CLAUDE.md 该写什么？实测「别犯错」指令的真相

上下文文件到底该写什么？一场关于「别犯错」的实测

给 AI 编程工具写一个 CLAUDE.md（或 AGENTS.md）时，很多人第一反应是塞满各种规则。但 YouTube 博主做了一场系统性实测，结论可能和你想的不一样：真正有用的规则，往往不是那些泛泛而谈的「最佳实践」，而是工具无法从代码中推断出的项目决策。

这场实测覆盖了 Claude Code、Codex 和 GitHub Copilot 三个工具，以一个小型 Java 房间预订库为试验田，逐条验证规则是否真的改变了工具行为。

原则一：优先写工具无法推断的决策

博主提出的第一原则很清晰：优先写工具无法可靠推断的决策。如果代码里已经到处都是某种模式，工具会直接复制它，不需要你在文件里再提醒一遍。

实验验证了这一点。在没有任何上下文文件的情况下，新类被放进正确包路径的概率是九次九中。也就是说，「服务类放在 service 包」这类规则，对当前任务毫无增益。

作者把这类规则称为「对照组」——加进去是为了确认工具本来就能做对，而不是为了证明文件有效。真正值得写入文件的，是那些重要、容易遗漏、或者反复被破坏的约定。

AI 编程工具的上下文推断机制：Claude Code、Codex 等工具在生成代码前，会先检索项目中的现有文件（如包结构、命名习惯、构建脚本），并基于这些模式进行续写或补全。这种机制依赖的是「上下文学习」（in-context learning）——模型从提示词中已有的示例里归纳规律，而非依赖外部记忆。因此，凡是代码库中反复出现、结构清晰的约定（如包路径、命名风格、依赖注入方式），工具通常能直接复用，无需在 CLAUDE.md 中重复声明。真正需要人工写入的，是那些「代码中未体现但必须遵守」的决策，例如团队内部的历史包袱、外部合规要求、或即将迁移的临时兼容层。理解这一点，就能明白为什么博主强调「对照组」规则没有增益：它们描述的是工具已经能推断的模式，写进去只是确认，而非补充信息。

原则二：规则要具体到可检查

「确保能跑」不是一条可执行的指令。博主写入了实际命令 mvn -q test，并要求工具报告失败的测试、且除非真正运行过，否则不得声称测试通过。

但这里有一个隐蔽的坑：指令不等于权限。在博主的配置中，Claude 的权限模式拦截了 Maven，导致 12 次运行中没有一次能真正执行测试——不过 Claude 如实报告了「无法运行」。放开权限后，三次运行中只有一次真正跑通了测试，另外两次因为命令形式不匹配被拦截。Codex 则在全部 12 次运行中都执行了测试。

文件负责引导，测试和检查负责强制执行。

据截图信息，作者在对比成本时提到从 52 美分降到约 40 美分。这提醒我们：写命令之前，先确认工具真的有权限执行它。

In my setup

权限模式与命令拦截：Claude Code 等工具默认运行在受限的权限沙箱中，对可能修改系统状态或执行外部程序的命令（如 mvn、npm、docker）进行拦截，除非用户显式授权。这种设计是为了防止 AI 在未经确认的情况下执行危险操作，但也会导致上下文文件中写入的测试命令「形同虚设」。博主实验中 12 次运行无一执行 Maven，正是权限模式拦截的结果。值得注意的是，Claude 如实报告了「无法运行」，说明工具在权限不足时会反馈失败而非静默跳过。因此，编写上下文文件时，除了写清楚命令，还需确认工具的权限配置（如 settings.json 中的 allowedTools 或交互式授权流程）是否放行了该命令。否则，规则写得再具体，也无法被真正执行，反而可能让工具误以为测试已通过。

原则三：写明边界，而非绝对禁令

上一轮视频中，工具曾未经要求就修改 README，Claude 还两次替换了已有构造函数，导致依赖它的测试失败。新视频里，博主在文件中加入了「保持兼容性，无法保持时说明原因」和「不要动 README」两条边界。

结果如何？没有文件时，README 在九次运行中被修改了两次（一次 Codex、一次 Copilot）；有文件时，三十次运行中零次被修改。作者谨慎地表示，样本量小，只能算「值得关注的观察」。

构造函数方面则没有出现替换行为——三十九次运行中，无论有没有文件，都没有发生。这意味着该实验无法证明文件能防止构造函数被改，上一轮的破坏来自不同的提示词。

Two, documentation you already have

实测「别犯错」：一条规则省了 27% token，但说不清为什么

最有趣的实验是这个：一个只有一行「Don't make mistakes」的上下文文件，对比完全没有文件。

九次运行（每工具三次）全部通过隐藏测试和约定检查——和没有文件时表现一致。但在 Claude 上，token 用量减少了约 27%，成本降低约 19%，超出了该工具自身的波动范围。而在 Codex 和 Copilot 上，差异落在噪声范围内。

博主自己的八条真实规则节省了 43%，但两个数字之间的差距小于运行波动，所以他无法断定是规则起了作用，也无法断定「别犯错」有什么实际功效。关键区别在于：「别犯错」没有定义任何可检查的具体行为，而 README 规则明确产生了可测量的差异（零次修改 vs 两次修改）。

该从文件里删掉的六样东西

博主列出了六类不该留在上下文文件中的内容：

泛泛而谈的建议：「遵循最佳实践」——如果背后有真实规则，把那条规则写出来。
已有的文档：指向它，别粘贴它。副本会过时，工具会得到两个答案。
当前任务的需求：文件是「这里怎么做事」，提示词是「今天做什么」。
与提示词冲突的指令：实测中，明确写在提示词里的覆盖规则赢了，但隐藏测试三个工具全部失败——因为测试期待的是项目格式。保持两者一致。
过时的规则：项目变了，文件也得改。
未经审查的生成文件：让工具起草是个不错的起点，但三个工具都没写出「别动 README」或「保留构造函数」。生成文件是起点，不是终点。

for review

文件名与长度的实测数据

关于文件名，博主没有轻信文档，而是在每个文件名中植入一条假规则（「每条回复末尾单独一行写 pineapple」）来测试加载情况。结果：Claude Code 从 CLAUDE.md 和根目录 AGENTS.md 都能读取（各三次全中）；Codex 只认根目录 AGENTS.md；Copilot 在 15 次尝试中从未输出该标记，但它自己的工具列出了 .github 下的文件——说明文件被找到了，但无法确认是否被遵守。

长度方面，对比无文件、8 行、20 行、60 行四种情况。Claude 在 Maven 被拦截时，8 行减少 43% token，20 行减少 27%，60 行减少 38%，全部超出波动范围；Codex 各长度变化均在波动内；Copilot 无文件时自身波动高达平均值的 93%，无法分离出可辨识的效果。

一句话总结：在 8 到 60 行范围内，没有发现一致的性能恶化。

博主还往 60 行文件里藏了 10 条额外规则（分硬性「always/never」和软性「prefer」及解释型三种措辞），脚本检查未发现任何违反——但这个小任务很少给工具用到这些规则的机会。唯一的微弱信号是：规则缺席时 Codex 在九次运行中写了三次通配符导入，规则在场时三次运行中均未出现。样本太小，无法定论。

from 52 cents to about 40 cents

上下文文件的加载优先级与作用域：不同工具对文件名和存放位置有各自的约定。Claude Code 支持 CLAUDE.md 和根目录 AGENTS.md 两种入口，且会递归读取子目录中的同名文件，形成层级化的上下文；Codex 目前仅识别根目录 AGENTS.md；GitHub Copilot 则依赖 .github 目录下的配置文件（如 copilot-instructions.md），但其加载行为在实验中没有被可靠触发。这种差异意味着，跨工具协作时，单一文件未必能被所有工具读取。博主用「pineapple」假规则测试加载情况，正是为了区分「文件被找到」和「文件被遵守」——Copilot 的工具列出了 .github 下的文件，却从未输出标记，说明加载与执行是两个独立环节。实际项目中，建议根据团队使用的工具选择对应文件名，或维护多份指向同一内容的软链接，避免规则只对部分工具生效。

实操建议

综合全部实测，博主的建议可以浓缩为六条：优先写测试容易遗漏的约定；写具体可检查的指令；包含测试命令并确保有权限执行；声明兼容性和变更边界；删除重复、冲突和过时的规则；审查输出，用测试强制执行必须成立的部分。

最让博主意外的发现是：工具本来就会复制代码中展现的约定，而一行「别犯错」省下的成本几乎和八条精心设计的规则相当。这提醒我们，上下文文件不是万灵药，它是审查的补充，不是替代。

本文基于 YouTube 频道的实测视频整理，所有数据均来自原视频。