CLAUDE.md 别写成第二份 README
第一次配 Claude Code，很多人把 README 复制一份改名，或者把 CLAUDE.md 的规矩原样塞回 README。两边越写越像，改一处要改两遍，代理还是漏最关键的那几条。
它们不是同一份文档的两个副本。
README 写给人。讲这是什么、怎么装、怎么跑、怎么参与。人想看才打开，写多长都不占会话成本。
CLAUDE.md 写给代理。会话开始时注入上下文，讲这次动手必须知道的事实和边界。每一行都会反复占 token，也会挤后面的代码和对话。它表达的是倾向，不是开关。一次都不能破的动作，用 Hooks，见 CLAUDE.md 管倾向，Hooks 才是铁律。
同一句话，两边写法不一样
假设所有业务查询都必须带租户字段，漏了就是越权。
README 可以解释：多租户用 tenant_id 做逻辑隔离，新表要留这个字段，查询时带上，避免串数据。
CLAUDE.md 只留命令：业务表必须有 tenant_id。查询必须带 tenant_id 过滤，禁止跨租户查询。
不需要在这份文件里说服模型「我们当初为什么这么设计」。背景留给 README。
| README | CLAUDE.md | |
|---|---|---|
| 受众 | 要上手或参与的人 | 会改代码的代理 |
| 语气 | 解释、铺垫 | 祈使句，不解释 |
| 该写的 | 是什么、怎么装、怎么贡献 | 必须做什么、绝对别做什么、关键路径和命令 |
| 成本 | 不进上下文 | 每次会话都加载 |
事实留下，流程抽走
一段从「一条事实」长成「一套步骤」时，就不该再待在 CLAUDE.md。
留下的是短事实：目录各管什么、构建和测试命令、命名和禁用写法、提交规矩、反直觉的特例。「构建命令是 pnpm build」是事实。「一次发布要走哪七步」是流程，做成 Skill，发布时再加载。怎么把流程和钩子分开，见 MCP、Skills、Hooks 怎么选。
不要写进去的还有：愿景和选型故事、给新人的长安装教程、完整 API 参考、大段「为什么」。package.json 里已经写明的框架和语言，也不必再复述一遍，除非有代码里看不出来的坑。
个人偏好也不要提交进仓库。回答用中文、提交信息的个人格式，放 ~/.claude/CLAUDE.md。这个项目独有的，才进项目级 CLAUDE.md。
两边都要的事实，只写一处
构建命令、目录结构，人和代理都要知道。不要各抄一遍。
把短清单放在单独文件，例如 docs/commands.md，README 链过去，CLAUDE.md 用 @docs/commands.md 引进来。@ 的相对路径以写这行的文件为准，不是当前工作目录。
不要 @README.md 把整份说明引进来。那会把给人看的铺垫全部注入会话。只引用双方都要、而且本来就短的那一段。
团队如果还在用 Cursor、Codex、Gemini CLI 这类工具，核心规则可以放 AGENTS.md。Claude Code 不直接读这个文件。在 CLAUDE.md 里加一行 @AGENTS.md，再补只给 Claude 的几条。只用 Claude Code 的项目，直接写 CLAUDE.md 就够，不必为了标准多维护一份。
不听话时，先查这三处
代理没照做，多半不是工具坏了。
- 文件太长，关键句被后半段淹没。超过大约 200 行还在涨，就把解释挪回 README，把流程抽成 Skill。
- 句子太软。「尽量带上
tenant_id」和「所有查询必须带tenant_id，禁止跨租户查询」不是同一句。 - 多层说明互相打架。用户级和项目级会拼接，不是后者覆盖前者。跑
/memory看这次到底加载了哪些文件。
光靠 README 也不够。代理能去读它，但要从大段介绍里捞构建命令，又慢又容易抓错。CLAUDE.md 的用处就是把代理真正需要的那点硬信息提纯出来。
反过来，只留 CLAUDE.md、不写 README，人进仓库不知道这个项目是干什么的。两个都写，各写各的，短事实用引用打通。
可直接改的约束条目，仍可用站里的 CLAUDE.md 约束提示词。那份是条目清单，这篇只负责别把清单写成第二份说明书。