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

2026 年 1 月下旬，Andrej Karpathy 发了一条推文，抱怨 Claude 编写代码的方式。他指出了三种故障模式：静默的错误假设、过度复杂化，以及对不应触碰的代码造成正交损害。

Forrest Chang 阅读了这条推文，将这些抱怨打包成单文件 CLAUDE.md 中的 4 条行为规则，并发布到了 GitHub 上。它在第一天就获得了 5,828 个星标。两周内收藏量达到 60,000。至今已获得 120,000 个星标。 这是 2026 年增长最快的单文件仓库。

随后，我在 6 周内对其在 30 个代码库上进行了测试。

这 4 条规则确实有效。在发挥其优势的任务中，原本约 40% 时间的错误率降至 3% 以下。但该模板是为了修复 1 月份的代码编写错误而构建的。

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

因此，我添加了另外 8 条规则。以下是完整的 12 条规则 CLAUDE.md，每一条规则为何值得存在的原因，以及原始 Karpathy 模板静默失效的 4 个地方。

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

为什么这很重要

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

• 把它当作存储所有偏好的垃圾场，膨胀到 4,000+ tokens，合规率降至 30%

• 完全跳过它，每次都重新提示——浪费 5 倍 tokens，会话间缺乏一致性

• 复制一个模板然后忘记。管用两周，然后随着代码库的变化静默失效

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

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

上限更高。通过下面将要介绍的 8 条额外规则，你不仅覆盖了 Karpathy 抱怨的 2026 年 1 月的代码编写问题，还覆盖了模板编写时尚不存在的 2026 年 5 月的代理编排问题。

原始的 4 条规则

如果你还没有阅读 Forrest Chang 的仓库，这是底线：

规则 1 — 先思考再编码。 没有静默假设。陈述你的假设。揭示权衡。猜测前请询问。当存在更简单的方法时提出异议。

规则 2 — 简单第一。 解决所需的最小代码。没有投机性功能。没有为单次使用代码设计的抽象。如果高级工程师会称之为过度复杂——简化它。

规则 3 — 手术式变更。 只触碰必须触碰的部分。不要“改进”相邻的代码、注释或格式。不要重构未损坏的部分。匹配现有风格。

规则 4 — 目标驱动执行。 定义成功标准。循环直到验证。不要告诉 Claude 遵循哪些步骤，告诉它成功的样子，让它迭代。

这四条规则关闭了我所看到的无人监督的 Claude Code 会话中约 40% 的故障模式。剩下的约 60% 存在于下面的差距中。

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

每一条都源于 Karpathy 的 4 条规则不够用的真实时刻。我将展示那个时刻，然后是规则。

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

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

那个时刻： 一段调用 Claude 来“决定是否应在 503 错误时重试”的代码在两周内运行完美，然后开始不稳定，因为模型开始将请求体作为决策的上下文。重试策略是随机的，因为提示词是随机的。

规则 6 — 硬性 token 预算，无例外

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

那个时刻： 一个调试会话运行了 90 分钟。模型很乐意在相同的 8KB 错误消息上迭代，逐渐忘记它已经尝试过哪些修复。到最后，它建议的修复是我 40 条消息前就拒绝过的。token 预算本可以在第 12 分钟就终止它。

规则 7 — 揭示冲突，不要取平均值

当代码库的两个部分不一致时，Claude 试图取悦两者。结果是不连贯的。

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

规则 8 — 先读再写

Karpathy 的“手术式变更”告诉 Claude 不要触碰相邻代码。它没有告诉 Claude 要先理解相邻代码。没有这一点，Claude 编写的新代码会与 30 行外的现有代码冲突。

那个时刻： Claude 在一个它没有读取的现有相同函数旁边添加了一个函数。这两个函数做同样的事情。新函数因为导入顺序而优先。旧函数在 6 个月内一直是真理的来源。

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

Karpathy 的目标驱动执行隐含测试作为成功标准。在实践中，Claude 将“测试通过”视为唯一目标，并编写通过浅层测试但破坏其他一切的代码。

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

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

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

那个时刻： 一个 6 步重构在第 4 步出错。当我注意到时，Claude 已经在损坏的状态上完成了第 5 和第 6 步。解开纠缠比重新做所有事情花的时间更长。检查点本可以在第 4 步捕获它。

规则 11 — 惯例胜于新奇

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

那个时刻： Claude 在类组件代码库中引入了 React 钩子。它们工作了。但它们也破坏了代码库的测试模式，这些模式假设了 componentDidMount。花了半天时间移除和重写。

规则 12 — 显式失败，不要静默失败

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

那个时刻： Claude 说数据库迁移“成功完成”。它静默跳过了 14% 遇到约束违规的记录。跳过被记录但未表面化。11 天后当报告开始看起来不对劲时发现了问题。

数据

我在 6 周内跟踪了 30 个代码库中相同的 50 个代表性任务。三种配置：

错误率 = 任务需要纠正或重写以匹配意图。计数：静默错误假设、过度工程、正交损害、静默失败、惯例违规、冲突平均、错过检查点。

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

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

Karpathy 模板静默失效的地方

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

1. 长运行代理任务。 Karpathy 的规则针对 Claude 编写代码的那一刻。它们对 Claude 运行多步骤管道时发生的事情保持沉默。没有预算规则。没有检查点规则。没有“大声失败”规则。管道漂移。

2. 多代码库一致性。 “匹配现有风格”假设一种风格。在具有 12 个服务的 monorepo 中，Claude 必须选择哪种风格。原始规则没有告诉它如何选择。它随机选择或取平均值。

3. 测试质量。 目标驱动执行将“测试通过”视为成功。没有说测试必须有意义。结果是测试没有测试任何有用内容但让 Claude 自信的测试。

4. 生产 vs 原型。 保护生产代码免于过度工程的相同 4 条规则也拖慢了真正需要 100 行投机性脚手架来确定方向的原型。Karpathy 的“简单第一”在早期代码上过度触发。

添加的 8 条规则不取代 Karpathy 的 4 条。它们修补了他的模型、2026 年 1 月、自动补全式编码与 2026 年 5 月的代理驱动、多步骤、多代码库工作不匹配的差距。

什么不起作用

我在确定 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（复制粘贴即用）

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

如何安装

两步：

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

心理模型

CLAUDE.md 不是愿望清单。它是一个行为合同，关闭你观察到的特定故障模式。

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

Karpathy 的 4 条防止了他在 2026 年 1 月看到的故障模式： 静默假设、过度工程、正交损害、弱成功标准。它们是基础性的。不要跳过它们。

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

你的效果会有所不同。如果你不运行多步骤管道，规则 10 不重要。如果你的代码库有一种由 linting 执行的一致风格，规则 11 是多余的。阅读这 12 条，保留那些映射到你实际犯过的错误的规则，丢弃其余的。

一个调整到你真实故障模式的 6 条规则 CLAUDE.md 胜过带有 6 条你永远不需要的规则的 12 条规则。

T H E _ E N D

Karpathy 2026 年 1 月的推文是一个抱怨。Forrest Chang 将其转化为 4 条规则。120,000 名开发者星标的结果。他们中的大多数今天仍在运行 4 条规则。

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

8 条额外规则。30 个代码库的 6 周测试。错误率从 41% 到 3%。

收藏这个，今晚将 12 条规则粘贴到你的 CLAUDE.md 中。如果它节省了你一周的 Claude 错误转向，请转发。

Telegram 获取每日 Claude 优化技巧：https://t.me/+_ZWrQN7GuDA3ZDEy