CLAUDE.md 写作指南：AI 编程的"宪法"文件到底怎么写才有效 ​

CLAUDE.md 是 Claude Code 的"宪法"文件——你写的每一行，AI 都会在每次对话时永久记住。写得好，AI 越用越顺手；写得差，反而不如不写。这篇从 Karpathy 的四个原则出发，讲清楚到底怎么写才有效。

参考资源：

• Forrest Chang 的 CLAUDE.md 模板：https://github.com/forrestchang/andrej-karpathy-skills
• Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code

一、CLAUDE.md 到底是什么 ​

CLAUDE.md 就是一个全局项目配置文件。

你把它放在项目根目录里，Claude Code 每次启动会话都会自动读取它。每次输入 /init 就会生成一个 CLAUDE.md 文件。

它里面的内容，在每次对话的时候都会塞进 AI 的上下文里，而且永远不会被压缩。

这就是说，你写在里面的东西，AI 是一定会记住的。不管你跟它聊了多少轮对话，1 万次也好，10 万次也好，它始终记得。

你可以把它想象成一份常设指令文档。你不用每次都从头解释"这个项目用什么框架"、"测试怎么跑"、"命名规范是什么"。写一次，AI 永久记住。

听起来很简单对吧？但问题就出在这个"简单"上。

写得差，不如不写 ​

苏黎世理工学院有个研究报告，结论很反直觉：

用了 CLAUDE.md 的项目和不用 CLAUDE.md 的项目比，反而成功率更低，推理成本还高了 20%。

写得差的 CLAUDE.md，带来的副作用很明显——还不如不写。

二、Karpathy 的四个原则 ​

2026 年 1 月，Karpathy 发了一篇帖子，说他用了 Claude Code 两个月，从 80% 手写代码变成了 80% 代理驱动编码。他管这叫"二十年编程生涯中工作流程的最大变化"。

从他的实践中，可以提炼出四个核心原则：

原则一：不要假设，不要隐藏困惑，浮出权衡 ​

你跟 AI 说"帮我加一个登录按钮"。

它要是默认给 PC 端加的，默默写完了，结果你用的是手机 App——那这部分代码基本废了。

好的 CLAUDE.md 应该告诉 AI：遇到模糊需求，先问再动手。

原则二：最小代码解决问题，没有推测性内容 ​

你让它"给这个表单加个验证"。

它给你整了一套三层架构：Validator 抽象基类、策略模式、再加一个配置文件。200 行代码。实际上你就想验证一个邮箱格式，一行正则就搞定了。

"推测性内容"就是那些 AI 自己脑补出来的"未来可能需要"的东西。它觉得"万一以后要加其他验证呢"，所以先搭个框架。

结果是框架搭得挺漂亮，功能就一行。

好的 CLAUDE.md 应该告诉 AI：只解决当前问题，不要推测未来需求。

原则三：只触碰必须的，只清理自己的烂摊子 ​

你让它"修复 calculateTotal() 函数里的 bug"。

它改完 bug，顺手把 utils/ 目录下的三个文件格式化了，还改了另一个跟你请求完全无关的函数——因为它觉得那个函数"看起来不太优雅"。

你本来只想修一个 bug，现在 diff 里有五个文件，改了十处，code review 都不知道该看哪里。

好的 CLAUDE.md 应该告诉 AI：不该碰的别碰。

原则四：定义成功标准，循环直到验证 ​

你让它"优化一下这个查询性能"。

它优化完了，跑了一下，挺好，提交了。但到底优化了多少？有没有回退到更差的版本？测试通过了没有？

正确的做法：你告诉它"这个查询要从 500ms 优化到 50ms 以内，用 AB 测试对比，优化前后都要跑一遍压测"。

给它一个可以衡量的目标，它会自己循环调试，直到达到那个标准。

好的 CLAUDE.md 应该告诉 AI：做完不等于做好，要有明确的验收标准。

三、五条铁律：写约束不写介绍 ​

经过实践总结，好的 CLAUDE.md 还应该满足这五个特点：

1. 越短越好 ​

前沿模型能一致遵循的指令大概在 150 到 200 条。Claude Code 自己的系统提示就占了大约 50 条。你写的每一行都在跟实际工作竞争上下文空间。

能删就删。

2. 写反例，不写正例 ​

说白了就是写禁止，不写要求。

3. 写约束，不写介绍 ​

AI 需要的不是"这是什么"，而是"别乱来"。

4. 写长期有效的，不写临时的 ​

你开发过程中有个临时流程需要跑，没问题，但不要写到 CLAUDE.md 里。写成命令或者 Skill，这些是按需加载的，不占上下文。

5. 模型越强，CLAUDE.md 越简单 ​

去年用普通模型编程，你需要写很多约束"不要做这个、不要做那个"。今年用更强的模型，很多规范它自己学会了，约束可以越来越少。

CLAUDE.md 不是一劳永逸的——它应该随着模型能力增长而瘦身。

四、不好写的 CLAUDE.md 会带来什么 ​

副作用一：占用上下文长度 ​

你的 CLAUDE.md 有 1000 行？这 1000 行就是 1000 行，永远在上下文里挪不走、压不了、删不掉。上下文长度是有限的，里面放了这个，就放不了别的。

副作用二：诱发非必要行为 ​

你在 CLAUDE.md 里写了"每次处理任务前，都要完整阅读相关依赖目录"。那好，不管你让 AI 做什么，只要涉及代码，它都会去读目录。即使你今天只是让它改一个简单的文案。

这些事情也要消耗推理成本。

副作用三：增加判断负担 ​

模糊的概念最害人。"保持代码优雅"、"要考虑扩展性"——这些话看起来没问题，但 AI 每次生成代码都要反复揣摩"我这段代码够不够优雅"。

它不是人，不懂什么叫"优雅"，它只会机械地匹配你给的关键词。结果就是推理成本蹭蹭往上涨。

好的 vs 不好的：直接看例子 ​

不好的写法：

这是一个电商项目。
项目结构如下：
- src/：源代码
- components/：组件
- utils/：工具函数
- tests/：测试

开发时要保持代码优雅，
注意代码的可维护性和扩展性。
每次完成后要运行完整测试。

好的写法：

引用组件去 components/ 目录找。
工具函数放到 utils/ 目录。
生产代码禁止 console.log。
提交前必须跑 tests/ 下的测试。
禁止单文件超过 200 行。

区别：前者是"介绍"，后者是"约束"。前者告诉 AI "这是什么"，后者告诉 AI "别乱来"。

五、源码级解析：CLAUDE.md 是怎么加载的 ​

这部分是给想深入理解的读者准备的。

Claude Code 加载 CLAUDE.md 不是一股脑全加载，它有一套优先级体系。从 claudemd.ts 源码里可以看到，分为四层：

加载顺序：越后面加载的，优先级越高，会覆盖前面的内容。

这就是"就近原则"——离你当前工作目录越近的配置，优先级越高。

@include 懒加载机制 ​

当你的 CLAUDE.md 越来越长，可以把一部分规则拆分到单独的文件里，然后在 CLAUDE.md 里用 @ 引用它们。

# CLAUDE.md

@.claude/rules/api-conventions.md
@.claude/rules/testing-standards.md

这就好比 CLAUDE.md 做入口，做懒加载。需要的规则才加载，不需要的暂时不加载。

这也是为什么好的 CLAUDE.md 不一定要写很多内容——它可以只是一个入口文件，把规则分散到多个文件里管理。

六、渐进式写入：TDD 方法论 ​

如果你不知道从哪里开始，有一个笨办法：

先留空，让 AI 跑一段时间，它报错的地方，就是你需要写进去的地方。一个错误出现两次以上，再更新 CLAUDE.md。

这是"测试驱动"的思路，可以标准化成四步：

这比"一开始就写满"靠谱得多，因为每条规则都是被真实错误验证过的。

七、上下文经济学：每一行都有租金成本 ​

CLAUDE.md 的每一行都有"租金成本"：它永久占据上下文空间，消耗每次推理的 token。

判断标准：如果一行约束只在 5% 的场景下有用，但 100% 的时间都在占空间，它的"租金回报率"就是负的。用 @include 做懒加载，把低频规则从"永久住户"变成"按需访客"。

总结 ​

CLAUDE.md 不是说明书，是护栏。删掉一行后 AI 犯错概率不会显著增加？那就别写。