（译文）重温：Karpathy 的 4 条 CLAUDE.md 规则将 Claude 错误率从 41% 降至 11%——历经 30 个代码库后，我又加了 8 条

2026 年 1 月底，Andrej Karpathy 发了一条推文抱怨 Claude 写代码的问题。三种失败模式：沉默的错误假设、过度复杂化、对不该碰的代码造成正交破坏。

Forrest Chang 读了这个帖子，把抱怨打包成 4 条行为规则放进一个 CLAUDE.md 文件，丢到了 GitHub 上。第一天 5828 星。两周 6 万书签。今天 12 万星。 2026 年增长最快的单文件仓库。

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

这 4 条规则确实有效。在它们擅长的任务上，错误率从 ~40% 降到了 3% 以下。但那个模板是为解决 1 月的代码写作问题而建的。

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 --- Think Before Coding（编码前先思考）。 不要沉默假设。陈述你的假设。暴露权衡。不确定时先问，不要猜。有更简单的方案时主动反馈。

规则 2 --- Simplicity First（简单优先）。 解决问题所需的最少代码。不做推测性功能。不对单次使用的代码做抽象。如果高级工程师会说这过度设计了------简化。

规则 3 --- Surgical Changes（外科手术式修改）。 只碰必须碰的。不要"改进"相邻代码、注释或格式化。不要重构没坏的东西。匹配现有风格。

规则 4 --- Goal-Driven Execution（目标驱动执行）。 定义成功标准。循环迭代直到验证通过。不要告诉 Claude 按步骤做，告诉它成功长什么样，让它自己迭代。

这四条堵住了我在无人监督的 Claude Code 会话中看到的约 40% 的失败模式。剩下的 ~60% 藏在下面的空白里。

我加的 8 条规则（以及为什么）

每条都来自一个真实的时刻------Karpathy 的 4 条不够用的时刻。我先展示那个时刻，再给出规则。

规则 5 --- 别让模型做非语言工作

Karpathy 的规则对此只字未提。模型决定了一些本该由确定性代码决定的事情------是否重试 API 调用、如何路由消息、何时升级。每周做不同的决定。一个脆弱的 if-else，花 $0.003 每 token。

text 复制代码

## 规则 5 --- 模型只做判断类工作
用 Claude 做：分类、起草、摘要、从非结构化文本中提取信息。
不要用 Claude 做：路由、重试、状态码处理、确定性转换。
如果状态码已经能回答问题，普通代码就能回答问题。

那个时刻： 用 Claude "判断 503 时是否重试"的代码完美运行了两周，然后开始不稳定------因为模型开始读取请求体作为决策上下文。重试策略变得随机，因为 prompt 是随机的。

规则 6 --- 硬性 token 预算，没有例外

没有预算的 CLAUDE.md 是空白支票。每个循环都有机会螺旋上升成 50000 token 的上下文转储。模型自己不会停。

text 复制代码

## 规则 6 --- Token 预算不是建议性的
每任务预算：4000 token。
每会话预算：30000 token。
如果任务接近预算，总结并重新开始。不要硬撑。
主动暴露超预算 > 默默超支。

那个时刻： 一个调试会话运行了 90 分钟。模型非常乐意在同一个 8KB 错误信息上反复迭代，逐渐忘记它已经试过哪些修复。到最后，它在建议我 40 条消息前就已经否决过的修复。token 预算能在第 12 分钟就把它终止。

规则 7 --- 暴露冲突，不要取平均

当代码库的两个部分有分歧时，Claude 试图两全其美。结果是自相矛盾的代码。

text 复制代码

## 规则 7 --- 暴露冲突，不要取平均
如果代码库中两种已有模式互相矛盾，不要混合它们。
选一个（更新的 / 测试更充分的），解释为什么，标记另一个待清理。
"平均"式代码------同时满足两套规则的代码------是最差的代码。

那个时刻： 一个代码库有两种错误处理模式------一种用 async/await 加显式 try/catch，一种用全局 error boundary。Claude 写的新代码两种都用上了。错误处理器翻倍。花了我 30 分钟才搞明白为什么错误被吞了两次。

规则 8 --- 写之前先读

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

text 复制代码

## 规则 8 --- 写之前先读
在文件中添加代码前，先读文件的导出、直接调用方、以及任何明显的共享工具函数。
如果你不理解为什么现有代码是那样组织的，先问再添加。
"看起来跟我不相关"是这个代码库里最危险的一句话。

那个时刻： Claude 在一个已有相同函数的文件旁边加了一个新函数，但它没读那个旧函数。两个函数做同样的事。新函数因为 import 顺序先被执行。旧函数已经当了 6 个月的事实标准。

规则 9 --- 测试不是可选项，但也不是目标

Karpathy 的目标驱动执行暗示测试是成功标准。实际上，Claude 把"测试通过"当成唯一目标，写出通过浅层测试但破坏一切的代码。

text 复制代码

## 规则 9 --- 测试验证的是意图，不只是行为
每个测试必须编码为什么这个行为重要，而不只是它做什么。
像 `expect(getUserName()).toBe('John')` 这样的测试，如果函数拿的是硬编码 ID，那就一文不值。
如果你写不出一个在业务逻辑变化时会失败的测试，那么这个函数是错的。

那个时刻： Claude 为一个 auth 函数写了 12 个测试。全部通过。线上 auth 是坏的。测试验证的是函数返回了什么，而不是返回的是不是正确的东西。函数通过是因为它返回了一个常量。

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

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

text 复制代码

## 规则 10 --- 每个重要步骤后做检查点
完成多步骤任务中的每一步后：总结做了什么、验证了什么、还剩什么。
不要从一个你无法描述回来的状态继续。
如果跟丢了，停下来重新陈述。

那个时刻： 一个 6 步重构在第 4 步出错。到我发现时，Claude 已经在错误状态上又做了第 5 和第 6 步。拆解比重新做一遍更花时间。检查点能在第 4 步就截住。

规则 11 --- 惯例优于新颖

在有既定模式的代码库里，Claude 喜欢引入自己的模式。即使它的方式"更好"，引入两种模式比单独任何一种都更差。

text 复制代码

## 规则 11 --- 匹配代码库的惯例，即使你不同意
如果代码库用 snake_case 而你更喜欢 camelCase：用 snake_case。
如果代码库用 class 组件而你更喜欢 hooks：用 class。
意见分歧是另一个对话。在代码库内部，一致性 > 品味。
如果你真心认为某个惯例有害，主动提出。不要悄悄地分叉。

那个时刻： Claude 在一个 class 组件代码库里引入了 React hooks。它们能跑。但它们也破坏了代码库的测试模式------那些测试假设了 componentDidMount。花了半天删除并重写。

规则 12 --- 失败要可见，不要沉默

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

text 复制代码

## 规则 12 --- 失败要大声说出来
如果你不能确定某件事做对了，明确说出来。
如果 30 条记录被悄悄跳过，"迁移完成"就是错的。
如果你跳过了任何测试，"测试通过"就是错的。
如果你没有验证我问过的边缘情况，"功能正常"就是错的。
默认暴露不确定性，不要隐藏它。

那个时刻： Claude 说数据库迁移"成功完成"。它悄悄跳过了 14% 的记录------那些记录触发了约束违规。跳过被记录了但没被暴露。11 天后报表开始不对劲时才发现问题。

数据

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

错误率（Mistake rate） = 任务需要修正或重写才能匹配意图。计次：沉默错误假设、过度工程、正交破坏、沉默失败、惯例违规、冲突取平均、缺失检查点。

遵从率（Compliance） = Claude 在规则适用时实际可见地应用规则的频率。

有意思的结果不是从 41% 降到 3% 的标题数字。而是从 4 条规则到 12 条规则几乎没增加遵从率开销（78% → 76%），但错误率又降了 8 个百分点。新规则覆盖了原始 4 条没处理的失败模式------它们不争抢同一个注意力预算。

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

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

1. 长运行 agent 任务。 Karpathy 的规则针对 Claude 正在写代码的那一刻。它们对 Claude 运行多步骤流水线时会发生什么只字未提。没有预算规则。没有检查点规则。没有"大声失败"规则。流水线会漂移。

2. 多代码库一致性。 "匹配现有风格"假设只有一种风格。在 12 个服务的 monorepo 里，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（可直接粘贴）

text 复制代码

# CLAUDE.md --- 12-rule template

These rules apply to every task in this project unless explicitly overridden.
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

## Rule 1 --- Think Before Coding
State assumptions explicitly. If uncertain, ask rather than guess.
Present multiple interpretations when ambiguity exists.
Push back when a simpler approach exists.
Stop when confused. Name what's unclear.

## Rule 2 --- Simplicity First
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
Test: would a senior engineer say this is overcomplicated? If yes, simplify.

## Rule 3 --- Surgical Changes
Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Don't refactor what isn't broken. Match existing style.

## Rule 4 --- Goal-Driven Execution
Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.

## Rule 5 --- Use the model only for judgment calls
Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.

## Rule 6 --- Token budgets are not advisory
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.

## Rule 7 --- Surface conflicts, don't average them
If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.

## Rule 8 --- Read before you write
Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

## Rule 9 --- Tests verify intent, not just behavior
Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.

## Rule 10 --- Checkpoint after every significant step
Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.

## Rule 11 --- Match the codebase's conventions, even if you disagree
Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.

## Rule 12 --- Fail loud
"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.

保存为仓库根目录的 CLAUDE.md。在 12 条之下添加项目特定规则（技术栈、测试命令、错误模式）。总共不要超过 200 行，超过后遵从率会下降。

怎么安装

两步：

text 复制代码

# 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 循环、没有检查点的多步骤任务、不测试的测试、隐藏失败的沉默成功。它们是累加的。

你的效果会不同。如果你不跑多步骤流水线，规则 10 就不重要。如果你的代码库有 linting 强制执行的一致风格，规则 11 就是多余的。读完 12 条，保留那些对应你实际犯过的错误的，删掉其余的。

一个针对你真实失败模式调优的 6 条规则 CLAUDE.md，胜过有 6 条你永远不需要的 12 条规则版本。

完

Karpathy 2026 年 1 月的帖子是一次抱怨。Forrest Chang 把它变成了 4 条规则。12 万开发者收藏了结果。他们中的大多数人今天还在跑这 4 条规则。

模型进步了。生态变了。多步骤 agent、hook 级联、skill 加载、多代码库工作------这些都是 Karpathy 发帖时不存在的东西。这 4 条规则不处理它们。它们没有错；它们是不完整的。

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

收藏本文，今晚就把 12 条规则粘贴进你的 CLAUDE.md。如果它省了你一周的 Claude 走弯路，转发。