CLAUDE.md和README到底有什么区别？一个给AI一个给人，别再复制粘贴

摘要：很多人把CLAUDE.md当成“给AI看的README”，复制粘贴一份就完事，结果两个文件越长越像、互相打架，AI还经常不听话。真相是它俩根本不是一种东西：README是写给人看的项目说明书，讲“这是什么、怎么跑、怎么参与”；CLAUDE.md是写给AI代理的行为约束，讲“你必须怎么做、绝对别碰什么”。一个偏解释、一个偏命令；一个能写长、一个越短越好。这篇把两者的受众、语气、内容、格式四条线彻底拆开，给一张“什么写哪个”的对照表，讲清为什么CLAUDE.md里该放事实、把过程抽去Skill，怎么用@import让两个文件不重复，以及AGENTS.md这个跨工具标准怎么把你的规则一次写好处处能用。

CLAUDE.md和README到底是不是一回事？

先把最常见的误解掐掉。不少人第一次配CLAUDE.md，做法是把README复制一份改个名，或者反过来把CLAUDE.md里的规则原样塞进README。两个文件于是越长越像，内容大段重叠，改一处要改两遍，AI读着读着还经常不照做。问题的根源，是把它们当成了同一种文档的两个副本。

它们不是。README和CLAUDE.md的根本差别只有一句话：README是写给人看的，CLAUDE.md是写给AI代理看的。受众一换，几乎所有写法都得跟着变。人需要被解释、被引导、被铺垫上下文；AI代理需要的是明确的边界、能直接执行的指令、不绕弯子的规则。你给新同事讲“我们这个项目是做跨境支付的，技术栈选型当年是这么考虑的……”，这是README的口吻；你给一个会动手改代码的代理立规矩“所有金额字段一律用整数存分、禁止用浮点”，这是CLAUDE.md的口吻。把这两种口吻混在一个文件里，对谁都不友好。

这个区分不是文风偏好，背后有实打实的代价差异。README放在仓库里，人想看才点开，写多长都不占运行成本；而CLAUDE.md会在每次会话启动时被注入到模型的上下文里，它的每一行都是反复消耗的token，也都在挤占模型有限的注意力。这条机制上的硬差别，决定了两个文件必须分开、各按各的逻辑写。理解了它,后面所有的取舍就都顺了。

CLAUDE.md准确说是个什么文件？

给CLAUDE.md一个准确定义：它是Claude Code的项目级记忆文件，会在会话开始时自动加载，用来把“这个项目里AI该怎么干活”的规则、约定和关键事实，长期固定下来。它不是配置文件那种带强制语义的东西，更像一份始终摆在代理面前、每次都先读一遍的工作守则。Claude Code官方的记忆文档把它定位成持久上下文，而非硬性开关——这点很重要，意味着CLAUDE.md里写的是“倾向和约定”，真正不能破的硬约束得靠钩子去兜底。

CLAUDE.md还不是只有一个。它按作用域分成四级，从企业托管策略、用户级（你个人跨所有项目）、项目级（仓库里，团队共享），到本地级（你在这个项目里的私人覆盖），四级是全部拼接叠加、不是后者覆盖前者。这套作用域机制本身是个值得单独讲透的话题，保哥在另一篇里专门拆过CLAUDE.md的四级作用域、自动记忆与配置模板，这里不重复，你只需要记住一个结论：CLAUDE.md是分层生效、层层累加的，所以每一层都该只写这一层独有的东西，别让不同层级互相重复。

对照之下，README就单纯多了：它是仓库的门面文档，GitHub上一进来就显示的那一页，受众是任何一个想了解、想用、想参与这个项目的人。它不会被注入进任何AI的上下文（除非你显式让AI去读），写多长、配多少图表都没有运行成本。一个是AI每次开工都先过一遍的随身守则，一个是人按需翻阅的项目说明书，定位天差地别。

同样一句话，写进README和CLAUDE.md有什么不一样？

光说概念太虚，拿同一件事看两个文件怎么分别处理，差别立刻就出来了。假设你的项目是个多租户的SaaS，有条铁律：所有业务数据查询都必须带上租户隔离字段，漏了就是越权。

写进README，它会是一段解释：“本系统采用多租户架构，不同商户的数据通过tenant_id字段做逻辑隔离。新加业务表时请注意预留该字段，查询时一并带上，以保证数据不串户。”——有背景、有原因、给的是理解。

写进CLAUDE.md，它会被压成一条命令：“所有业务表必须含tenant_id字段；所有查询必须带tenant_id过滤，禁止跨租户查询。”——没有铺垫、没有解释为什么，直接告诉代理边界在哪。AI不需要被说服，它需要被约束。你越是把规则写成不容置疑的祈使句，代理踩线的概率越低；反过来，你在CLAUDE.md里写一大段“我们之所以这么设计是因为……”，不但没用，还白白烧token、稀释注意力。

把这种差别铺开成一张表，四条线一目了然：

表里最该盯住的是最后一行“篇幅成本”，因为它解释了其余所有差别为什么必须存在。粗算一笔账：一份两百行、写满解释的CLAUDE.md，轻松就是好几千token，而这几千token在你这个项目的每一次会话里都要被重新读一遍、占一遍坑。一天开十次会话，它就被加载十次；它越臃肿，留给你真实代码和对话的上下文预算就越少，模型在长任务里“忘事”的概率也越高。README再长都没有这个问题，因为它根本不进上下文。把这笔账算明白，你就会真心实意地想把CLAUDE.md往短了写——这不是洁癖，是实打实的成本和效果考量。

一个124000星的项目是怎么处理这两个文件的？

看头部开源项目怎么做，比看任何教程都直观。Claude Code自己的仓库现在已经过了121000星，而开源代理OpenClaw更是冲到124000星上下，整个“用CLAUDE.md这类文件约束AI”的实践，背后是二十多万星级别的生态在共同验证。这么大体量的项目，反而把CLAUDE.md写得极简。

OpenClaw的CLAUDE.md一度短到只有一行——指向另一个文件AGENTS.md。这不是偷懒，是个深思熟虑的选择：它把真正的规则集中写在AGENTS.md里，CLAUDE.md只做一个转发。为什么要绕这一道？因为AGENTS.md是个跨工具的开放标准，而CLAUDE.md只有Claude Code认。规则写在AGENTS.md里，OpenAI的Codex、Google的Gemini CLI、Cursor、Windsurf、GitHub Copilot等二十多款工具都能读；再用一行CLAUDE.md把Claude Code也接进来，等于一份规则喂饱所有AI编程工具。AGENTS.md开放标准的官方说明记录了已经有六万多个开源项目采用它，俨然成了AI代理指令文件的事实标准。

这个做法对团队的启发很实在：如果你的团队同时在用好几款AI编程工具，别给每个工具单独维护一份指令文件，那是维护噩梦。把核心规则写进AGENTS.md，再用各工具自己的入口文件（Claude Code的CLAUDE.md、其他工具的对应文件）做一行转发，一处修改、处处同步。当然，如果你全队就只用Claude Code，那直接写CLAUDE.md也完全没问题，不必为了标准而标准。

哪些内容该写进CLAUDE.md，哪些坚决不该？

这是最容易出错、也最值钱的一节。CLAUDE.md失控，几乎都是因为往里塞了不该塞的东西，越写越长，最后变成一个谁也不敢删的大杂烩。划清楚边界，得先弄明白一个关键原则。

官方在Skills文档里给过一句很精炼的判断标准：Claude Code的Skills文档建议，当CLAUDE.md里某一段从“一条事实”长成了“一套步骤流程”时，就该把它抽出去做成Skill。换句话说，CLAUDE.md里放事实，不放过程。“构建命令是npm run build”是事实，该留；“怎么走完一次完整发布”是过程，那是七八步的流程，塞在CLAUDE.md里每次会话都得加载一遍纯属浪费——把它做成一个Skill，只在真要发布时才加载，平时一个token都不占。这个“事实留下、过程抽走”的切法，是控制CLAUDE.md体积最有效的一刀。

按这个原则，该写进CLAUDE.md的是这些：项目结构的关键路径、构建和测试的命令、代码风格的硬约定（缩进、命名、禁用的写法）、提交和推送的规矩、绝对不能碰的红线（别动生产配置、别提交密钥）、以及那种“反直觉、不说AI一定会踩”的项目特例。共同点是——都短、都是事实、都需要每次都生效。

坚决不该写进CLAUDE.md的，是这些：给人看的项目背景和愿景介绍（那是README的活）、长篇的安装上手教程（README或单独文档）、完整的API参考（太长，做成Skill的附属文件按需加载）、多步骤的操作流程（抽成Skill）、以及任何“解释为什么”的大段论述。判断方法很简单：这段内容是不是每次会话都必须在场？不是，就别放进CLAUDE.md。它是不是一套要照着做的步骤？是，就抽去Skill。保哥的经验是，CLAUDE.md一旦超过两百行还在涨，基本就是这两类东西混进来了，该做一次清理。

这里还有一层容易被忽略的分工，跟前面说的四级作用域有关：同样是写给AI的规则，也得分清哪条该写在项目级、哪条该写在用户级。判断依据很直接——这条规则是“这个项目独有的”，还是“你个人不管在哪个项目都想要的”。项目独有的，比如“本项目金额存分”“业务表必带tenant_id”，写进仓库里的项目级CLAUDE.md，跟着代码走、团队共享；而“回答我时用中文”“提交信息用某种格式”这种纯个人偏好，写进你的用户级CLAUDE.md，跨所有项目对你生效，不该塞进某个具体仓库去污染队友。这条线划清楚，团队协作时就不会出现“你的个人习惯被提交进仓库、强加给所有人”的尴尬。把它和README的人机分工叠在一起看，你会发现整套文档体系其实是一个二维表：横轴是给人还是给AI，纵轴是项目共享还是个人私有，每格各放各的东西，井井有条。

两个文件内容重叠了，怎么办才不用维护两遍？

分清楚了该写哪个，还有个现实问题：有些信息人和AI都得知道，比如构建命令、目录结构。难道要在README和CLAUDE.md里各写一遍、改的时候同步两处？那又回到了重复维护的老路。

更聪明的办法是用引用而不是复制。Claude Code的CLAUDE.md支持用@路径的语法导入其他文件的内容，比如在CLAUDE.md里写一行@README.md，就能把README的内容引进来，而不必把那些段落抄一遍。这样事实只存在一个地方，改一处两边都更新。当然导入要克制，把整个README全量导进CLAUDE.md又会把上下文撑爆，正确姿势是只导真正双方都要、且本就简短的那部分（比如一个单独的docs/commands.md命令清单），让它成为唯一事实源，README和CLAUDE.md都去引它。

还有个进阶玩法是让AI帮你维护CLAUDE.md本身。你可以建一个专门的Skill，比如放在.claude/skills/maintain-claude-md/下，让它负责定期审视CLAUDE.md：哪些规则过时了、哪些段落长成了流程该抽走、哪些和README重复了。把“保持CLAUDE.md精简”这件事也工程化，它就不会随着项目膨胀而失控。这套思路，和把日常重复指令沉淀成可复用Skill是一脉相承的，保哥在另一篇里专门讲过Skill的设计模式与工程化写法，可以接着看。

一份好的CLAUDE.md和README，结构上各自长什么样？

落到可操作的模板。先看CLAUDE.md，推荐的骨架是这样几块，每块都尽量压成短列表或代码块：

# 项目约定

## 仓库
跨境电商SaaS后台，单仓库。

## 结构
- src/api 后端接口
- src/web 前端
- src/shared 共享类型

## 命令
- 构建：npm run build
- 测试：npm test
- 本地起服务：npm run dev

## 风格
- 用TypeScript，禁any
- 金额一律整数存分，禁浮点

## 红线
- 禁提交.env和任何密钥
- 禁直接改生产配置
- 所有业务查询必须带tenant_id

注意整份东西没有一句解释，全是命令和事实，扫一眼就能用，加载进上下文也不心疼。再看README，它该是另一副面孔，给人读的，可以有血有肉：

# 项目名

一句话说清这是什么、解决谁的什么问题。

## 功能特性
- 列出主要能力，可配徽章、截图

## 快速开始
详细的安装步骤、环境要求、第一次怎么跑起来，
该解释的都解释清楚，照顾从没接触过的人。

## 项目结构
配目录树和说明，告诉人各部分干什么。

## 如何贡献
分支约定、提交规范、PR流程，欢迎参与。

## 许可证

两相对照，差别一眼就看出来：CLAUDE.md惜字如金、全是祈使句；README娓娓道来、解释充分。同一个项目的同一组事实，因为受众不同，呈现方式完全是两套。把这两副面孔分清楚，你就不会再写出那种又长又像、互相打架的文档了。

AI老是不照CLAUDE.md做，是哪里出了问题？

把CLAUDE.md写好之后，新手最常遇到的挫败是：规则明明白纸黑字写在那儿，代理还是该犯的错照犯。这时候别急着怀疑工具，先回到那条最根本的定位上——CLAUDE.md是持久上下文，不是强制配置。它表达的是“强烈倾向”，会显著提高代理照做的概率，但并不像代码里的断言那样物理上拦住它。理解这一点，排查方向就对了。

实际带团队，见过的“不听话”八成能归到三个原因。第一个，也是最常见的，是CLAUDE.md太长了，关键规则被淹没在一堆可有可无的内容里，模型的注意力被稀释，越往后的规则越容易被忽略。这恰恰印证了前面反复强调的“越短越好”——不是为了好看，是越短每条规则的权重越高。把那些解释性废话清掉、把长流程抽成Skill，剩下的硬规则反而更容易被遵守。

第二个原因是规则写得太软。“尽量带上tenant_id”和“所有查询必须带tenant_id，禁止跨租户查询”，对模型的约束力天差地别。前者给了它“看情况”的余地，后者是不容商量的边界。CLAUDE.md里凡是真正重要的红线，都该用最硬的祈使句写，别用“建议”“尽量”“最好”这种留口子的词。第三个原因是层级冲突——你在用户级CLAUDE.md里写了一套，项目级又写了相抵触的另一套，四级拼接之后代理读到的是自相矛盾的指令，自然无所适从。这种情况下回去把各层级理清楚，让每层只管自己那摊事，冲突就消了。

那要是某条规则真的一次都不能破呢？比如“绝对不许提交密钥到仓库”，靠CLAUDE.md的“倾向”终究不够保险。这时候正确的做法是把它从“嘱咐”升级成“物理拦截”——用Claude Code的钩子（hook）机制，在提交动作真正发生前跑一段检查脚本，发现密钥就直接拒掉。CLAUDE.md负责让代理“知道并倾向于”守规矩，钩子负责让某些铁律“物理上没法破”，两者配合才是完整的约束体系。把这层关系想通，你就不会再期待一份CLAUDE.md包打天下了。

讲个真实的小例子。保哥带的一个做户外装备独立站的团队，早期把CLAUDE.md写成了一份近三百行的“项目大全”：又是业务背景介绍，又是完整的部署流程，又是大段代码风格的解释和举例，几乎把README和操作手册的内容全搬了进去。结果代理在改代码时反而频繁忽略最关键的那几条数据隔离规则，因为它们被埋在第两百多行。后来做了一次大刀阔斧的精简：业务背景挪回README，部署流程抽成一个deploy的Skill，代码风格只留“禁用什么、必须用什么”的硬条目，全文砍到六十行出头。改完之后，那几条核心红线被遵守的稳定性肉眼可见地上来了。这件事给团队的教训是——CLAUDE.md不是写得越全越安心，而是越聚焦越管用。

不写CLAUDE.md，光靠README行不行？

有人会问：我README写得很全了，AI不能直接读README吗，何必再单独维护CLAUDE.md？理论上AI确实能读README，但效果差很多，原因还是回到那条机制。

README是给人写的，里面充满了解释、背景、营销式的描述，对人友好，对AI却是噪音——代理要从一大段“我们的愿景是……”里捞出“构建命令是什么”，又慢又容易抓错重点。更要命的是README往往很长，全量塞进上下文会严重挤占模型的注意力预算。CLAUDE.md的价值，正在于它把“AI干活真正需要的那点硬信息”从人类叙事里提纯出来，压成最省token、最不易误读的形态。这就像你不会把整本员工手册甩给新人让他自己找重点，而是给他一张一页纸的“上岗须知”。README是手册，CLAUDE.md是那张须知，两者各司其职，谁也替代不了谁。

反过来也一样，只写CLAUDE.md不写README同样不行——那样人类访客一进仓库，面对的是一堆冷冰冰的命令式约束，完全不知道这项目是干嘛的、怎么参与。所以正解从来不是二选一，而是两个都写、各写各的、用引用打通重复部分。这套分工理顺了，你的项目对人对AI才都算交代清楚了。如果你想顺带把整个Claude Code的高效工作习惯也梳理一遍，可以接着看这份Claude Code最佳实践，CLAUDE.md的写法只是其中一环。

常见问题解答

CLAUDE.md和README可以是同一个文件吗？

不建议合并。两者受众和用途根本不同：README给人看、偏解释、可以写长；CLAUDE.md给AI代理看、偏命令、越短越好且每次会话都注入上下文消耗token。合成一个文件会让AI读到大量对它是噪音的解释性内容，也让人读到一堆冷冰冰的约束。正确做法是分开写，用@import引用打通真正重复的简短事实。

CLAUDE.md里该写解释和背景吗？

不该。CLAUDE.md是写给AI的行为约束，用祈使句直接说“必须怎样、禁止怎样”就够了，别写“之所以这么设计是因为……”这类背景。原因有两个：解释性内容对代理执行规则没帮助，还白白消耗每次会话注入的token、稀释模型注意力。需要解释的背景放README，CLAUDE.md只留能直接执行的事实和命令。

什么内容该从CLAUDE.md里抽出去做成Skill？

判断标准是看它是事实还是流程。一条短事实，比如“构建命令是npm run build”，留在CLAUDE.md；一套多步骤的操作流程，比如完整的发布步骤、某种代码生成的固定套路，就该抽成Skill。因为流程往往很长，塞在CLAUDE.md里每次会话都加载纯属浪费，而Skill只在真正需要时才加载，平时不占上下文。

AGENTS.md和CLAUDE.md是什么关系，该用哪个？

AGENTS.md是跨工具的开放标准，Codex、Gemini CLI、Cursor等二十多款AI编程工具都认；CLAUDE.md只有Claude Code认。如果你团队同时用多款工具，把规则写进AGENTS.md，再用一行CLAUDE.md转发指向它，一份规则所有工具通用。如果只用Claude Code，直接写CLAUDE.md就行，不必强上AGENTS.md。

怎么避免README和CLAUDE.md里同样的信息维护两遍？

用引用代替复制。Claude Code的CLAUDE.md支持@路径语法，比如把命令清单单独放进docs/commands.md，让它成为唯一事实源，README和CLAUDE.md都用@导入它，改一处两边同步。注意别把整个README全量导入CLAUDE.md，那会撑爆上下文，只导真正双方都要且本就简短的那部分。

CLAUDE.md写多长算合适？

越短越好，没有硬性字数但有个经验参考：一旦超过两百行还在持续增长，基本就是混进了不该放的东西——长篇解释、多步骤流程、和README重复的内容。这时该做一次清理：解释挪去README，流程抽成Skill，重复部分用@import打通。记住每一行都是每次会话反复消耗的token，精简CLAUDE.md本身就是在省钱和保注意力。