01｜CLAUDE.md 到底是个什么东西？

很多人一上来就开始问「CLAUDE.md 应该写些啥」、「行数多少合适」、「能不能 import 别的文件」。

但我觉得这些问题之前，得先回答一个更基本的问题：CLAUDE.md 到底是干啥的？为什么 Claude Code 要专门搞这么个文件？

你想象一个场景。

你刚入职一家公司，主管丢给你一份文档，标题叫「团队约定」。里面写了：我们用 yarn 不用 npm，API 在 src/api/ 下，生产数据库千万别动，提 PR 之前要跑 yarn lint。

这份文档看着不起眼，但效果惊人。新人不用一遍遍问「咱们这边怎么做 X」，老人也不用一遍遍重复回答。一份文档，省下整个团队的沟通成本。

 

CLAUDE.md 就是给 Claude 的这份「团队约定」。

说穿了，它本质上就是一个普通的 markdown 文件，文件名固定叫 CLAUDE.md，放在你项目的根目录下。

你能用记事本打开，能用 VSCode 编辑，跟你平时写的 README 一样，里面就是写写规则、放放说明，谁都能上手。

但它特别的地方在于：每次你打开 Claude Code 跟它聊天，Claude 都会自动把这个文件读一遍，作为整个对话的「ground truth」（基准事实，可以理解为「默认成立的前提」）。你后面提的需求、它做的判断，全都是在这份「团队约定」的基础上推进的。

换句话说：在你输入第一句提问之前，在写任何代码之前，在任何事情发生之前，Claude 都会先读这个文件，并把它当作整段会话的默认前提。它不是「可选的提示」，而是「默认的前提」。

你看，你压根没在提问里提这条规则，Claude 自己就把它套上了。

更妙的是，下次再开新 session 问别的，比如「什么是 WebSocket」，它还是会以「打个比方」开头。规则一旦写进 CLAUDE.md，相当于给 Claude 装了个稳定的「长期记忆」，每个新对话都默认带着。

 

讲到这儿，你可能会冒出一个新疑问：那为啥要专门搞一个 CLAUDE.md？

我直接把规则写在 README 里不行吗？反正它俩都是 markdown 文件。

不行。两个文件长得像，但定位完全不一样。

Anthropic 官方文档里有句话点醒了我：「README 是写给人看的，CLAUDE.md 是写给 agent 看的，两个读者群体不一样，密度也不一样。」

啥意思？README 是给开发者翻的，写项目介绍、快速上手、贡献指南，长一点没事，散一点没事，反正人会跳读。

而且 Claude 默认不会主动去读 README，你不告诉它去看，它就当不存在。

CLAUDE.md 才是那个被自动加载、每次都吃 token 的「默认配置」。

（顺带说一句，token 简单理解就是模型读写时的「字符单元」，大致 1 个中文字 ≈ 1 个 token；每次请求消耗的 token 既算钱也占用上下文窗口，所以「省 token」全文会反复出现。）

所以一个项目可能同时有好几份 CLAUDE.md 在生效，这一点我们第四节会展开。

 

到这里你应该能感觉到 CLAUDE.md 的特殊之处了：它不是文档，是配置。是你给 Claude 配的「这个项目的预设」。

 

理解了这一层，接下来就要扒一个让所有人意外的事实：写得越多，效果反而越差。

02｜写多了反而废？

我刚开始用 Claude Code 的时候，是这么想的：CLAUDE.md 嘛，多写点总没坏处，规则越细，Claude 越知道我要啥。

后来看到一组数据，我直接把自己 400 多行的 CLAUDE.md 删了一半。

这个数据来自一个叫 SFEIR Institute 的技术博客。他们做了一组实测：把所有规则塞在一个 CLAUDE.md 里，控制在 200 行以内的时候，规则遵守率大概 92%。但写到 400 行往上，遵守率就肉眼可见地往下掉。

更有意思的是，如果你把 200 行拆成 5 个 30 行的模块化文件，丢到 .claude/rules/ 目录里，遵守率反而能涨到 96%。

写得多反而不听，写少了拆开反而听了。这跟我朴素的直觉完全是反的。

为啥会这样？两个原因。

第一个原因，token 经济。CLAUDE.md 每次启动都会被完整加载进上下文窗口。你写 400 行，每次请求就消耗几千 token，挤压你的对话、Claude 的思考、工具调用结果的位置。

打个比方，会议桌上摆 50 张便签，重点一目了然。换成 400 张，整张桌子都被淹没，谁也找不着重点。

第二个原因，注意力稀释。模型的注意力不是无限的，规则一多，每条规则在模型脑子里的权重就被摊薄了。社区里不少重度用户都聊过这个体感：CLAUDE.md 超过 300 行之后，「记不住」就变成常态。

 

讲到这儿你可能想，那只要控制在 200 行就行了？也不全是。光控制行数还不够，得知道哪些东西根本就不该写进 CLAUDE.md。

肯定有不少人的 CLAUDE.md 里塞着大量负资产。最典型的三类反例：

第一类，复述型。 把整个项目架构文档复制粘贴进 CLAUDE.md，一写写 100 行。问题是项目架构会变，今天 React，半年后可能就 Vue 了，CLAUDE.md 里的 100 行还停留在 React 时代。正确做法是一行话指过去：「项目架构详见 docs/architecture.md」，Claude 真要看自己会去 read。

第二类，愿望型。 「我们希望测试覆盖率达到 90%」、「我们的目标是 0 bug」。这种话听着政治正确，但 Claude 没法判断「希望」和「实际」的差距，可能为了「满足愿望」给你乱补一堆没意义的测试。CLAUDE.md 里只写当下实际执行的规则，「PR 提交前必须跑 npm test」是规则，「我们希望大家多写测试」是 PUA。

第三类，术语表型。 把团队术语表往 CLAUDE.md 里搬。「Repo 指 repository、PR 指 pull request……」Claude 是个 LLM，这些通用术语它都懂。你真正需要解释的是团队特有的黑话（比如「我们说『小灰』指的是预发布环境」），但也建议放 docs/glossary.md 里。

 

把这三类垃圾清掉，你的 CLAUDE.md 可能直接从 400 行瘦到 80 行。Claude 的表现，下一次开 session 就能感觉到。

03｜什么样的规则才真正「有效」？

清完垃圾，问题就变成：剩下那些该写的规则，到底怎么写才有用？

我先抛个问题给你猜：同样讲缩进，下面哪种写法 Claude 听得更好？

• A：「所有 TypeScript 文件用 2 个空格缩进」
• B：「代码要按规范格式化」

如果你猜 A，恭喜，答对了。但你能说清楚为什么吗？

关键差异在一个词：可验证。

A 是具体的，Claude 写完代码自己就能数：是不是 2 个空格？是不是 TypeScript 文件？这两个问题都有明确答案，它能自检。

B 是模糊的，什么叫「按规范格式化」？这个判断需要外部标准，Claude 只能猜你的偏好，猜得对就对，猜得错就错。

收尾：3 句话精华

文章讲了一堆，咱们最后做个总结。

如果你只能从这篇文章带走三句话，那就是这三句：

第一，CLAUDE.md 是给 Agent 的入职手册，不是给人的 README。写之前先问自己：这句话是给人看的，还是给 Claude 看的？给人看的留给 README。

第二，200 行是黄金线，每行都吃 token，多写不如不写。复述型、愿望型、术语表型这三类内容直接删，瘦下来 Claude 反而更听话。

第三，具体可验证、告诉 why、持续更新，三条铁律压过一切技巧。哪条规则都别忘了这三个核心。

如果你面试被问到对 CLAUDE.md 的理解，可以这么答：

「CLAUDE.md 每次启动都会被完整加载进上下文，规则一多反而稀释模型注意力。社区实测数据是 200 行 92% 遵守率，400 行掉到 70%。我的做法是项目根 CLAUDE.md 控制在 80 行以内，按模块拆到 .claude/rules/ 下用 path-scoped 加载，配合 /init 起步和 /memory 维护，规则遵守率明显上来了。」