第 7 章 / 共 12 章
用 CLAUDE.md 把项目规矩写给它
7.1 你不想每天说三遍的那些话
“这个项目用 pnpm 不用 npm。""测试跑 make test，不是 npm test。""不要碰 legacy/ 目录。”
如果你发现自己每开一个新会话都要重复这几句，那就该把它们写下来了。CLAUDE.md 就是干这个的：一个放在项目里的 Markdown 文件，会话启动时自动加载。
最快的起步方式是让它自己生成初稿：
/init它会分析代码库，生成一份 CLAUDE.md 草稿。但初稿只是初稿——下一节讲怎么把它删到有用。
7.2 加载顺序：五层记忆
CLAUDE.md 不止一个位置，它们按从宽到窄的顺序叠加：
| 层级 | 位置 | 放什么 |
|---|---|---|
| 组织管理策略 | 由 IT 统一下发 | 公司级红线 |
| 个人全局 | ~/.claude/CLAUDE.md | 你在所有项目里的偏好 |
| 项目共享 | ./CLAUDE.md | 团队约定，提交进版本库 |
| 项目本地 | ./CLAUDE.local.md | 只属于你的、不该进版本库的（记得加 .gitignore） |
| 子目录 | sub/CLAUDE.md | 只在这个模块成立的规矩，按需加载 |
还可以用 @ 语法把别的文件引进来，最多四跳：
# 项目约定
构建与测试命令见 @package.json
Git 流程见 @docs/git-workflow.md
我的个人偏好见 @~/.claude/my-style.md引用路径是相对包含这条引用的文件来解析的，不是相对当前工作目录。
7.3 该写什么，不该写什么
这是 CLAUDE.md 唯一真正重要的问题。官方给了一条检验标准，逐行拿它去问：
删掉这一行，会不会让 Claude 犯错？ 不会，就删掉。
| 该写 | 不该写 |
|---|---|
它猜不出来的命令（make test-integration） | 语言的标准约定（“Python 用 snake_case”） |
| 与默认不同的风格规则 | 从代码里一眼能看出来的东西 |
| 测试怎么跑、构建怎么跑 | 第三方库的 API 文档（给链接就行） |
| 分支与 PR 规范 | 逐个文件的功能描述 |
| 环境的坑（“本地要先起 docker-compose”) | 泛泛的鼓励语（“请写高质量代码”） |
官方给出的目标是控制在 200 行以内。这个数字不是硬限制，但越过它之后你会遇到一个反直觉的现象——文件越长，规则越不被遵守。官方文档的原话是：臃肿的 CLAUDE.md 会导致 Claude 忽略你真正的指令。
一份健康的 CLAUDE.md 大概长这样：
# 项目约定
## 命令
- 安装依赖：`pnpm install`（不要用 npm）
- 跑测试：`make test`
- 只跑单测：`make test-unit`
- 本地起服务前需要先 `docker compose up -d db`
## 代码
- API 层的错误一律走 `src/errors/AppError.ts`，不要直接 throw Error
- 数据库访问只允许出现在 `src/repositories/` 下
- `legacy/` 目录冻结，除非我明确要求，否则不要修改
## 提交
- 分支名：`feat/xxx`、`fix/xxx`
- 提交前必须跑 `make lint`
- 不要自动执行 `git push`7.4 两条诊断法则
当 CLAUDE.md 不起作用时，官方给了两个很准的判断：
- 它反复忽略某条规则 → 文件太长了，这条规则被淹没了。删掉别的，而不是把这条加粗。
- 它问了一个 CLAUDE.md 里已经写了的问题 → 那条写得有歧义，重写它。
还有一条关于强调的经验：在一行上写 IMPORTANT 是有效的；在二十行上都写，等于一行都没写。
用 /context 可以确认哪些记忆文件真的被加载进来了；/memory 可以直接编辑。
7.5 写不进 CLAUDE.md 的东西该放哪
CLAUDE.md 有一个结构性的局限：它每次会话都会全量加载。所以只有”每次都需要”的内容才配放在这里。
其他内容有更合适的去处：
| 内容性质 | 去处 | 理由 |
|---|---|---|
| 每次都要的项目约定 | CLAUDE.md | 必须常驻 |
| 偶尔才用的领域知识、复杂流程 | 技能（第 8 章） | 按需加载，不占常驻预算 |
| 必须每次强制执行的动作 | 钩子（第 8 章） | CLAUDE.md 是建议，钩子是强制 |
| 需要大量读取的调查 | 子代理（第 8 章） | 独立上下文 |
最后一行值得单独强调：CLAUDE.md 里的话是建议，不是保证。 如果某件事必须每次都发生（比如提交前必须跑格式化），写在 CLAUDE.md 里只能提高概率，用钩子才能变成确定性。
7.6 常见坑
7.7 本章练习与检查点
你现在的成果：新会话不再需要你交代背景。你已经把个人经验变成了项目资产——下一步是把重复的动作也变成资产。