CLAUDE.md 写法大全：11 级优先级与我踩过的三个大坑

第一次用 Claude Code 的时候，我根本不知道 CLAUDE.md 是干啥的。项目根目录莫名其妙多了个文件，我以为是 Claude Code 的缓存，还一度想把它丢进 .gitignore。

后来在一次协作翻车之后我才意识到这东西有多重要。那次的情况是：我和同事在同一个 repo 里协作，我本地跑 Claude Code 改一个接口改得风生水起，他拉下来跑的时候却发现 Claude Code 一直把代码往完全错误的方向推。排查了俩小时才搞明白——我本地有一份 CLAUDE.md，里面写了一堆项目约定；他没有这份文件（我没 commit），所以他的 Claude 完全不知道这个项目的规矩，只能按通用最佳实践瞎写。

从那天起我开始认真研究 CLAUDE.md。这东西本质上是给 Claude Code 的项目说明书，写得好能让 AI 协作翻倍提效，写得不好能把 AI 带到沟里。这篇把我这半年的经验总结一下。

一、CLAUDE.md 是什么，为什么重要

简单说，CLAUDE.md 是 Claude Code 在启动时会自动读入、作为 system context 的一部分注入到模型的文件。它告诉 Claude：

• 这个项目用什么技术栈
• 代码风格有什么约定
• 哪些文件/目录不能动
• 常用命令是什么（跑测试、部署、lint）
• 有什么”坑”要提前知道

它解决的核心问题是：让 Claude 在一个陌生项目里不再按通用默认行事，而是按这个项目的规矩行事。

你可以理解成”给新人入职的 README，只不过读者是 AI”。

但和 README 有一个关键区别——README 是可选阅读，CLAUDE.md 是强制注入。意味着你写进去的每一个字都会消耗 token、都会影响模型行为。这就决定了 CLAUDE.md 不能当 README 写，它必须更精炼、更有指令性。

二、11 级优先级：从哪读到哪

这个东西官方文档藏得有点深，我整理一下我理解的顺序（从高到低，高优先级会覆盖低优先级）：

1. 当前命令的 CLI 参数 —— 最高优先级，临时强制
2. .claude/settings.local.json —— 本地机器的 Claude 配置（不入 git）
3. 项目根 CLAUDE.md —— 当前项目规则
4. **父目录 CLAUDE.md**（monorepo 场景）
5. 祖父目录 CLAUDE.md —— 依次往上找到 repo 根或 home
6. ~/.claude/CLAUDE.md —— 用户级全局配置
7. .claude/settings.json —— 项目共享配置
8. ~/.claude/settings.json —— 用户全局配置
9. 环境变量（如 ANTHROPIC_MODEL）
10. Claude Code 内置默认
11. 模型本身的 default behavior —— 最底层兜底

这个顺序不用硬记，但要理解两条核心原则：

• 越具体、越靠近当前文件的，优先级越高
• 项目级（CLAUDE.md）和用户级（~/.claude）会叠加，但冲突时项目级优先

实际用起来有一个容易忽略的细节——Claude Code 在启动时会自顶向下把所有层级的 CLAUDE.md 串联起来，不是只读最近的那一份。这意味着你在子目录里的 CLAUDE.md 不是”覆盖”祖父目录的，而是”追加”。如果祖父目录写了”代码注释用中文”，子目录里不写相关规则，那中文注释规则依然生效。

这个机制在 monorepo 场景下特别有用。你可以在 repo 根写通用规则（”所有包都用 TypeScript strict 模式”），然后在每个 package 子目录里写各自的特殊规则（”api 包禁止引入 zod 之外的 validation 库”）。

三、坑 1：写得太多，反而把 Claude 整懵了

这是我第一个大坑。发现 CLAUDE.md 好用之后，我开始往里面疯狂写东西——项目架构、技术栈细节、每个目录的作用、每个核心函数的职责、过往几次重构的历史……写到快 2000 行。

然后 Claude Code 开始变得又慢又飘。

原因很简单：CLAUDE.md 是要完整注入到每次请求的 context 里的。你写 2000 行，意味着每次 Claude 启动都要消化这 2000 行。问题是：

• 信息太多，重点被稀释。关键规则（比如”不要改 legacy_util.py”）被淹没在一堆描述性内容里
• Token 成本爆炸。2000 行大概 15K token，每次请求都是这个基础成本
• **模型开始”过度解读”**。写得越多，Claude 越容易从无关内容里脑补奇怪的推论
• 维护成本翻倍。项目演化时，你要同步更新 CLAUDE.md，内容越多越容易遗漏

我后来把 CLAUDE.md 砍到 150 行以内，执行规则、关键约束、常用命令——其他什么都不写。效果立刻恢复正常，而且 Claude 的判断更稳定了。

原则：CLAUDE.md 写关键信息，不写全部信息。详细架构文档放 docs/ 目录，让 Claude 需要的时候自己去读。你可以在 CLAUDE.md 里留一句：需要深入了解架构时，请先阅读 /docs/architecture.md，把”读不读”的判断权交给模型。

有人问过我具体怎么判断该不该写进 CLAUDE.md。我的标准是——如果 Claude 不知道这条规则就有可能写出错误代码，才写进去；如果只是”知道了更好”的背景信息，不写。这个筛选标准帮我砍掉了 80% 的冗余内容。

四、坑 2：user 级和项目级配置打架

第二个坑更隐蔽。

我在 ~/.claude/CLAUDE.md 里写了我个人的偏好——比如”回答我时默认用中文””代码注释用中文””import 顺序按 isort 风格”等等。这是我的个人习惯。

但有一次我接了一个外包项目，他们的 repo 里有自己的 CLAUDE.md，明确写了”代码注释一律英文”。结果：我本地 Claude 写出来的代码里，注释一会儿中文一会儿英文，完全不统一。

排查后发现问题是——两个文件的规则都被注入了，然后 Claude 自己做了一个折中：”一部分用中文，一部分用英文”。

解决思路：

**1. 把 user 级 CLAUDE.md 写成”偏好”而不是”规则”**。
用 “我通常更喜欢…” 这种语气，不用 “必须…” 这种硬性措辞。这样项目级规则能比较干净地覆盖它。

2. 项目级 CLAUDE.md 明确声明优先级。
我现在写项目级 CLAUDE.md 的第一行一般是：

1
2
3

# 项目规则

本文件中的所有规则优先于 user-level CLAUDE.md。冲突时以本文件为准。

显式写出来，模型会认账。

3. 真的要强制，用 --override-user-memory 启动参数（这个 flag 从某个版本开始支持，具体版本号我不确定，先试再说）

4. 做好 user 级配置的定期清理。
我现在每季度会把 ~/.claude/CLAUDE.md 重读一遍，删掉那些已经不符合自己当前工作习惯的老规则。这个文件一旦塞多了很容易被遗忘，时间一长就变成各种项目的”通用毒瘤”。

再补一个小技巧：如果你经常切换不同客户/团队的项目，可以在 ~/.claude/CLAUDE.md 里完全不写任何强规则，只写自己的语言偏好和沟通风格偏好。技术决策全部交给项目级 CLAUDE.md 去定，冲突就少了。

五、坑 3：@include 循环与隐式依赖

CLAUDE.md 支持 @path/to/file 语法，可以把其他文件的内容拉进来。这玩意儿很强大，但我踩过一个搞笑的坑。

当时我为了复用，把一些通用规则写在 ~/.claude/common.md 里，然后 user 级 CLAUDE.md 里写：

1

@~/.claude/common.md

项目级 CLAUDE.md 里也想复用，又写：

1

@~/.claude/common.md

结果 common.md 被 include 了两次，规则重复。Claude 看到”代码风格 A”出现两次，当作重要信号，反而开始过度强调这个规则。

更惨的情况是：我有一次 common.md 里 include 了 base.md，base.md 里又 include 了 common.md，形成循环。Claude Code 直接报错启动不了。

原则：

• @include 要有层级意识。下游 include 上游，不要互相 include
• 不要重复 include 同一个文件
• 深层嵌套尽量避免。一级 include 够用了，两级以上容易出事
• include 进来的内容也要算 token。有人以为 @include 是懒加载——错了，是 eager 的，启动就全部注入

一个实用建议：如果你想做规则复用，与其用 @include，不如用 shell script 在启动时生成 CLAUDE.md。把”规则碎片库”放在一个统一目录，写一个脚本根据当前项目类型拼装出定制化 CLAUDE.md。这比 @include 的控制力强一个数量级。

六、一个我实际在用的 CLAUDE.md 模板

这是我现在大部分 Node / TypeScript 项目的骨架：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# [项目名] — CLAUDE.md

本文件优先于 user-level CLAUDE.md。

## 项目本质
一句话说明这个项目是做什么的。

## 技术栈
- Runtime: Node 20
- Framework: Fastify 5
- ORM: Drizzle
- Test: Vitest

## 关键约束
- 所有对外 API 必须有 zod schema 校验
- 禁止引入新的第三方 validation 库（我们用 zod）
- 数据库迁移走 drizzle-kit，不手动改 schema

## 不要改
- `/src/legacy/` 目录下所有文件（迁移中，容易出事）
- `package.json` 里的 node 版本

## 常用命令
- 跑测试：`pnpm test`
- 起开发：`pnpm dev`
- 数据库迁移：`pnpm db:migrate`

## 风格
- import 用绝对路径（`@/xxx`）
- 错误用 Result 类型，不 throw
- 文件名用 kebab-case

## 遇到不确定的时候
- 先看 `/docs/architecture.md`
- 新增 API 前先看 `/src/api/_template.ts`

这份大概 50 行左右。不追求完整，追求关键。

展开一下每个小节的写作原则：

• 项目本质：一句话就够，目的是给 Claude 一个定位锚点
• 技术栈：只列关键版本，不写”为什么选这个”
• 关键约束：写死的红线，违反了一定有问题
• 不要改：负面清单，明确点名
• 常用命令：Claude 要跑测试、lint 时直接复制这些命令，不用猜
• 风格：写 3-5 条最重要的风格偏好，多了反而模糊
• 遇到不确定的时候：告诉 Claude 要去哪看，相当于给它的”自助服务入口”

七、配合 Claude Code 的几个小技巧

1. 把 CLAUDE.md 放进 git。
这应该是常识但很多人不做。这东西不 commit，团队协作就废了。

2. 定期 review。
项目演化，CLAUDE.md 也要演化。我每两周会打开 CLAUDE.md 看一眼，删掉已经不适用的规则、补上新的坑。这东西不是一次性写完就完事的。

3. 新人加入项目时让 Claude 读一遍 CLAUDE.md 做导读。
这招挺好用——直接让 Claude 基于 CLAUDE.md 给新人做一次项目 walkthrough，省了半天时间。

**4. 结合 .claude/commands/**。
把常用的 prompt 做成 slash command，这块和 CLAUDE.md 配合使用效率爆炸。详细玩法我之前在 Claude-Code 分类 下的几篇文章里讲过。

**5. 给 CLAUDE.md 加一个”更新日期”**。
在文件顶部或底部写一行 最后更新：2026-04-15，Claude 看到会自动把这个时间点作为”当前项目约定的参考线”。老旧 CLAUDE.md 如果没标时间，很容易误导模型。

**6. 善用 CLAUDE.md 做 Claude 的”行为纠偏”**。
如果你发现 Claude 某个行为反复让你不爽（比如老是主动改你没让改的文件），就在 CLAUDE.md 里加一条明确禁止。这个文件不仅是项目说明，也是你和 Claude 之间的”行为协议”。

八、最后

CLAUDE.md 这个东西的价值，在于它让 AI 协作有了项目特化的能力。通用大模型有它的通用智能，但每个项目有每个项目的土规矩，这些土规矩靠 prompt 临时讲讲讲不完，靠文档让 AI 自己去读效率又低——CLAUDE.md 就是那个固化土规矩的载体。

写好它的核心心法就一句话：写关键信息，不写全部信息；写规则，不写描述。

想看更多 Claude Code 的实战玩法，claudecode.cocoloop.cn 是一个专门做深度内容聚合的站点，我平时也会去翻那边的更新；想看国内 AI 工程师社区的讨论可以去 ask.cocoloop.cn 看看。

再送一个彩蛋——CLAUDE.md 其实也适合用在非 Claude Code 的场景。我现在很多个人项目的仓库根目录都放一份 CLAUDE.md，哪怕我暂时不用 Claude Code，只是用网页版 Claude。需要让 AI 理解这个项目时，直接把 CLAUDE.md 内容贴进对话框作为 system prompt 就好了。这个文件正在慢慢变成一种跨工具的项目元信息标准。