CLAUDE.md 怎么写: 提升 Claude Code 准确率的最小有效配置

社区里流传一句很有冲击力的话：某个项目把 Claude Code 的「准确率从 41% 升到 89%」，靠的只是改了一个 CLAUDE.md。这个数字来自热点原帖的说法，没有公开的评测方法和样本量，我们不把它当作实测基准。但它指向的那件事是真的，而且每个用 Claude Code 写过几天代码的人都体感得到：同一个模型、同一个仓库，给不给项目说明，输出质量差出一个档。

这篇文章不复述那个跑分故事，而是把它背后的工程问题讲透——CLAUDE.md 到底凭什么影响准确率，一个有效的 CLAUDE.md 该包含哪些块、删掉哪些块，根目录和子目录怎么分层，以及大多数人写它时会踩的几个坑。文末给一份可以直接拿走改的模板骨架。

为什么一个文本文件能改变准确率

TL;DR

CLAUDE.md 是 Claude Code 在每次会话启动时自动读入、拼进系统上下文的项目说明文件。它不是文档，是接口——你用它把「这个项目的真实约束」喂给模型，模型据此决定怎么写代码、跑什么命令、碰什么不能碰。写得准、写得短，模型就少猜；写得乱、写得长，模型的注意力被稀释，反而更容易跑偏。提升准确率的核心不是「写更多」，而是「写对的那几条，并且保持它不过期」。

机理：这其实是一道上下文工程题

要理解 CLAUDE.md 为什么有用，得先承认一个事实：大模型对你的项目一无所知。它不知道你的构建命令是 pnpm build 还是 make，不知道你这个仓库里 utils/ 已经废弃、新代码要写进 lib/，不知道你团队约定「不准在 /tmp 留 .php」。没有这些信息时，模型只能靠先验去补——也就是从训练语料里见过的「大多数项目长什么样」来猜你的项目。猜对了是运气，猜错了就是你要返工的那一段。

CLAUDE.md 做的事，是把模型从「靠先验猜」拉到「靠现场事实推」。这正是上下文工程的核心命题：模型的能力上限由权重决定，但单次任务的发挥由你喂进上下文的信息决定。同一个 Claude，在一个有清晰 CLAUDE.md 的仓库里像个熟悉代码库的同事，在一个空仓库里像个第一天入职、谁也没给他讲过规矩的外包。

这里有个容易被忽略的反向效应：上下文不是越多越好。模型的注意力是有限资源，你塞进 CLAUDE.md 的每一个字都在和真正重要的约束抢注意力。一份 600 行、把环境变量、历史决策、未来规划全堆进去的 CLAUDE.md，效果往往不如一份 80 行、只讲清楚「项目结构 + 关键命令 + 三条红线」的精简版。这就是为什么这篇文章反复强调最小有效——目标是信噪比，不是信息量。

如果你对「模型重新打开仓库时从哪里恢复记忆」这件事感兴趣，Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换把长项目的上下文恢复问题讲得更系统，CLAUDE.md 正是其中最便宜的一环。

一个有效的 CLAUDE.md 该有哪些块

下面逐块拆。每一块都给「为什么需要」和「示例写法」，但请记住：不是每个项目都要全装上，按你仓库的实际复杂度取舍。

块一：项目是什么（一两句话定位）

模型需要先知道它在跟什么打交道。一句话说清楚这是个什么项目、用什么技术栈、解决什么问题。不要写市场宣传语，写工程事实。

## 项目
基于 Next.js 14 (App Router) + TypeScript 的内容站。
数据源是本地 Markdown，构建期静态生成。无后端数据库。

这三行的价值在于：模型从此知道「这里没有数据库」，就不会给你写出连 Prisma 的代码。

块二：项目结构（只标关键目录，不复述文件树）

不要把 tree 的输出贴进来——那是噪音。只标注那些「模型必须知道、否则会写错位置」的目录约定。

## 结构
- `lib/`：核心逻辑，新代码写这里
- `utils/`：已废弃，不要往里加东西
- `content/`：Markdown 内容源，构建期读取
- `app/api/`：路由处理，每个文件一个 endpoint

注意「utils/ 已废弃」这种负向约定往往比正向说明更值钱，因为它消除了模型一个最常见的错误猜测。

块三：关键命令（构建、测试、lint）

模型经常需要自己跑命令验证改动。如果你不告诉它命令是什么，它会去猜——猜 npm test 结果你用的是 vitest，猜 npm run build 结果你用的是 pnpm。把这几条钉死：

## 命令
- 装依赖：`pnpm install`
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（vitest）
- 类型检查：`pnpm typecheck`

这一块对「让模型自己验证」的工作流尤其关键。模型能自己跑测试、读报错、再修，这条闭环的起点就是它知道该跑什么命令。

块四：代码风格与约定

不要把整个 ESLint 配置抄进来——那有 lint 工具管。这里写的是工具检查不出来、但你团队真在乎的约定。

## 约定
- 组件用函数式 + hooks，不写 class 组件
- 异步用 async/await，不用 .then 链
- 错误处理：API 层统一 try/catch，不在组件里裸 fetch
- 文案中文用全角标点，代码注释用中文

块五：做什么 / 不做什么（红线）

这是整份文件里密度最高的一块，也是最能拉准确率的一块。把那些「做错了代价很大、回滚很贵」的边界明确列出来。

## 红线
- 不要改 `config/legacy.ts`，那是兼容层，动它会炸老用户
- 不要在未问的情况下升级主版本依赖
- 提交信息用 conventional commits 格式
- 数据库迁移必须可回滚，不写不可逆的 DROP

这一块的写法直接决定了模型会不会闯祸。红线越具体，模型越不容易在你没盯着的时候做出难以挽回的操作。关于「用流程规范约束 AI 行为」，开发者反击”自私”的 AI 滥用：用表情符号暗号与流程规范对抗 LLM 垃圾内容提供了一个更激进的社区视角，本质上和这里的「红线」是同一类思路。

块六：按需加载的子文档索引

CLAUDE.md 本身要短，但有些信息（数据库 schema、复杂模块的设计文档、踩坑记录）确实需要存在。解法是索引而非内联：在主文件里只放一行指针，告诉模型「需要时去读哪个文件」。

## 关键文档（按需加载）
- `docs/db-schema.md`：数据表结构，涉及数据层任务时读
- `docs/auth-flow.md`：鉴权流程，改登录相关时读
- `docs/deploy.md`：部署流程与回滚步骤，发布前读

这样主文件保持精简，详细信息又不丢失。模型会在判断任务相关时主动去读那些子文档，而不是一上来就被几千字的 schema 占满上下文。

目录约定与分层：根 CLAUDE.md 不是唯一一份

很多人不知道 CLAUDE.md 可以分层。Claude Code 不只读根目录那一份，它会沿着你当前工作的目录路径，把沿途的 CLAUDE.md 都纳入上下文。这给了你一个很自然的「就近说明」机制。

根目录 CLAUDE.md：全局约定

放整个仓库都适用的东西：技术栈、全局命令、跨模块的红线、团队风格。这一份要尽量稳定，不该频繁改动。

子目录 CLAUDE.md：局部上下文

在一个有独立约定的子目录里放一份局部 CLAUDE.md。比如你的 packages/web/ 和 packages/cli/ 用不同的测试框架、不同的发布流程，就各放一份，写各自的局部规则。模型在 packages/web/ 下干活时，自然带上 web 包的上下文，不会被 cli 包的规则干扰。

这种分层的好处是信息局部性：每一份文件只对它管辖的范围负责，既避免了根文件无限膨胀，也避免了模型在写 A 模块时被 B 模块的无关信息分心。这其实和「模块化管理配置」是同一个工程直觉——社区里关于配置组织方式的讨论一直没停，开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹就是一例，分层 CLAUDE.md 是 Claude Code 自带的、最轻量的模块化手段。

如果你同时在用多个 AI 编程工具，配置分散是个真问题。社区已经有人在做聚合管理，比如聚合管理AI编程客户端配置，开源工具SMRmanager v0.2发布和早一点的开源神器 SMRmanager：一键统一管理 Claude、Cursor 等 AI 编程工具配置，思路是把多工具的配置集中起来。不过对单一 Claude Code 项目来说，先把分层 CLAUDE.md 写好，收益更直接。

一份可复用的模板骨架

下面是一个可以直接拿走改的根目录 CLAUDE.md 模板。它是示例/参考写法，不是官方规范——Claude Code 对 CLAUDE.md 的内容没有强制 schema，你完全可以增删块。保持它在 100 行以内，是这份模板想传达的纪律。

# CLAUDE.md

## 项目
<一两句话：什么项目、什么栈、解决什么问题、有没有后端/数据库>

## 结构
- `src/`：<职责>
- `<已废弃目录>/`：不要往里加东西
- `<内容/配置目录>/`：<构建期还是运行时用>

## 命令
- 装依赖：`<cmd>`
- 开发：`<cmd>`（端口 <port>）
- 构建：`<cmd>`
- 测试：`<cmd>`（<框架>）
- lint / 类型检查：`<cmd>`

## 约定
- <工具检查不出、但团队在乎的风格 1>
- <约定 2>
- <约定 3>

## 红线（做错代价大、回滚贵）
- 不要改 `<敏感文件>`，原因：<...>
- 未经确认不要 <危险操作>
- 提交信息用 <格式>
- <可回滚要求>

## 关键文档（按需加载）
- `docs/<x>.md`：<什么时候读>
- `docs/<y>.md`：<什么时候读>

子目录 CLAUDE.md 更短，通常只需要「局部命令 + 局部约定 + 局部红线」三块，全局信息靠根文件继承，不要重复。

值得强调的是：模板是起点不是终点。第一版写出来后，真正让它变准的是迭代——你每次发现模型又跑偏了，就回头问「CLAUDE.md 里缺了哪条说明，导致它这么猜」，把那条补上。几轮之后，这份文件会收敛成你这个项目专属的、密度极高的说明书。这个「发现偏差 → 补一条 → 收敛」的循环，和工程团队用 AI 重写核心模块时的迭代方式是相通的，PostHog 工程实录：利用 AI 重写核心 SQL 解析器，性能暴增 454 倍里那种长会话、反复校准的打法，靠的也是把项目约束持续喂准。

常见反模式：好心办坏事的三种写法

CLAUDE.md 写坏比不写还糟，因为坏的说明会主动误导模型。下面三种是最高频的。

反模式一：写成一本书

最常见的错误，是把 CLAUDE.md 当成项目 wiki，恨不得把架构演进史、所有环境变量、每个模块的详细设计全塞进去。结果是几百行的文件，模型读完，真正重要的「红线」被埋在第 300 行，注意力早就分散了。

修法：主文件砍到 100 行以内，详细内容拆进 docs/ 用「按需加载索引」引用。问自己一个问题：这条信息，是「模型每次都得知道」还是「模型偶尔才用到」？前者留在主文件，后者进子文档。

反模式二：堆无关信息

往 CLAUDE.md 里塞模型其实用不上、或者别的工具已经管了的东西。比如把整份 .eslintrc 抄进来（lint 工具会执行，模型不需要读）、把 package.json 的依赖列表复述一遍（模型自己会看 package.json）、写一堆「我们是一个充满激情的团队」之类的废话。

修法：每一行都过一遍「删掉它，模型会写错吗？」如果不会，就删。CLAUDE.md 的每个字都该是「不写就会出错」的信息。

反模式三：过期不更新

这是最隐蔽、危害最大的一种。你三个月前写「测试用 jest」，后来全仓库迁到了 vitest，但 CLAUDE.md 没改。现在模型每次都按 jest 的 API 给你写测试——它不是猜错的，是被你主动喂错的。过期的 CLAUDE.md 比没有 CLAUDE.md 更危险，因为它带着权威感误导。

修法：把 CLAUDE.md 当代码维护。目录结构变了、命令变了、约定变了，第一时间同步改。最好在团队约定里写一条：「改动构建/测试/目录结构的 PR，必须同步更新 CLAUDE.md」。让它和代码一起进版本控制、一起 review。

这种「配置漂移导致行为异常」的麻烦，在 Claude Code 的使用反馈里并不少见。当然有些波动并不是 CLAUDE.md 的锅，比如解决 Claude Code 性能波动难题：用户推测降智与服务器 Session 路由强相关讨论的是服务端的不确定性。排查输出质量问题时，先确认是「你喂的上下文有问题」还是「服务端确实在抖」，别把所有锅都甩给 CLAUDE.md，也别忽略它。

把 CLAUDE.md 放进更大的工作流

CLAUDE.md 不是孤立的。它和你怎么选工具、怎么编排多智能体、怎么管额度，共同决定了 AI 编程的最终体验。

如果你还在选编程 Agent，Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选和 AI编程工具现状：从IDE到CLI，开发者如何在Cursor与Claude间抉择这两篇能帮你定位——但无论选哪个 CLI 类工具，「给项目写一份精炼的说明文件」这个动作都是通用的，只是文件名不同。

进阶玩法是多智能体协作，开发者构建多智能体协作流：用GPT Pro指挥Claude Code与Codex 展示了用一个模型指挥另一个模型干活的编排方式，这种场景下每个执行节点都需要清晰的项目上下文，CLAUDE.md 的价值被进一步放大。而遭遇GPT降智后转向Claude：开发者实测MCP协议打造”自举”式开发闭环则把 MCP 协议和开发闭环串了起来，CLAUDE.md 在这种闭环里承担的就是「让每一轮都从正确的项目认知出发」。

成本侧也别忽视。上下文写得精炼，本身就是省 token——一份臃肿的 CLAUDE.md 每次会话都要重新读一遍，长期看是实打实的额度消耗。关于额度，社区最近讨论很多，比如 Claude Code 实战：20篇顶会文献瞬间总结，Opus 额度告急引发成本担忧和频繁触发限流？开发者反馈 Claude Code 会话额度疑似大幅收紧，精简上下文虽然不能根治限流，但能让你每一份额度花得更值。

FAQ

Q：CLAUDE.md 要放在哪里，Claude Code 会自动读吗？
A：放在项目根目录，文件名就是 CLAUDE.md。Claude Code 在会话启动时会自动读取并拼入上下文，无需手动指定。子目录里也可以放，模型在该目录下工作时会一并纳入。

Q：CLAUDE.md 越详细越好吗？
A：不是。它和真正重要的约束抢模型注意力，过长反而稀释效果。目标是「最小有效」——只写不写就会出错的信息，详细内容拆进 docs/ 按需加载。一般主文件控制在 100 行以内。

Q：那个「41% 到 89%」的准确率提升是真的吗？
A：这是社区热点原帖的说法，没有公开的评测方法、样本量和复现步骤，不能当作权威基准。但「写好项目说明文件能显著改善输出质量」这个方向是站得住的，具体能提升多少取决于你的项目和写法。

Q：CLAUDE.md 和 MCP、子 agent 这些是什么关系？
A：是互补的不同层。CLAUDE.md 解决「模型该知道这个项目的什么」，MCP 解决「模型能调用什么外部能力」，子 agent 解决「复杂任务怎么拆分编排」。先把 CLAUDE.md 写好，它是成本最低、收益最直接的一层。

Q：团队协作时 CLAUDE.md 要进版本控制吗？
A：要。把它当代码维护，进 Git、一起 review，约定「改构建/测试/目录的 PR 必须同步更新它」。过期的 CLAUDE.md 会主动误导模型，比没有还糟。

结语

CLAUDE.md 不是文档，是接口：你把项目的真实约束写准、写短、并保持它不过期，模型就从「靠先验猜」切到「靠现场推」。提升准确率的关键从来不是写更多，而是写对那几条。先给你的项目补一份 80 行的精简版，剩下的交给迭代。