Karpathy 的 4 条 CLAUDE.md 规则将 Claude 的错误率从 41% 降至 11%。在测试 30 个代码库后，我又增加了 8 条

2026 年 1 月下旬，Andrej Karpathy 发了一条帖子，吐槽 Claude 写代码的方式。三个失败模式：无声的错误假设、过度复杂化、对不该碰的代码造成连带损害。

Forrest Chang 看到了这条帖子，把吐槽内容打包成 4 条行为规则，放进一个 CLAUDE.md 文件，丢到了 GitHub 上。第一天就获得了 5,828 个星标。两周内被收藏 60,000 次。到今天已有 120,000 个星标。 这是 2026 年增长最快的单文件仓库。

然后，我在 30 个代码库上测试了 6 周。

这 4 条规则确实有效。以前大约 40% 情况下会出现的错误，在适合它们发挥优势的任务上，降到了 3% 以下。但这个模板是为了解决 1 月份的代码编写错误而构建的。

2026 年 5 月的 Claude Code 生态系统面临不同的问题——Agent 冲突、钩子级联、技能加载冲突、跨会话中断的多步骤工作流。

所以我加了 8 条规则。下面：完整的 12 条 CLAUDE.md 规则，每条规则为何存在，以及原始 Karpathy 模板在 4 个地方会悄然失效。

如果你想跳过解释直接粘贴，完整文件在文末。

为什么这很重要

Claude Code 的 CLAUDE.md 是整个 AI 编码栈中被利用最不足的文件。大多数开发者要么：

• 把它当成所有偏好的垃圾场，膨胀到 4,000+ token，合规率降到 30%
• 完全跳过它，每次都重新提示——5 倍的 token 浪费，会话之间毫无一致性
• 复制一个模板后就忘了。头两周还行，然后随着代码库变化悄然失效

Anthropic 官方文档明确说明：CLAUDE.md 是建议性的。Claude 大约 80% 的时间会遵循它。超过 200 行后，合规率会急剧下降，因为重要规则被淹没在噪音中。

Karpathy 的模板用一个文件、65 行、4 条规则解决了这个问题。这是底线。

上限可以更高。加上下面我要讲的 8 条规则，你不仅能覆盖 Karpathy 吐槽的 2026 年 1 月的代码编写问题，还能覆盖模板编写时还不存在的 2026 年 5 月的 Agent 编排问题。

原始的 4 条规则

如果你没读过 Forrest Chang 的仓库，底线如下：

规则 1 — 先思考，再编码。

没有无声的假设。说明你在假设什么。揭示权衡。在猜测之前先提问。当存在更简单的方法时，要提出异议。

规则 2 — 简洁至上。

用最少的代码解决问题。没有推测性功能。不为一次性代码创建抽象。如果资深工程师会认为它过于复杂——那就简化。

规则 3 — 外科手术式修改。

只动你必须动的地方。不要"改进"相邻的代码、注释或格式。不要重构没有问题的部分。匹配现有风格。

规则 4 — 目标驱动执行。

定义成功标准。循环直到验证。不要告诉 Claude 要遵循哪些步骤，告诉它成功是什么样的，让它自己迭代。

这四条规则堵住了我在无监督 Claude Code 会话中看到的大约 40% 的失败模式。剩下的约 60% 存在于下面的空白地带。

我添加的 8 条规则（以及原因）

每一条都来自一个真实的场景，在这些场景中，Karpathy 的 4 条规则不够用。我会展示场景，然后给出规则。

规则 5 — 不要让模型做非语言类工作

Karpathy 的规则对此保持沉默。模型会决定那些本应是确定性代码的事情，比如是否重试 API 调用、如何路由消息、何时升级处理。每周都有不同的决定。用 $0.003 每 token 的成本做不稳定的 if-else 判断。

1## 规则 5 — 仅将模型用于判断性调用
2将 Claude 用于：分类、起草、总结、从非结构化文本中提取。
3不要将 Claude 用于：路由、重试、状态码处理、确定性转换。
4如果状态码已经回答了问题，那么普通代码就能回答问题。

场景： 一段代码调用 Claude 来"决定是否应该在 503 错误时重试"，前两周运行得很好，然后开始不稳定，因为模型开始把请求体作为决策的上下文来读取。重试策略变得随机，因为提示词是随机的。

规则 6 — 硬性 Token 预算，没有例外

没有预算的 CLAUDE.md 就是一张空白支票。每个循环都有可能螺旋式地变成一个 50,000 token 的上下文转储。模型不会自行停止。

1## 规则 6 — Token 预算不是建议性的
2每个任务预算：4,000 个 token。
3每次会话预算：30,000 个 token。
4如果任务接近预算，总结并重新开始。不要硬撑。
5暴露超支情况 > 默默地超额运行。

场景： 一个调试会话持续了 90 分钟。模型非常乐意在同一个 8KB 的错误信息上反复迭代，逐渐忘记了已经尝试过哪些修复。到最后，它开始建议我在 40 条消息之前就已经拒绝过的修复方案。Token 预算本应在第 12 分钟就终止它。

规则 7 — 暴露冲突，不要中和它们

当代码库的两个部分意见不一致时，Claude 试图取悦双方。结果是前后矛盾。

1## 规则 7 — 暴露冲突，不要中和它们
2如果代码库中两个现有模式相互矛盾，不要混合它们。
3选择一个（较新的 / 经过更多测试的），解释原因，并标记另一个待清理。
4满足两条规则的"平均"代码是最糟糕的代码。

场景： 一个代码库有两种错误处理模式——一种是 async/await 配合显式的 try/catch，另一种是使用全局错误边界。Claude 编写的新代码同时使用了两种。错误处理器加倍。我花了 30 分钟才弄清楚为什么错误被吞掉了两次。

规则 8 — 先读后写

Karpathy 的"外科手术式修改"告诉 Claude 不要碰相邻的代码。但它没有告诉 Claude 要先理解相邻的代码。没有这个规则，Claude 编写的新代码会与 30 行之外的现有代码冲突。

1## 规则 8 — 先读后写
2在文件中添加代码之前，先读取该文件的导出项、直接调用者以及任何明显的共享工具。
3如果你不理解现有代码为何如此组织，在添加代码之前先提问。
4"看起来是正交的"是这个代码库中最危险的短语。

场景： Claude 在一个现有的、它没有读过的相同函数旁边添加了一个新函数。两个函数做同样的事情。新函数因为导入顺序而优先。而旧函数已经是 6 个月的事实标准。

规则 9 — 测试不是可选的，但它们不是目标

Karpathy 的目标驱动执行暗示测试是成功标准。在实践中，Claude 把"测试通过"当作唯一目标，并编写能通过浅层测试但破坏其他一切的代码。

1## 规则 9 — 测试验证意图，而不仅仅是行为
2每个测试必须编码 WHY（为什么）行为重要，而不仅仅是 WHAT（什么）行为。
3像 `expect(getUserName()).toBe('John')` 这样的测试，如果函数接受一个硬编码的 ID，那就毫无价值。
4如果你无法编写一个在业务逻辑改变时会失败的测试，那么这个函数就是错的。

场景： Claude 为一个认证函数编写了 12 个测试。全部通过。但认证在生产环境中是坏的。这些测试是在测试函数返回了某些东西，而不是是否返回了正确的东西。函数通过了，因为它返回的是一个常量。

规则 10 — 长时间运行的操作需要检查点

Karpathy 的模板假设是一次性交互。真正的 Claude Code 工作是多步骤的——跨 20 个文件重构、在会话中构建功能、跨多个提交调试。没有检查点，一个错误的转向就会丢失所有进展。

1## 规则 10 — 在每个重要步骤后设置检查点
2完成多步骤任务中的每一步后：总结做了什么、验证了什么、还剩下什么。
3不要从一个你无法向我描述的状态继续。
4如果你迷失了方向，停下来重新陈述。

场景： 一个 6 步骤的重构在第 4 步出了问题。等我注意到的时候，Claude 已经在错误的状态上完成了第 5 步和第 6 步。理清问题比从头重做花的时间还长。检查点本可以在第 4 步就发现问题。

规则 11 — 惯例优于新奇

在一个有既定模式的代码库中，Claude 喜欢引入自己的模式。即使它的方式"更好"，引入两种模式也比单独使用任何一种模式更糟糕。

1## 规则 11 — 匹配代码库的惯例，即使你不同意
2如果代码库使用 snake_case 而你更喜欢 camelCase：用 snake_case。
3如果代码库使用基于类的组件而你更喜欢 hooks：用基于类的组件。
4不同意见是另外的讨论。在代码库内部，一致性 > 个人品味。
5如果你真的认为某个惯例是有害的，请提出来。不要默默地另起炉灶。

场景： Claude 将 React hooks 引入了一个基于类组件的代码库。它们能工作。但它们也破坏了代码库的测试模式，这些模式假设了 componentDidMount。花了半天时间移除并重写。

规则 12 — 显式失败，而非静默失败

最昂贵的 Claude 失败是那些看起来像成功的失败。一个函数"能工作"但返回了错误的数据。一个迁移"完成了"但跳过了 30 条记录。一个测试"通过了"但只是因为断言是错的。

1## 规则 12 — 大声失败
2如果你不能确定某件事是否成功，请明确说出来。
3如果 30 条记录被静默跳过，那么"迁移完成"就是错的。
4如果你跳过了任何测试，那么"测试通过"就是错的。
5如果你没有验证我问到的边缘情况，那么"功能正常"就是错的。
6默认暴露不确定性，而不是隐藏它。

场景： Claude 说一个数据库迁移"成功完成"。它静默地跳过了 14% 的记录，这些记录遇到了约束冲突。跳过操作被记录了但没有被暴露出来。11 天后，当报告开始看起来不对劲时才发现问题。

数据

我在 30 个代码库中跟踪了同一组 50 个代表性任务，持续 6 周。三种配置：

错误率 = 任务需要修正或重写才能符合意图。计数包括：无声的错误假设、过度工程化、连带损害、静默失败、惯例违反、冲突平均化、遗漏检查点。

合规率 = Claude 在适用情况下明显应用相关规则的频率。

有趣的结果不是错误率从 41% 下降到 3% 这个头条数字。而是从 4 条规则增加到 12 条，几乎没有增加合规开销（78% -> 76%），但错误率又降低了 8 个百分点。新规则覆盖了原始 4 条规则未解决的失败模式——它们不争夺相同的注意力预算。

Karpathy 模板悄然失效的地方

在 4 个地方，原始的 4 条规则模板是不够的，即使在添加新规则之前也是如此：

1. 长时间运行的 Agent 任务。

Karpathy 的规则针对的是 Claude 编写代码的时刻。它们对 Claude 运行多步骤流水线时发生的情况保持沉默。没有预算规则。没有检查点规则。没有"大声失败"规则。流水线会漂移。

2. 多代码库一致性。

"匹配现有风格"假设只有一种风格。在一个有 12 个服务的单体仓库中，Claude 必须选择哪种风格。原始规则没有告诉它如何选择。它会随机选择或取平均值。

3. 测试质量。

目标驱动执行将"测试通过"视为成功。没有说明测试必须是有意义的。结果是测试测试不出什么有用的东西，但让 Claude 充满信心。

4. 生产环境 vs 原型。

保护生产代码免于过度工程化的同 4 条规则，也会拖慢那些为了探索方向而合理需要 100 行推测性脚手架代码的原型。Karpathy 的"简洁至上"在早期代码上过度开火。

添加的 8 条规则并没有取代 Karpathy 的 4 条规则。它们修补了空白地带，在这些地方，他 2026 年 1 月的模型（自动补全式编码）与 2026 年 5 月的 Agent 驱动、多步骤、多代码库工作不匹配。

什么没起作用

在确定这 12 条规则之前，我尝试过的一些事情：

• 添加我在 Reddit / X 上看到的规则。 大多数要么是用不同措辞重述 Karpathy 的 4 条规则，要么是无法通用的领域特定规则（"始终使用 Tailwind 类"）。删掉了。
• 超过 12 条规则。 我测试了最多 18 条。超过 14 条规则后，合规率从 76% 下降到 52%。200 行的上限是真实的。超过这个限度，Claude 开始模式匹配到"存在规则"而不实际阅读它们。
• 依赖可能不存在的工具的规则。 "始终使用 eslint"在 eslint 未安装时会失效。规则静默失败。替换为与能力无关的措辞："匹配代码库强制执行的风格"而不是"使用 eslint"。
• 在 CLAUDE.md 中使用示例而不是规则。 示例比规则更重。三个示例消耗的上下文大约相当于 ~10 条规则，而且 Claude 会过度拟合它们。规则是抽象的，示例是具体的。使用规则。
• "小心" / "认真思考" / "真正集中注意力。" 纯粹的噪音。这些规则的合规率下降到约 30%，因为它们不可测试。替换为具体的命令式语句（"明确陈述假设"）。
• 告诉 Claude 要"资深"。 不起作用。Claude 已经认为自己很资深了。合规差距在于思考和行动之间。命令式规则缩小了差距；身份提示不能。

完整的 12 条 CLAUDE.md 规则（可直接复制粘贴）

1# CLAUDE.md — 12 条规则模板
2
3除非明确覆盖，否则这些规则适用于本项目中的每个任务。
4倾向：在非琐碎工作上，谨慎重于速度。在琐碎任务上使用判断力。
5
6## 规则 1 — 先思考，再编码
7明确陈述假设。如果不确定，提问而不是猜测。
8当存在歧义时，提出多种解释。
9当存在更简单的方法时，提出异议。
10困惑时停下来。指出不清楚的地方。
11
12## 规则 2 — 简洁至上
13用最少的代码解决问题。没有推测性内容。
14没有超出要求的功能。不为一次性代码创建抽象。
15测试：资深工程师会说这过于复杂吗？如果是，就简化。
16
17## 规则 3 — 外科手术式修改
18只动你必须动的地方。只清理你自己的烂摊子。
19不要"改进"相邻的代码、注释或格式。
20不要重构没有问题的部分。匹配现有风格。
21
22## 规则 4 — 目标驱动执行
23定义成功标准。循环直到验证。
24不要遵循步骤。定义成功并迭代。
25强大的成功标准让你能够独立循环。
26
27## 规则 5 — 仅将模型用于判断性调用
28将我用于：分类、起草、总结、提取。
29不要将我用于：路由、重试、确定性转换。
30如果代码能回答，就让代码回答。
31
32## 规则 6 — Token 预算不是建议性的
33每个任务：4,000 个 token。每次会话：30,000 个 token。
34如果接近预算，总结并重新开始。
35暴露超支情况。不要默默地超额运行。
36
37## 规则 7 — 暴露冲突，不要中和它们
38如果两个模式矛盾，选择一个（较新的 / 经过更多测试的）。
39解释原因。标记另一个待清理。
40不要混合冲突的模式。
41
42## 规则 8 — 先读后写
43在添加代码之前，读取导出项、直接调用者、共享工具。
44"看起来是正交的"是危险的。如果不确定代码为何如此组织，请提问。
45
46## 规则 9 — 测试验证意图，而不仅仅是行为
47测试必须编码 WHY（为什么）行为重要，而不仅仅是 WHAT（什么）行为。
48一个在业务逻辑改变时不会失败的测试就是错的。
49
50## 规则 10 — 在每个重要步骤后设置检查点
51总结做了什么、验证了什么、还剩下什么。
52不要从一个你无法描述的状态继续。
53如果你迷失了方向，停下来重新陈述。
54
55## 规则 11 — 匹配代码库的惯例，即使你不同意
56在代码库内部，一致性 > 个人品味。
57如果你真的认为某个惯例是有害的，请提出来。不要默默地另起炉灶。
58
59## 规则 12 — 大声失败
60如果任何东西被静默跳过，那么"完成"就是错的。
61如果任何测试被跳过，那么"测试通过"就是错的。
62默认暴露不确定性，而不是隐藏它。

保存为 CLAUDE.md 放在你的仓库根目录。在 12 条规则下面添加项目特定规则（技术栈、测试命令、错误模式）。合并后不要超过 200 行，超过这个限度，合规率会下降。

如何安装

两步：

1# 1. 将 Karpathy 的 4 条规则基线追加到你的 CLAUDE.md
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. 将本文中的规则 5-12 粘贴到下面

保存到你的仓库根目录。>> 很重要，它会追加到你现有的 CLAUDE.md 中，而不是覆盖你已经有的任何项目特定规则。

心智模型

CLAUDE.md 不是一个愿望清单。它是一个行为契约，用于堵住你观察到的特定失败模式。

每条规则都应该回答：这条规则防止了什么错误？

Karpathy 的 4 条规则防止了他在 2026 年 1 月看到的失败模式： 无声的假设、过度工程化、连带损害、弱成功标准。它们是基础性的。不要跳过它们。

我添加的 8 条规则防止了在 2026 年 5 月出现的失败模式： 没有预算的 Agent 循环、没有检查点的多步骤任务、不测试的测试、隐藏着静默失败的静默成功。它们是补充性的。

你的情况可能会有所不同。如果你不运行多步骤流水线，规则 10 就不重要。如果你的代码库有一种由 linting 强制执行的一致风格，规则 11 就是多余的。阅读这 12 条规则，保留那些与你实际犯过的错误相对应的规则，丢弃其余的。

一个针对你真实失败模式调整过的 6 条规则 CLAUDE.md，胜过一条有 6 条你永远用不上的规则的 12 条规则 CLAUDE.md。

完

Karpathy 在 2026 年 1 月的帖子是一次吐槽。Forrest Chang 把它变成了 4 条规则。120,000 名开发者给结果点了星标。他们中的大多数人今天仍在运行这 4 条规则。

模型已经改进。生态系统已经改变。多步骤 Agent、钩子级联、技能加载、多代码库工作——Karpathy 写他的帖子时，这些都不存在。这 4 条规则没有解决它们。它们不是错的；它们是不完整的。

再加 8 条规则。在 30 个代码库上测试了 6 周。错误率从 41% 降到 3%。

收藏本文，今晚就把这 12 条规则粘贴到你的 CLAUDE.md 中。如果它为你省下了一周因 Claude 错误转向而浪费的时间，请转发分享。

Telegram 频道，每日获取 Claude 优化技巧：

*https://t.me/+_ZWrQN7GuDA3ZDEy*