CLAUDE.md 12 条规则：从 Karpathy 4 条到完整行为契约

从 4 条到 12 条

2026 年 1 月底，Andrej Karpathy 发推抱怨 Claude 写代码的三个失败模式：静默错误假设、过度复杂化、对不该碰的代码造成正交损伤。

Forrest Chang 把这些抱怨打包成 4 条行为规则，放进一个 CLAUDE.md 文件，丢到 GitHub。第一天 5,828 星，两周 6 万收藏，今天 12 万星——2026 年增长最快的单文件仓库。

Mnimiy 在 30 个代码库上测试了 6 周。4 条规则有效：原本约 40% 的错误率在它们擅长的任务上降到 3% 以下。但这个模板是为 2026 年 1 月的代码编写错误建的。到了 5 月，Claude Code 生态有了新问题——Agent 冲突、hook 级联、skill 加载冲突、跨会话的多步工作流断裂。

所以 Mnimiy 加了 8 条规则。

Karpathy 的 4 条基础

Rule 1 — Think Before Coding

静默假设是杀手。Claude 经常"觉得"它理解了你的意图，然后基于错误的假设写一堆代码。规则要求：显式陈述假设，有歧义时提问而非猜测，存在多种解释时呈现多种可能，有更简单方案时 push back。

Rule 2 — Simplicity First

最小代码解决问题。不加推测性功能，不为单次使用代码造抽象。测试标准：资深工程师会不会说这过度复杂了？如果是，简化。

Rule 3 — Surgical Changes

只碰必须碰的。不"改进"相邻代码、注释或格式。不重构没坏的东西。匹配现有风格。

Rule 4 — Goal-Driven Execution

定义成功标准，循环直到验证。不给步骤清单，给成功画像然后迭代。强的成功标准让 Agent 能独立循环。

这 4 条关闭了约 40% 的无监督 Claude Code 会话中的失败模式。剩下 60% 活在下面的缝隙里。

新增的 8 条规则

每条都来自一个 Karpathy 4 条不够用的真实时刻。

Rule 5 — Use the model only for judgment calls

用 Claude 做：分类、起草、总结、从非结构化文本中提取。

不要用 Claude 做：路由、重试、状态码处理、确定性转换。

如果一个状态码已经回答了问题，纯代码就该回答。

真实时刻：代码调用 Claude 来"决定是否在 503 时重试"，前两周工作完美，然后开始不稳定——因为模型开始把请求体当作决策上下文来读。重试策略变成随机的，因为 prompt 是随机的。

Rule 6 — Token budgets are not advisory

单任务预算：4,000 tokens
单会话预算：30,000 tokens

如果任务接近预算，总结并重新开始。不要硬撑。暴露越界 > 静默超支。

真实时刻：一次调试会话跑了 90 分钟。模型很乐意在同一个 8KB 错误信息上迭代，逐渐丢失它已经试过哪些修复的追踪。到最后，它在建议 40 条消息前就被拒绝过的修复。Token 预算会在第 12 分钟杀死它。

Rule 7 — Surface conflicts, don't average them

如果代码库中两个现有模式矛盾，不要混合它们。选一个（更新的/测试更充分的），解释为什么，标记另一个待清理。"平均"代码同时满足两条规则是最差的代码。

真实时刻：代码库有两种错误处理模式——一种 async/await 加显式 try/catch，一种用全局错误边界。Claude 写的新代码两种都做了。双重错误处理器。花了 30 分钟才搞清楚为什么错误被吞了两次。

Rule 8 — Read before you write

在文件中添加代码前，读文件的导出、直接调用方、任何明显的共享工具。如果你不理解现有代码为什么这样结构，先问。"看起来是正交的"是这个代码库里最危险的短语。

真实时刻：Claude 在没读过的现有相同函数旁边加了一个新函数。两者做同样的事。新函数因为导入顺序优先。旧函数 6 个月来一直是真相来源。

Rule 9 — Tests verify intent, not just behavior

每个测试必须编码为什么行为重要，不只是做什么。像 expect(getUserName()).toBe('John') 这样的测试如果函数接受硬编码 ID 就毫无价值。如果你写不出一个会在业务逻辑变化时失败的测试，那这个函数是错的。

真实时刻：Claude 为一个 auth 函数写了 12 个测试。全通过了。生产环境 auth 坏了。测试在测函数返回了"某个东西"，不是它返回了"正确的东西"。函数通过是因为它返回常量。

Rule 10 — Checkpoint after every significant step

多步任务中每完成一步：总结做了什么、验证了什么、还剩什么。不要从一个你无法向我描述的状态继续。如果丢失追踪，停下来重述。

真实时刻：一个 6 步重构在第 4 步出错。等注意到时，Claude 已经在坏状态上做了第 5 和第 6 步。解开比重做整个事情花更长时间。检查点会在第 4 步抓住它。

Rule 11 — Match the codebase's conventions, even if you disagree

如果代码库用 snake_case 而你偏好 camelCase：用 snake_case。如果代码库用 class-based 组件而你偏好 hooks：用 class-based。不同意是另一个对话。在代码库内，一致性 > 品味。如果你真觉得约定有害，暴露出来。不要静默分叉。

真实时刻：Claude 在一个 class 组件代码库中引入 React hooks。它们工作了。但也破坏了代码库的测试模式——那些模式假设 componentDidMount。花了半天移除和重写。

Rule 12 — Fail loud

如果你不能确定某事工作了，显式说出来。"迁移完成"如果 30 条记录被静默跳过就是错的。"测试通过"如果你跳过了任何测试就是错的。"功能工作"如果你没验证我要求的边界情况就是错的。默认暴露不确定性，不是隐藏它。

真实时刻：Claude 说数据库迁移"成功完成"。它静默跳过了 14% 命中约束冲突的记录。跳过被记录了但没被暴露。11 天后报告开始看起来不对时才发现问题。

测试结果

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

配置	错误率	合规率
无 CLAUDE.md	41%	—
Karpathy 4 条	11%	78%
12 条完整版	3%	76%

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

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

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

原 4 条不够用的 4 个场景

长时间运行的 Agent 任务：Karpathy 的规则针对 Claude 写代码的瞬间。对 Claude 运行多步 pipeline 时发生了什么沉默。没有预算规则、没有检查点规则、没有"大声失败"规则。Pipeline 漂移。
多代码库一致性："匹配现有风格"假设只有一种风格。在 12 个服务的 monorepo 中，Claude 得选哪种风格。原规则不告诉它怎么选。它随机选或平均。
测试质量：Goal-Driven Execution 把"测试通过"当作成功。没说测试必须有意义。结果是测试什么都没测到但让 Claude 很自信。
生产 vs 原型：同样的 4 条保护生产代码不被过度工程，也拖慢合法需要 100 行推测性脚手架来摸索方向的原型。Karpathy 的"Simplicity First"在早期代码上过度触发。

12 条规则的完整模板

# 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 行，超过后合规率会下降。

关键原则

CLAUDE.md 不是愿望清单。它是关闭你观察到的具体失败模式的行为契约。

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

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

新增的 8 条防止 2026 年 5 月出现的失败模式：没有预算的 Agent 循环、没有检查点的多步任务、不测任何东西的测试、隐藏静默失败的静默成功。它们是补充。

你的情况会不同。如果你不运行多步 pipeline，Rule 10 不重要。如果你的代码库有一种被 lint 强制执行的一致风格，Rule 11 是冗余的。读 12 条，保留映射到你实际犯过的错误的那些，丢掉其余的。

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