claude.md怎么写才能让Claude Code更高效?

你给 Claude Code 写的那份说明书，可能三个月都没人改过

上个月我差点被一个项目气到摔键盘。

事情是这样的——Claude Code 进去之后，二话不说开始 yarn install，然后卡住了。我盯着终端看了十秒钟，脑子里全是问号。

后来打开项目根目录的 CLAUDE.md，好家伙，第一行写着“本项目使用 yarn 管理依赖”。

问题是——那个项目三周前就从 yarn 迁移到了 pnpm 啊。

没人改那个文件。

更绝的是，我扒了一下 git log，最近三个月压根没人动过 CLAUDE.md。

你想想：AI 一直照着过期的说明书干活，团队还纳闷“这玩意儿怎么越用越笨”……它不笨谁笨？

这事儿让我彻底想明白：CLAUDE.md 这东西，写得好能让你爽到飞起，写不好就是给自己挖坑。今天我把这几个月啃出来的东西拆成几个问题，一个一个说清楚。

问题一：是不是在项目根目录随便扔个 CLAUDE.md 就行？

太天真了。

最容易翻车的不是内容，而是——你放对地方了吗？

Claude Code 的配置分四个层级，优先级从低到高：

1. 全局级 ~/.claude/CLAUDE.md — 所有项目共享的通用习惯

2. 项目级 项目根目录的 CLAUDE.md — 检入 Git，团队共用

3. 模块级 子目录下的 CLAUDE.md — monorepo 里的大杀器

4. 内联级 对话里手写 @CLAUDE.md 引用

规则很简单：就近覆盖。模块级压过项目级，项目级压过全局级。

说个我踩过的坑——一开始我把所有规则全塞进根目录一个 CLAUDE.md，结果一个前端一个后端两个子项目互相污染：Claude 在前端目录里问后端的事，在后端目录里用前端的规范。那叫一个乱。

后来在 test/ 目录下单独配了 CLAUDE.md，写清楚：“测试文件不需要遵循主项目的架构规范，每个测试文件独立、自包含。”一句话，世界清净了。

还有个更灵活的玩法——.claude/rules/ 目录。按路径放规则文件，Claude 进到对应目录自动加载，你根本不需要在主文件里堆一堆 if-else。现在我的项目根目录 CLAUDE.md 大概 80 来行，只放通用规则；.claude/rules/ 下面按模块细分，每个文件 30 到 50 行。干净，清晰，省 token。

不过还有一个坑：新项目别指望第一次对话就变专家。

Claude Code 有个 /init 命令，在项目根目录跑一下，它会自动扫代码、读 README、推断技术栈，给你生一份 CLAUDE.md 草稿。但你要明白——这只是起点。真正好用的 CLAUDE.md 是“喂”出来的：Claude 犯一次错你就加一条规则，三个月之后的那个文件，才是你最有价值的 AI 资产。

问题二：能直接当 README 写吗？

大错特错。这是最普遍的误解。

我见过太多人直接在 CLAUDE.md 里写“本项目是一个电商后台管理系统，采用微服务架构，包含商品、订单、用户三个核心模块”。

这行字白占了 token，Claude 根本用不上。

你想想，AI 需要知道你项目叫什么名字吗？需要知道这是电商还是社交吗？它需要的是——“我应该怎么跑你”、“你要我怎么写代码”。

评判标准特别简单：写之前问自己——“这句话是给人看的还是给 Claude 看的？”

给人看的？写到 README 里去。

给 Claude 看的？技术栈、构建命令、测试命令、代码规范、项目特定的约定。就这些。

举个例子，我现在项目的 CLAUDE.md 开头长这样：

# 技术栈
- 语言: TypeScript 5.4
- 包管理器: pnpm（别用 npm，别用 yarn）
- 测试: Vitest（别用 Jest，当前项目没有 Jest 配置）
- 格式化: Biome（不是 Prettier）
- CI: GitHub Actions

# 命令
- 构建: pnpm build
- 测试: pnpm test（跑全部）
- 单文件测试: pnpm test -- <file path>
- Lint: pnpm lint:fix

# 代码规范
- 组件使用 React 函数组件 + hooks，不用 class 组件
- CSS 方案用 Tailwind，不写 `.css` 文件
- API 请求统一用 `/api/` 开头的 fetch 封装

每一行都有用。每一行都在告诉 Claude 怎么做，而不是描述项目在做什么。

有个哥们问过我：“那项目背景信息咋办？”

简单。写在 README 里。Claude Code 本身能读 README，你不需要在 CLAUDE.md 里重复。

另外还有个小技巧：如果团队同时用 Claude Code 和 Copilot，可以用 CLAUDE.md 引用 AGENTS.md。基础内容写一份在 AGENTS.md 里，CLAUDE.md 通过路径引用它，再追加 Claude Code 特有的规则。两边各读各的，不用维护两套重复内容。

问题三：能从网上复制个模板直接用吗？

可以复制，但别直接用。模板的问题比你想象的严重。

我从网上下载过一个挺受欢迎的 CLAUDE.md 模板，里面赫然写着：

- 遵循最佳实践
- 代码应有良好可读性
- 确保类型安全

全是废话。AI 看到“遵循最佳实践”就像人看到“好好工作”一样——听君一席话，如听一席话，等于没说。

更绝的是什么？模板里带着 、{{ ... }}、TODO 占位符没删，AI 会当真！我见过有人在 GitHub issue 里吐槽 Claude 总输出“TODO: implement this later”，查了半天，原来是 CLAUDE.md 里写着的。AI 以为这是指令。

那怎么搞？我推荐的做法：从真实项目分析入手。

先用 /init 让 Claude Code 扫描项目生成草稿，然后基于这个草稿删改。或者手动看 package.json、pyproject.toml、biome.json 这些配置文件，把真实的技术栈写进去。

具体到内容，我核心遵守三条铁律：

1. 具体可验证 — 不是“用好的测试实践”，而是“测试文件用 Vitest，mock 统一放在 __mocks__/ 目录”

2. 告诉 Why — 不只说“用 pnpm”，还要说“因为项目锁文件是 pnpm-lock.yaml，用 npm 会生成新的 lockfile 污染”

3. 持续更新 — 每次技术栈变化，第一时间同步到 CLAUDE.md

这三条是铁律，压过一切技巧。

问题四：是不是写得越多越好？

不是。200 行是黄金线，超了就是灾难。

这个数据来自 SFEIR Institute 的实测：CLAUDE.md 200 行时 AI 对规则的遵守率是 92%，400 行时直接掉到 70%。每多一行，注意力就被稀释一点。

我自己也试过。一开始满腔热血写了 400 多行，团队的各种约定全塞进去。结果呢？Claude 经常忽略关键规则，反而对边边角角的限制执行得很死。

后来一顿删，删到 180 行左右，遵守率明显上来了。

那删什么？三类内容直接清掉：

1. 复述型 — 重复 README 已有的内容。Claude Code 能自己读 README，不需要你替它总结。

2. 愿望型 — “希望代码优雅”“期望有良好架构”。AI 理解不了抽象愿望，只会执行具体指令。

3. 术语表型 — 把项目专用术语全部列一遍。除非这些术语会影响代码生成（比如“User”和“Customer”在代码里必须严格区分），否则没必要写。

那想多写怎么办？拆！

一个 500 行的 CLAUDE.md 不如 10 个 50 行的 .claude/rules/ 文件。按模块、目录、任务类型拆分，每个文件聚焦一件事。Claude 进入对应目录时自动加载，加载的就是精准的上下文。

我的做法：

• 根目录 CLAUDE.md：80 行，通用规则
• `.claude/rules/`：按路径分，每个文件 30-50 行
• 总规则数控制在 200 行以内

实测遵守率明显比之前好。

问题五：写完就不用管了吧？

这是最隐蔽的坑，没有之一。CLAUDE.md 会过期，而且过期的时候什么都不会发生。

你想想，代码出问题有反馈——测试挂了，CI 变红，type checker 报错。但规则文件出问题是静默的——AI 照旧执行，只是执行的是一份过期的说明书。

这个差别太要命了。

我前面说了三个月没动过的 CLAUDE.md 例子。那之后我养成了一个习惯：每次技术栈变动，第一时间更新 CLAUDE.md。 不只是改版本号，连推荐的命令、工具的用法都要同步。

更绝的是，Claude Code 还有一个Auto Memory 机制。Claude 自己会记笔记——你的构建命令偏好、代码风格倾向、踩过的坑和解决方法。这些存在 ~/.claude/CLAUDE.md（用户记忆）和 ./CLAUDE.md（工程记忆）里。

你可能用了几天后打开 ~/.claude/CLAUDE.md，发现里面多了一堆你没写的东西。

不要慌，那是 Claude 自己记的。

输入 /memory 可以查看和编辑这些自动记忆。我现在每两周检查一次，删掉过时的，保留有用的。CLAUDE.md 是你给 Claude 的入职手册，Auto Memory 是 Claude 自己的工作笔记，两者配合起来效果 1+1>2。

几个你可能没想到的问题

1. CLAUDE.md 和 AGENTS.md 到底啥关系？

AGENTS.md 是 GitHub 定义的规范，给 Copilot 的 Agent 用的。CLAUDE.md 是 Anthropic 定义的，给 Claude Code 用的。两家的 Agent 各自认自家的文件名。

两边都用的项目怎么办？我前面提了桥接方案——基础内容写 AGENTS.md 里，CLAUDE.md 引用它，再追加 Claude Code 特有的规则。

现在 AGENTS.md 正在演变成通用的 AI Agent 配置文件标准，但 Claude Code 的最佳选择仍然是 CLAUDE.md，它有更强大的专属内置指令。

2. Skills 和 Slash Commands 是啥？和 CLAUDE.md 有啥区别？

很多人搞混。

CLAUDE.md 是静态的“入职手册”——描述项目的固定信息。Skills 是可复用的工作流程——比如“如何添加新页面”。Slash Commands 是快捷指令——比如自定义一个 /review 自动跑代码审查。

我刚开始做的时候把所有流程都塞进 CLAUDE.md，越塞越胖。后来把流程型的内容抽成 Skills，把高频操作抽成 Slash Commands，CLAUDE.md 回归到只做“上下文说明”，结构清晰得多。

3. Claude Code 的重试系统其实挺能扛的

这算是个彩蛋知识点。Claude Code 最多能重试 10 次，带指数退避加抖动，基准 500ms。遇到 401/403 自动刷新 OAuth token。Opus 连续 3 次 529 错误自动降级到 Sonnet。流式输出 90 秒没响应自动切到非流式。

实际体会就是：API 抖动、限流、短期故障，它会自己处理，你不用盯着。设好规则文件，让它在后台跑，过一会回来拿结果就行。

说实话，真正拉开用户差距的，不是谁更会写 prompt，而是谁开始把 Claude Code 当成一套“可配置的开发基础设施”来用。

前置规则设计、并行任务拆分、跨会话的上下文经营——这些才是值得你花时间琢磨的地方。

先写这么多。CLAUDE.md 这个东西，写三个月和写三个小时的差别，你自己试了就知道。

别忘了——最好的 CLAUDE.md，不是今天写完就完美的那份，而是三个月后还在被你持续改进的那份。

附：上面提到的实测数据来源和完整配置模板我放在了参考资料里，有需要自己去翻。