编者按：2026 年 1 月，Andrej Karpathy 对 Claude 写代码的吐槽，引出了一个看似很小、但在 AI 编程工作流中极其关键的文件：CLAUDE.md。Forrest Chang 随后将这些问题整理成 4 条行为规则，试图约束 Claude 在编码时常见的错误：静默假设、过度工程化、误伤无关代码，以及缺乏清晰的成功标准。

但几个月后，Claude Code 的使用场景已经不再只是「让模型写一段代码」。随着多步骤 Agent、hook 链式触发、skill 加载和多代码库协作成为常态，新的失败模式也开始出现：模型在长任务中失控、测试通过却没有验证真实逻辑、迁移完成但静默跳过错误、不同代码风格被错误混合。

本文作者在 6 周内测试了 30 个代码库，并在 Karpathy 原有 4 条规则基础上新增 8 条规则，试图覆盖 AI 编程从单次补全走向 Agent 化协作后的新问题。

以下为原文：

2026 年 1 月下旬，Andrej Karpathy 发了一条推文串，吐槽 Claude 写代码的方式。他指出了三类典型问题：在没有说明的情况下做出错误假设、过度复杂化，以及对原本不该改动的代码造成无关破坏。

Forrest Chang 看到了这条推文串，把其中的抱怨整理成 4 条行为规则，写进一个单独的 CLAUDE.md 文件，并发布到了 GitHub。这个项目上线第一天就获得了 5,828 个 Star，两周内被收藏 60,000 次，如今已有 120,000 个 Star，成为 2026 年增长最快的单文件代码仓库。

随后，我在 6 周时间里，用 30 个代码库对它进行了测试。

这 4 条规则确实有效。过去大约 40% 概率会出现的错误，在适合这些规则发挥作用的任务中，下降到了 3% 以下。但问题在于，这个模板最初是为了解决 1 月份 Claude 写代码时出现的错误。

到了 2026 年 5 月，Claude Code 生态面临的问题已经不同了：Agent 之间相互冲突、hook 链式触发、skill 加载冲突，以及跨会话多步骤工作流中断等。

所以，我又加入了 8 条规则。下面是完整的 12 条规则版 CLAUDE.md：每一条为什么值得加入，以及原版 Karpathy 模板会在哪 4 个地方悄悄失效。

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

为什么这很重要

Claude Code 的 CLAUDE.md，是整个 AI 编程技术栈里最被低估的文件。大多数开发者通常会犯三类错误：

第一，把它当成偏好垃圾桶，把自己所有习惯都塞进去，最后膨胀到 4000 多个 token，规则遵守率掉到 30%。

第二，干脆完全不用，每次都重新 prompt。这会造成 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 每一步该怎么做，而是告诉它成功结果应该是什么样，让它自己迭代。

这 4 条规则，能解决我在无人监督的 Claude Code 会话中看到的大约 40% 的失败模式。剩下约 60% 的问题，则藏在下面这些空白地带。

我新增的 8 条规则，以及为什么

每一条规则，都来自一个真实时刻：Karpathy 原来的 4 条规则已经不够用了。下面我会先讲那个场景，再给出对应规则。

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

Karpathy 的规则没有覆盖这一点。于是模型开始决定一些本该由确定性代码处理的问题：是否重试一次 API 调用、如何路由一条消息、什么时候升级处理。结果是，每周的判断都不一样。你得到的是一种按每 token 0.003 美元计费的、不稳定的 if-else。

那个时刻是这样的：有一段代码会调用 Claude 来「判断遇到 503 时是否应该重试」。它一开始运行得很好，持续了两周，后来突然变得不稳定，因为模型开始把请求体也当作判断上下文。重试策略变得随机，因为 prompt 本身就是随机的。

规则 6：设置硬性 token 预算，没有例外

没有预算约束的 CLAUDE.md，就等于一张空白支票。每一次循环都有可能失控，变成一次 50,000 token 的上下文倾倒。模型不会自己停下来。

那个时刻是这样的：一次调试会话持续了 90 分钟。模型一直在围绕同一段 8KB 的错误信息反复迭代，并逐渐忘记自己已经尝试过哪些修复方案。到最后，它开始提出 40 条消息之前我已经否定过的方案。如果有 token 预算，这个过程在第 12 分钟就该被终止。

规则 7：暴露冲突，不要折中平均

当代码库里的两个部分互相矛盾时，Claude 会试图同时讨好两边，结果写出来的是一团不连贯的代码。

那个时刻是这样的：一个代码库里存在两套错误处理模式，一套是 async/await 加显式 try/catch，另一套是全局错误边界。Claude 写出的新代码把两套都用了。结果错误处理被做了两遍。我花了 30 分钟才弄明白，为什么错误被吞掉了两次。

规则 8：先读，再写

Karpathy 的「外科手术式修改」告诉 Claude 不要改动相邻代码。但它没有告诉 Claude：先理解相邻代码。没有这一条，Claude 会写出和 30 行之外既有代码相冲突的新代码。

那个时刻是这样的：Claude 在一个已有函数旁边新增了一个功能完全相同的函数，因为它没有先读原来的函数。两个函数做的是同一件事。但由于 import 顺序的关系，新函数覆盖了旧函数，而旧函数已经作为事实上的唯一标准存在了 6 个月。

规则 9：测试不是可选项，但测试本身不是目标

Karpathy 的「以目标为导向执行」暗示测试可以作为成功标准。但在实践中，Claude 会把「测试通过」当成唯一目标，于是写出一些能通过浅层测试、却会破坏其他东西的代码。

那个时刻是这样的：Claude 为一个认证函数写了 12 个测试，全部通过。但生产环境里的认证逻辑坏了。那些测试只是在验证函数「返回了某个东西」，而不是验证它是否返回了正确的东西。函数之所以能通过测试，是因为它返回的是一个常量。

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

Karpathy 的模板默认交互是一次性的。但真实的 Claude Code 工作往往是多步骤的：跨 20 个文件重构、在一个会话里构建功能、跨多个 commit 调试。如果没有检查点，一步走错，前面所有进度都可能丢失。

那个时刻是这样的：一个 6 步重构任务在第 4 步出错了。等我发现时，Claude 已经在错误状态之上继续完成了第 5 步和第 6 步。拆解修复花的时间，比重做整个任务还长。如果有检查点，第 4 步就能发现问题。

规则 11：约定优先于新意

在一个已经有成熟模式的代码库里，Claude 喜欢引入自己的写法。哪怕它的写法「更好」，引入第二套模式本身，也比任何一种单一模式都更糟。

那个时刻是这样的：Claude 在一个基于 class component 的 React 代码库里引入了 hooks。它确实能运行。但它同时破坏了代码库原有的测试模式，因为那些测试依赖 componentDidMount。最后花了半天时间才把它删掉并重写。

规则 12：要显性失败，不要静默失败

Claude 最昂贵的失败，往往是那些看起来像成功的失败。一个函数「能跑」，但返回了错误数据；一次 migration「完成了」，但跳过了 30 条记录；一个测试「通过了」，但只是因为断言本身是错的。

那个时刻是这样的：Claude 说一次数据库迁移「成功完成」。但实际上，它静默跳过了 14% 触发约束冲突的记录。跳过行为被写进了日志，却没有被明确暴露出来。11 天后，当报表数据开始异常时，我们才发现问题。

数据结果

我在 6 周时间里，追踪了同一组 50 个代表性任务，覆盖 30 个代码库，测试了三种配置。

错误率指的是：任务需要被纠正或重写，才能匹配原始意图。计入的错误包括：静默错误假设、过度工程化、无关破坏、静默失败、违反约定、冲突折中、漏掉检查点。

遵守率指的是：当某条规则适用时，Claude 有多大概率会显性应用这条规则。

真正有意思的结果，不只是错误率从 41% 降到 3%。更重要的是，从 4 条规则扩展到 12 条规则，几乎没有增加遵守负担，遵守率只是从 78% 变成 76%，但错误率又下降了 8 个百分点。新增规则覆盖的是原来 4 条规则没有处理的失败模式，它们并没有争夺同一块注意力预算。

Karpathy 模板会在哪些地方悄悄失效

即便不加入新规则，原来的 4 条规则模板也至少在 4 个地方不够用。

第一，长时间运行的 Agent 任务。
Karpathy 的规则主要针对 Claude 正在写代码的那一刻。但当 Claude 在运行一个多步骤 pipeline 时，会发生什么？原模板没有预算规则，没有检查点规则，也没有「大声失败」规则。于是 pipeline 会慢慢漂移。

第二，多代码库一致性。
「匹配现有风格」默认只有一种风格。但在一个拥有 12 个服务的 monorepo 里，Claude 必须选择到底匹配哪一种风格。原始规则没有告诉它怎么选。于是它要么随机选择，要么把几种风格平均混合。

第三，测试质量。
「以目标为导向执行」会把「测试通过」视为成功，却没有说明测试本身必须有意义。结果就是，Claude 写出一些几乎什么都没验证的测试，但这些测试会让它误以为自己很有把握。

第四，生产环境与原型阶段的差异。
同样的 4 条规则，可以防止生产代码被过度工程化，但也可能拖慢原型开发。因为原型阶段有时确实需要 100 行探索性脚手架，先摸清方向。Karpathy 的「简单优先」在早期代码里容易过度触发。

这 8 条新增规则并不是要取代 Karpathy 的原始 4 条规则，而是在修补它们的空白：原模板对应的是 2026 年 1 月那种偏自动补全式的代码写作场景；而到了 2026 年 5 月，Claude Code 已经进入由 Agent 驱动的、多步骤、多代码库协作环境，两者面对的问题并不一样。

哪些方法没有奏效

在最终确定这 12 条规则之前，我也尝试过一些其他方案。

加入我在 Reddit / X 上看到的规则。
其中大多数，要么只是用不同说法重复 Karpathy 原来的 4 条规则，要么是无法泛化的领域特定规则，比如「始终使用 Tailwind class」。最后都删掉了。

超过 12 条规则。
我最多测试到 18 条。超过 14 条后，遵守率从 76% 掉到了 52%。200 行的上限是真实存在的。超过这个长度后，Claude 就会开始模式匹配成「这里有规则」，而不是真的逐条阅读规则。

依赖某些工具存在的规则。
比如「始终使用 eslint」，一旦项目里没有安装 eslint，这条规则就会失效，而且是静默失效。后来我把它改成了不依赖具体工具的表达，比如把「使用 eslint」改成「遵循代码库中已经强制执行的风格」。

在 CLAUDE.md 里放示例，而不是规则。
示例比规则更占上下文。三个示例消耗的上下文，差不多相当于 10 条规则，而且 Claude 很容易对示例过拟合。规则是抽象的，示例是具体的。所以，应当使用规则。

「小心一点」「认真思考」「专注一点」。
这些都是噪音。这类指令的遵守率掉到了大约 30%，因为它们无法被检验。后来我把它们替换成了更具体的命令式规则，比如「明确说明假设」。

告诉 Claude 要像「资深工程师」一样。
这没有用。Claude 本来就觉得自己像资深工程师。真正的问题不在于它是否这样认为，而在于它是否这样执行。命令式规则可以缩小这个差距，身份提示词不行。

完整的 12 条规则版 CLAUDE.md

以下是可直接复制粘贴使用的完整版本。

暂时无法在飞书文档外展示此内容

将它保存为仓库根目录下的 CLAUDE.md。在这 12 条规则下面，再添加项目专属规则，比如技术栈、测试命令、错误模式等。整体不要超过 200 行，超过之后，规则遵守率就会明显下降。

如何安装

两步即可：

1. 将 Karpathy 的 4 条基础规则追加到你的 CLAUDE.md 中
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. 将本文中的规则 5–12 粘贴到下面

把文件保存在仓库根目录。这里的 >> 很重要，它的作用是追加到已有的 CLAUDE.md，而不是覆盖你已经写好的项目专属规则。

心智模型

CLAUDE.md 不是愿望清单，而是一份行为契约，用来封堵你已经观察到的具体失败模式。

每一条规则都应该回答一个问题：它能防止什么错误？

Karpathy 的 4 条规则，防的是他在 2026 年 1 月看到的失败模式：静默假设、过度工程化、无关破坏、成功标准薄弱。它们是基础，不要跳过。

我新增的 8 条规则，防的是 2026 年 5 月之后出现的新失败模式：没有预算约束的 Agent 循环、没有检查点的多步骤任务、看似测试了但其实没测到关键逻辑的测试，以及把静默失败包装成静默成功的问题。它们是增量补丁。

当然，具体效果因人而异。如果你不跑多步骤 pipeline，规则 10 对你就没那么重要。如果你的代码库只有一种统一风格，而且已经由 lint 强制执行，规则 11 就是冗余的。读完这 12 条后，保留那些真正对应你实际犯过错误的规则，删掉其余部分。

一份针对真实失败模式定制的 6 条规则版 CLAUDE.md，胜过一份有 12 条规则、其中 6 条你永远用不上的版本。

结语

Karpathy 在 2026 年 1 月的那条推文，本质上是一场抱怨。Forrest Chang 把它变成了 4 条规则。最终，12 万开发者给这个结果点了 Star。而其中大多数人，今天仍然只在使用那 4 条规则。

模型已经进步，生态也已经变了。多步骤 Agent、hook 链式触发、skill 加载、多代码库协作——这些在 Karpathy 写下那条推文时都还不存在。原来的 4 条规则并没有解决这些问题。它们不是错了，而是不完整了。

新增 8 条规则。6 周时间，覆盖 30 个代码库的测试。错误率从 41% 降到 3%。

今晚就收藏这篇文章，把这 12 条规则粘贴进你的 CLAUDE.md。如果它帮你少走一周 Claude 弯路，欢迎转发。

[原文链接]