CLAUDE.md 才是这套系统的灵魂：程序员视角的深度配置指南

CLAUDE.md 才是这套系统的灵魂：程序员视角的深度配置指南

作者：一只阿木木

你有没有过这种经历：

和 Claude 聊了三个小时，把项目背景解释了个透彻，得到了很棒的回答。 第二天开启新对话，一切归零。你又要重新解释一遍。

这不是 Claude 的问题，这是 AI 工具的结构性限制——14每个 Claude Code 会话都从全新的上下文窗口开始。

但这个问题，有一个优雅的工程解法——CLAUDE.md。

大多数人知道 CLAUDE.md 的存在，却把它当成一个简单的"提示词文件"随手糊弄几行。这是巨大的浪费。CLAUDE.md 是这套 AI 工作流系统的灵魂，写得好与写得差，产出质量可以差出一个数量级。

1. CLAUDE.md 的本质：不是提示词，是项目宪法

CLAUDE.md 是 Claude 对你项目的永久记忆。写一次，Claude 就能在每次对话中都了解你的项目上下文——不需要重新解释。关键认知：CLAUDE.md 是你项目的宪法——不可变的规则，凌驾于临时提示之上。提示词是灵活的请求，CLAUDE.md 建立的是最高法则。

用程序员更熟悉的类比来说：

• 你的代码 = 对话内容（临时的，每次运行后消失）
• CLAUDE.md = 编译器配置 / .eslintrc（永久的，每次运行前都会加载）

CLAUDE.md 文件在每次会话开始时被加载进上下文窗口，与你的对话一起消耗 token。这意味着它的内容是有成本的，也意味着它的内容需要高度精炼，而不是把所有内容都堆进去。

2. 它是如何被读取的？先搞清楚加载机制

很多人不知道，CLAUDE.md 其实有四层加载层级：

~/.claude/CLAUDE.md # 第1层：全局（你所有项目） 
/project-root/CLAUDE.md # 第2层：项目级 
/project-root/frontend/CLAUDE.md # 第3层：子目录级 
/project-root/CLAUDE.local.md # 第4层：个人（被 .gitignore）

这几层叠加生效（不是替换），更具体的层级在冲突时优先生效。

对程序员来说，这个层级结构意味着什么？

实践建议：

3. 大多数人 CLAUDE.md 写得烂的真正原因

在看如何写好之前，先诊断"写烂了"的典型症状：

症状 A：太模糊

# 坏示例
请用我熟悉的编程风格回答问题，关注代码质量。

这没有任何信息量。Claude 不知道你的"熟悉风格"是什么，也不知道"代码质量"对你来说意味着什么。

症状 B：太长

官方文档给出的建议是：每个 CLAUDE.md 文件目标控制在 200 行以内。文件越长，消耗的上下文越多，遵从度越低。 

CLAUDE.md 是静态 Markdown，在会话开始时加载，适合存放项目规则和偏好，但在大约 200 行之后遵从度就会下降。

你把所有东西堆进去，反而会让 Claude 在"应该遵守哪条规则"上变得困惑。

症状 C：全是说明，没有约束

Markdown

# 还是坏示例
这个项目使用 TypeScript 和 React。我们有一个后端 API。

这是描述，不是规则。CLAUDE.md 最有价值的部分，是明确的约束和禁止项。

4. 程序员专属 CLAUDE.md 完整配置指南（附模板）

schema（即 CLAUDE.md）是告诉 LLM wiki 结构是什么、约定是什么、以及在摄入来源、回答问题或维护 wiki 时应遵循什么工作流的文档。这是核心配置文件——它让 LLM 成为一个有纪律的 wiki 维护者，而不是一个通用聊天机器人。你和 LLM 会随着时间的推移共同演化它，随着你弄清楚什么对你的领域有效。

下面是一套可直接复制使用的程序员专属 CLAUDE.md 模板，分为五个模块：

模块一：技术栈声明（必填，越具体越好）

Markdown

## 技术栈
- 语言：TypeScript 5.x，严格模式（strict: true），禁止使用 any
- 运行时：Node.js 20 LTS
- 框架：Next.js 14 App Router（不是 Pages Router）
- 数据库：PostgreSQL + Prisma ORM
- 测试：Vitest + React Testing Library
- 包管理器：pnpm（禁止使用 npm 或 yarn）

模块二：代码风格约束（用"禁止"比"推荐"更有效）

Markdown

## 代码约束（执行级）
- 禁止：console.log 提交到生产代码
- 禁止：未经处理的 Promise rejection（必须有 try/catch 或 .catch()）
- 禁止：超过 80 行的函数，超过 300 行的文件（必须拆分）
- 必须：所有 async 函数显式处理错误
- 必须：zod 做运行时数据校验，不用手写 if (typeof x === ...)
- 必须：提交前运行 pnpm test && pnpm typecheck

模块三：架构决策记录（ADR 集成——这是程序员专属的核心价值）

Markdown

## 架构决策（已定，不要质疑）
- 状态管理：Zustand（2024-03 决策，排除了 Redux 和 Jotai）
  原因：包体积最小，TypeScript 类型支持最好
- API 层：tRPC（2024-05 决策）
  原因：端到端类型安全，消除手写 API 类型的负担
- 样式：Tailwind CSS + shadcn/ui（不使用 CSS Modules 或 styled-components）
## 禁止重新讨论以上决策，除非我明确说"我们重新评估 X"

模块四：跨项目知识引用（与 claude-obsidian 知识库联动）

Markdown

## 个人知识库
路径：~/obsidian-vault/wiki/
当我的问题需要更深的上下文时，按以下顺序读取：
1. wiki/hot.md（当前最活跃的工作记忆）
2. wiki/index.md（全局知识索引）
3. wiki/entities/[相关技术名].md
相关 wiki 页面：
- [[tokio]] [[async-std]]（Rust 异步调研，2024-11）
- [[nextjs-app-router-patterns]]（Next.js 架构模式笔记）

模块五：输出风格约束（减少废话，直接上代码）

Markdown

## 回答风格
- 不要在代码前写"当然可以！"或"这是个好问题！"
- 先给结论，再给解释（Bottom Line Up Front）
- 代码示例：完整的、可直接运行的，不要 // ... existing code ...
- 如果有多个解法，给出对比表格，而不是分段解释
- 估计 token 消耗：解释型回答优先用 bullet points，不用长段落

5. 一个让大多数人忽视的高级用法：@import 语法

CLAUDE.md 可以用 @ 符号引用其他文件。被引用的文件会作为独立条目插入到上下文中，排在包含它的文件之前。例如：

Markdown

# 项目 CLAUDE.md
@./docs/architecture.md
@./docs/conventions/typescript.md
提交前始终运行 `bun test`。

这意味着什么？你可以把 CLAUDE.md 变成一个"目录"，而不是一个"大文件"。

更好的实践是把规则拆分到 .claude/rules/ 子目录下：

text

project/
├── CLAUDE.md          ← 只有 30 行，引用以下规则文件
└── .claude/
    └── rules/
        ├── typescript.md     ← TypeScript 专属规则
        ├── testing.md        ← 测试规则
        ├── git-workflow.md   ← Git 工作流规则
        └── api-design.md     ← API 设计规则

如果你的指令越来越多，可以使用路径范围规则，这样指令只在 Claude 处理匹配文件时才加载。这样，typescript.md 里的规则只在处理 .ts 文件时被加载，不会一直占用你的上下文窗口。

6. 与 claude-obsidian 集成：把个人 wiki 变成所有项目的共享大脑

这是最终形态，也是这套系统最强大的地方。

在任何项目里，你只需要两个命令：

Bash

# 写入：提炼你学到的东西
/wiki-update
# 读取：拉取你之前积累的上下文
/wiki-query "我对 rate limiting 了解多少？"

/wiki-update 读取你的项目，找出值得保留的内容，将其提炼进你的 Obsidian vault——架构决策、你发现的模式、关键概念、你评估过的权衡。它不会复制代码或转储文件列表，它提炼的是你三个月后会遗忘的东西。

在 ~/.claude/CLAUDE.md（全局层）里添加这段配置，就能让你的个人知识库在所有项目里都可用：

Markdown

## 跨项目知识库（全局）
路径：~/my-obsidian-vault/wiki/
每次会话开始时：
1. 读取 wiki/hot.md（最近工作记忆，约 500 词）
2. 如果当前项目与已有 wiki 页面有关，主动引用相关页面
3. 每次有新的技术决策时，询问我是否要更新 wiki
这个知识库包含：
- 技术选型调研结论（entities/）
- 架构模式笔记（concepts/）
- 跨项目可复用的代码片段分析（synthesis/）

 Auto Memory 让 Claude 在不需要你手动写任何东西的情况下，跨会话积累知识。Claude 在工作时自动保存笔记：构建命令、调试洞察、架构说明、代码风格偏好和工作流习惯。配合 CLAUDE.md 里的手动规则，你就拥有了自动积累 + 精准约束的双重记忆体系。

7. 写好 CLAUDE.md 的五条铁律

最后，提炼成五条可以贴在显示器上的铁律：

铁律 1：用约束语言，不用描述语言 不写"我喜欢简洁的代码"，写"禁止超过 80 行的函数"

铁律 2：控制在 200 行以内

具体、简洁、结构良好的指令效果最好。宁可拆分成多个文件，也不要塞成一个大文件。

铁律 3：把"已定决策"单独成节，明确写"禁止质疑" 这能节省你大量时间——不然 Claude 每次都会"友情提醒"你也许可以考虑用 Redux。

铁律 4：在 CLAUDE.local.md 里放本地私密配置 本地数据库地址、个人 API Key 的路径、你的沙盒环境 URL——这些绝对不能提交 Git。

铁律 5：随项目演化，定期回顾

你和 LLM 会随着时间的推移共同演化这份文件，随着你弄清楚什么对你的领域有效。每个月末检查一次：哪些规则过时了？哪些新约定需要固化？

写在最后

CLAUDE.md 不是一份文档，是你和 AI 协作关系的契约。

写得模糊，你就会一直陷入"重新解释上下文"的西西弗斯困境；写得精确，Claude 就会成为一个真正了解你、了解你项目、了解你技术偏好的协作者——在任何一个新项目、任何一次新会话里。

我是阿木木。在 AI 时代，配置好你的工具，让它真正为你所用。