写于 2026 年 7 月
2026 年 5 月，Andrej Karpathy 加入 Anthropic。社区里有人感慨：他开源的代码变少了。
但很快，另一个东西在社区里流传起来——一份号称「Karpathy 自用的 CLAUDE.md」。
真实性存疑。Karpathy 本人没有公开认领过，文件里的措辞也不完全像他的风格。但内容货真价实：它系统性地整理了「怎么给 AI 编程助手下规矩」，七类规则，条条切中要害。即便不是他写的，也是基于他长期表达的工程思想。
我读完之后有一个明确的判断：这份文件真正有价值的，不是它写了什么，而是它为什么这么写。 照搬一份别人的 CLAUDE.md 到自己的项目，几乎注定没用。但理解它背后的方法论，能帮你写出一份真正管用的工程规范。
这篇文章不是翻译复述。我想拆解的是规则文件这件事的本质——以及怎么为自己的项目写一份。
先说一个反直觉的判断
很多人把 CLAUDE.md / AGENTS.md 当成「prompt 的延伸」——给 AI 多写几句叮嘱，让它表现更好。
这个理解是错的。
规则文件的本质，是把你脑子里的工程默认值，外化成 AI 能读取的约束。
一个资深工程师接手新项目时，脑子里有大量隐性默认值：代码风格、错误处理偏好、依赖选择原则、测试粒度、commit 规范……这些东西平时不需要写下来，因为人类同事会通过 review、闲聊、看历史代码慢慢习得。
但 AI 没有这个渠道。它每次进来都是白纸一张。你能指望它“悟”出你 prefer 函数式风格、不允许加新依赖、commit message 必须带 issue 号吗？不能。
所以规则文件解决的是一个信息传递问题：怎么把一个人类工程师需要三个月才能“摸清楚”的项目约定，在 AI 接手的第一秒就告诉它。
从这个角度看，Karpathy 的那份文件之所以值得读，不是因为它的具体规则多高明，而是因为它示范了约束该写在哪些维度上。
七类规则，以及它们为什么是这七类
我把原文的规则重新归了一下，发现它们其实覆盖了一个 AI 写代码的完整生命周期：读 → 想 → 写 → 改 → 验 → 收尾。这不是随机的七条，而是一个工种的工作流。
1. 写之前先读（读）
不要在没读懂现有代码库前就生成代码。
这是最反直觉、又最关键的一条。
新手用 AI 的典型模式是：抛一个需求，AI 立刻开始写。看起来高效，实际上产出的代码几乎必然和现有代码风格格格不入——命名不对、抽象层级不对、错误处理方式不对。
资深工程师接手任务的第一反应永远是先读代码。看看类似功能别人怎么实现的，import 哪些工具，测试怎么组织。AI 应该被强制走同样的流程。
这条规则的潜台词是：AI 写得快不是优势，写得对才是。 强制它先读，是为了让它写出来的东西能 merge 进现有项目，而不是成为一块需要人重新收拾的烂摊子。
2. 想清楚再动手（想）
说清假设、取舍，遇到模糊需求先问，不要默默替用户做决策。
「加个认证」这种需求，可能是 JWT、可能是 OAuth、可能是 session cookie。默默替你选一个，几乎肯定选错。然后你花在纠正它的时间，比从头讲清楚还长。
这条规则的本质是：把隐式决策显式化。AI 倾向于“乐观路径”——假设你想要最常见、最标准的实现。但项目里的真实需求往往是有取舍的，没人替它做这个取舍，它就会选一个看起来合理的，然后你不得不推翻重来。
对应到规则文件里，你应该写清楚：哪些决策允许 AI 自己做，哪些必须先问。 比如我的 AGENTS.md 里有一条——遇到模糊需求，先基于上下文给最合理方案并推进；如果错误假设会带来真实风险，则先问清楚。这条省了我无数次来回。
3. 保持简单（想）
抵抗过度设计：过早抽象、臆想式错误处理、不必要的可配置性。
AI 最容易犯的错之一：为了“以防万一”，加上一堆现在根本用不上的灵活性。一个只需要返回字符串的函数，它给你写成泛型；一个只在一处调用的逻辑，它给你抽成接口。
「以防以后需要」不是需求。YAGNI（You Aren’t Gonna Need It）这条原则对 AI 尤其重要，因为人类工程师有“懒”的本能来抵抗过度设计，AI 没有——它写复杂代码和写简单代码一样快。
规则文件里应该明确：优先选简单方案，影响面尽可能小。
4. 外科手术式修改（写）
diff 尽可能小。不碰没被要求碰的代码，匹配现有风格，哪怕项目用
var。
这条很多人会忽略它的下半句：匹配现有风格，哪怕你觉得它不对。
人类工程师有个本能——看到不顺眼的代码顺手改了。AI 也学会了这个“本能”，但更失控。它会把整个文件重新格式化、顺手“优化”一些无关函数、把 var 改成 let。结果 PR 一打开，几百行 diff，review 的人根本看不出哪些是实际改动。
规则文件里要写死：改动只触碰必要范围，避免顺手重构和引入无关变化。 这条比任何代码风格规定都重要。
5. 验证（验证）
修 bug 先写复现测试，改动前后都跑测试，测行为而非实现。
这条直接对应 TDD（测试驱动开发），但用在 AI 上有特别的意义。
AI 写的代码有一个特征：它经常“看起来对”。语法没错、逻辑通顺、变量名起得好——但行为可能是错的。光看代码 review 不出来，必须靠测试。
更关键的是，测试是 AI 能否自我验证的前提。没有测试，AI 自己都不知道它做对了没有，只能靠人告诉它。有了测试闭环，它就能在交付前自己确认结果。这就是为什么 OpenAI 那个百万行代码实验里，“CI 验证闭环”是核心准备之一。
6. 目标驱动执行（验证）
把模糊任务变成可验证任务，多步任务先说明计划。
这条容易被低估。AI 跑长任务时，最大的失败模式不是某一步做错，而是跑着跑着忘了最初要干什么。
规则文件里要求“多步任务先说明计划”，本质上是在做目标锚定——让 AI 把模糊的指令拆解成可验证的步骤，并在执行过程中不断回到这个计划。这跟人类工程师写 task list 是一个道理，区别是人类会自觉做，AI 需要被要求做。
7. 调试 / 依赖 / 沟通（收尾）
调试别猜要调查；别轻易加依赖；commit message 写具体。
这三条放在一起，因为它们都属于“收尾质量”。
- 调试不猜：AI 倾向于“看起来合理的修复”。但 bug 的根因经常不在表面，得读日志、读错误、读失败测试才能定位。规则文件要强制它先调查再动手。
- 慎加依赖：AI 加依赖的成本感知为零。一个能用十行代码解决的问题，它给你引一个库。长此以往项目就臃肿了。
- commit 写具体：这条看起来是小事，但它直接影响项目历史的可读性。
七类规则之外：那些常见的失败模式
原文还列了一组 AI 写代码的典型失败模式，我觉得比规则本身更值得贴在墙上：
- 大杂烩：一次改动里混着功能、重构、格式化，review 不动
- 错误抽象：在只有一处调用时就过早抽象，导致后来改需求时抽象反而成了阻碍
- 隐形决策：默默替你做了选择，你直到出问题才发现
- 乐观路径：只考虑正常情况，边界条件和错误处理缺失
- 知识幻觉：自信地使用不存在的 API 或编造的函数签名
- 风格漂移：每个文件风格都不一样，看不出是同一个项目
- 失控重构：你说改个函数名，它把整个模块重新组织了
注意一个共性：这些失败都不是模型能力不够，而是缺少约束。 更强的模型会减轻一部分，但不会根除。这就是为什么即便是 Karpathy 这个级别的人，也得老老实实写规则文件。
怎么写一份属于自己的规则文件
这是我最想讲的部分。因为照搬别人的 CLAUDE.md 几乎一定没用——你的技术栈、代码风格、依赖偏好、团队约定都不一样。
我的建议是按这个顺序来：
第一步：把项目的基本事实写进去。
技术栈、目录结构、构建命令、测试命令、部署方式。这些是最基础的“AI 必须知道的事”。看起来琐碎，但能避免 AI 凭空猜测你的项目长什么样。
第二步：把“不允许的事”写清楚，比写“建议做的事”更重要。
负面约束比正面指导更有效。“不要加新依赖”、“不要重命名现有变量”、“不要在没跑测试前标记完成”——这些明确的禁令，AI 执行得比模糊的“保持代码整洁”靠谱得多。
第三步：把你自己最常纠正的事，提炼成规则。
这是最关键的一步。每次你发现自己在反复纠正 AI 同一个问题——比如它又顺手重格式化了代码、又加了一个没必要的泛型、又在 commit 里写了“update”——就把这条纠正写进规则文件。
规则文件不是一次写完的，它是从你的纠正历史里长出来的。 这也是为什么照搬别人的没用——你和别人的纠正历史不一样。
第四步：定期清理。
模型在变强。有些规则是针对旧模型的弱点写的，新模型已经不犯了，留着反而增加 token 消耗和干扰。每隔一段时间回头问一句：这条规则还有必要吗？
一个更深的观察
我读完那份 CLAUDE.md 之后，最强烈的感受不是“AI 需要规则”，而是另一件事：
给 AI 写规则的过程，本身就是一次对自己工程习惯的盘点。
你得问自己：我到底希望代码长什么样？我处理 bug 的标准流程是什么？我什么时候允许加依赖？我对 commit message 的要求是什么？……
这些问题平时是隐性的，藏在你的肌肉记忆里。但你从来没被迫把它们一条一条写出来过。AI 强制你做了这件事。
很多团队发现，写完一份好的 AGENTS.md 之后，受益的不只是 AI——新人 onboarding 速度也变快了。因为那份文件把团队的隐性约定显式化了，而人类同事也需要这些信息。
这或许才是规则文件最被低估的价值：它不只让 AI 干得更好，它也让你的工程实践变得更清晰、更可传承。
结语
原文末尾提了一句：社区里有个 andrej-karpathy-skills 项目，据称能把 Claude 的代码错误率从 41% 降到 11%。
这个数字我没法独立验证，但方向是对的。约束是有杠杆的——一次写好的规则，会在之后每一次 AI 调用里持续生效。
所以别把规则文件当成写给 AI 的 prompt。把它当成写给你自己、写给你的团队、写给未来每一个接手这个项目的人的工程文档。
写一份，然后持续迭代它。这是这个 AI 时代少数确定有回报的投入之一。
参考来源：社区流传的「Karpathy CLAUDE.md」(2026.06)、andrej-karpathy-skills 项目、以及我个人维护 AGENTS.md 的实践