公众号名称：程叙架构与AI.

作者名称：AI兴观点

发布时间：2026-05-12 19:30

✅点击上方🔺公众号🔺关注我✅

今天刷到一篇特别扎实的文章。作者 Mnilax 花 6 周时间，在 30 个代码库里实测了 Karpathy 提出的 CLAUDE.md 规则，发现确实能把错误率从 41% 压到 3%。但他也说 4 条规则不太够——2026 年 5 月的 Claude Code 生态和 1 月份 Karpathy 写那条推文时已经天差地别了。于是他补了 8 条。

下面是我的全文翻译，原文每一条规则都带一个真实的翻车故事，读完可以直接复制最后的 12 条模板。

2026 年 1 月底，Andrej Karpathy 发了条推文，抱怨 Claude 写代码的方式。三种失败模式：沉默的错误假设、过度复杂化、动到不该动的代码。

Forrest Chang 读到了这条推文，把这三条抱怨打包成 4 条行为规则，写进一个 CLAUDE.md 文件，扔上 GitHub。第一天 5,828 stars。两周 60,000 书签。到今天 120,000 stars。

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

4 条规则确实管用。过去大约 40% 会出错的任务，在规则覆盖的优势场景里降到了 3% 以下。但这个模板是为了修 1 月份的代码编写问题写的。

2026 年 5 月 Claude Code 的问题已经完全不一样了——agent 打架、hook 级联、技能加载冲突、跨 session 的多步骤工作流断掉。

所以我加了 8 条。下面就是全部 12 条规则、每条为什么值得写、以及原始模板在 4 个地方悄悄失效的原因。

想直接抄作业的话，拉到末尾复制完整文件就好。

为什么这事值得关心

CLAUDE.md 是整个 Claude Code 流程里最容易被浪费掉的文件。大多数人要么：

把它当成所有偏好的垃圾堆，膨胀到 4,000 多 token，遵循率跌到 30%

要么直接跳过，每次手动写 prompt——5 倍的 token 浪费，会话之间还没有一致性

要么复制一个模板用一次就忘了

Anthropic 的文档说得很直白：CLAUDE.md 只是建议性的。Claude 大概 80% 的时间会听。超过 200 行后，遵循率急剧下降——重要规则被埋在噪音里了。

Karpathy 的模板用一个文件、65 行、4 条规则，定了一个不错的下限。上限可以更高。加上我下面这 8 条，你覆盖的不只是 Karpathy 在 1 月抱怨的代码编写问题，还有当时根本不存在的 agent 编排问题。

原始 4 条规则

没看过 Forrest Chang 仓库的话，先把这几条记下来：

规则 1——先思考，再编码。 别闷头假设。说你假设了什么，暴露取舍。不确定就问，别猜。有更简单的方案就直接提。

规则 2——简约优先。 只写能解决问题的的最少代码。不写投机功能。不为只用一次的代码做抽象。如果资深工程师看了会说「搞复杂了」——简化。

规则 3——外科手术式修改。 只碰你必须碰的地方。别顺手「改进」旁边的代码、注释或格式。没坏的东西别重构。匹配现有风格。

规则 4——目标驱动执行。 定义成功的标准，循环直到验证通过。不要告诉 Claude 怎么做，告诉它成功长什么样，让它自己迭代。

这 4 条能挡住我见过的无监督 Claude Code 会话里大约 40% 的失败模式。剩下 60% 藏在下面。

我加的 8 条

每一条都来自一个真实的瞬间——Karpathy 那 4 条不够用的瞬间。先看事故现场，再看规则。

规则 5——别让模型干非语言类的活

Karpathy 的规则没提这个。Claude 经常替代码做决策——要不要重试 API 调用、消息怎么路由、什么时候该升级处理。每周决策都不一样。花 $0.003/token 跑一堆摇摇晃晃的 if-else。

事故现场：一段代码让 Claude「决定是否 503 时重试」。前两周好好的，然后开始抽风——模型开始读请求体当决策上下文。重试策略变成了随机策略，因为每次 prompt 都不同。

规则 6——硬性 Token 预算，没得商量

没设预算的 CLAUDE.md 就是一张空头支票。每次循环都可能螺旋膨胀成 50,000 token 的上下文 dump。模型不会自己刹车的。

事故现场：一次 debug 跑了 90 分钟。模型非常开心地对着同一段 8KB 的错误信息反复迭代，逐渐忘了试过哪些修复。到后面它开始推荐我 40 轮对话前就否决过的方案。要是有 token 预算，第 12 分钟就停了。

规则 7——暴露冲突，别和稀泥

当代码库的两个部分意见不一致，Claude 会试图两边都讨好。结果就是怎么都不对。

事故现场：一个代码库有两种错误处理模式——async/await 配合显式 try/catch，和全局 error boundary。Claude 写的新代码两种都上了。错误处理器翻了一倍。我花了 30 分钟才搞懂为什么错误被吞了两次。

规则 8——先读，再写

Karpathy 的「外科手术式修改」让 Claude 别碰旁边的代码，但没让它先理解旁边的代码。少了这条，Claude 写的新代码会和 30 行外的现成代码起冲突。

事故现场：Claude 在一个同名函数旁边加了新函数——它根本没读那个函数。两个函数做同一件事。新函数因为 import 顺序优先被加载了，而老函数是团队用了 6 个月的基准。

规则 9——测试不是可选的，但也不是目的

Karpathy 的「目标驱动执行」在暗示测试就是成功标准。但实践中 Claude 会拿「测试通过」当唯一目标——然后写出浅层测试全过、其他全崩的代码。

事故现场：Claude 给一个 auth 函数写了 12 个测试，全过。生产环境 auth 是坏的。测试测的是「函数返回了东西」，不是「返回了正确的东西」。函数能通过是因为它在返回常量。

规则 10——长时间操作要设检查点

Karpathy 的模板假设一次交互搞定。真实的 Claude Code 是多步骤工作——跨 20 个文件重构、跨 session 建功能、跨多个 commit 调试。没有检查点，一步走错就全白干了。

事故现场：一个 6 步重构到第 4 步出了岔子。等我发现的时候，Claude 已经在错误的状态上继续走了第 5、第 6 步。理清乱局比重做一遍还费时。检查点能在第 4 步就拦住。

规则 11——惯例优于新意

在已经有既定模式的代码库里，Claude 喜欢用自己的写法。就算它的写法「更好」，引入两种模式的代价比任何一种单独用都要差。

事故现场：Claude 在一个 class-component 的代码库引入了 React hooks。能用。但代码库的测试模式全坏了——所有测试都假设 componentDidMount。花了半天全部移除重写。

规则 12——失败要大声，别静悄悄

最坑的 Claude 失败是那些看起来像成功的失败。函数「能跑」但返回错误数据。迁移「完成」但跳了 30 条记录。测试「通过」但断言写错了。

事故现场：Claude 说数据库迁移「已成功完成」。它悄悄跳过了 14% 的记录——这些记录撞了约束冲突，日志里有写但没暴露出来。11 天后报表开始不对劲了才发现。

数据

我拿同一组 50 个代表性任务，在 30 个代码库上跑了 6 周。

配置	错误率
无规则	41%
Karpathy 4 条	11%
12 条（Karpathy + 8）	3%

错误率 = 需要人工干预才能匹配意图的任务。计数包括：沉默假设、过度工程、正交损伤、静默失败、惯例违规、冲突平均化、漏过检查点。

从 4 条扩到 12 条，规则遵循率就降了 2 个百分点（78% → 76%），但错误率又降了 8 个点。新规则堵上的窟窿和原始 4 条不重叠——它们不抢同一块注意力。

Karpathy 模板静默失效的 4 个地方

即使不加新规则，原始模板本身在 4 个地方就不够用了：

1. 长任务跑起来没人管。 Karpathy 的规则瞄准的是 Claude 正在写代码的那一刻。多步骤流水线跑起来怎么办？没有预算规则、没有检查点规则、没有「大声失败」规则。流水线会漂。

2. 多代码库的一致性。 「匹配现有风格」假设只有一个风格。在 12 个服务的 monorepo 里，Claude 得挑一个风格。原始规则没教它怎么挑。它要么随机选，要么取平均。

3. 测试质量。 「目标驱动执行」把「测试通过」当成功。没说测试必须有意义。结果就是测不出什么东西，但 Claude 很自信。

4. 生产代码 vs 原型代码。 保护生产代码不过度工程化的规则，同样会拖慢原型——后者本来就需要大量投石问路的脚手架来摸方向。Karpathy 的「简约优先」在早期代码上用力过猛。

8 条补充规则不是为了取代 Karpathy 的 4 条，而是补上 1 月的 autocomplete 式编码和 5 月的 agent 驱动、多步骤、多代码库工作之间的时差。

试了但没用的事

拍板 12 条之前，我也试过一些别的：

从 Reddit / X 上抄规则。 大部分是 Karpathy 4 条的换说法，或者领域绑定的规则（「永远用 Tailwind」）。不通用。全砍。

超过 12 条。 测试到 18 条，遵循率从 76% 降到 52%。200 行的天花板是真的——过了之后 Claude 开始模式匹配到「有规则存在」，不再真的读它们了。

依赖特定工具的规则。 「永远用 eslint」——eslint 没装呢？规则静默失效。改成能力无关的说法：「匹配代码库强制执行的风格」而不是「用 eslint」。

放例子代替规则。 例子比规则重。3 个例子吃掉的上下文 ≈ 10 条规则，而且 Claude 会过拟合到例子上。规则是抽象的，例子是具体的。用规则。

「小心点」「多想想」「集中注意力」。 纯噪音。遵循率大约 30%，因为没法检验。换成具体的祈使句（「显式说出假设」）。

让 Claude 当「高级工程师」。 没用。Claude 已经觉得自己是高级了。问题不是它想不想，是它做没做。祈使规则弥合这个差距，身份 prompt 不行。

完整 12 条模板（可直接复制）

# CLAUDE.md — Behavioral Rules

## Rule 1 — Think Before Coding
No silent assumptions. State what you're assuming. Surface tradeoffs. Ask before guessing. Push back when a simpler approach exists.

## Rule 2 — Simplicity First
Minimum code that solves the problem. No speculative features. No abstractions for single-use code. If a senior engineer would call it overcomplicated — simplify.

## Rule 3 — Surgical Changes
Touch only what you must. 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 tell me what steps to follow, tell me what success looks like and let it iterate.

## Rule 5 — Don't make the model do non-language work
Decide with code, not tokens. If a decision can be deterministic, write the code for it. Don't route decisions through the model.

## Rule 6 — Hard token budgets, no exceptions
Set a per-task token cap. Stop when you hit it. You will not "just finish this one thing" — you'll spiral.

## Rule 7 — Surface conflicts, don't average them
When the codebase disagrees, pick one. Do not try to satisfy both patterns. That creates incoherence.

## Rule 8 — Read before you write
Read adjacent files before writing new ones. Understand existing patterns. You cannot write compatible code for code you haven't read.

## Rule 9 — Tests are not optional, but they're not the goal
Write meaningful tests. A test that passes for the wrong reason is worse than no test — it creates false confidence.

## Rule 10 — Long-running operations need checkpoints
Checkpoint after each step. Verify intermediate state before proceeding. One wrong turn should not erase all progress.

## Rule 11 — Convention beats novelty
Match the codebase's established patterns. Even if your way is better, two patterns are worse than one.

## Rule 12 — Fail visibly, not silently
If something goes wrong, say so loudly. Surface skipped records, failed assertions, and partial results. Silence hides bugs.

保存到 repo 根目录。用 >> 追加，别覆盖已有内容。总行数卡在 200 行以内。

怎么理解这套东西

CLAUDE.md 不是许愿池。它是一个行为契约，用来堵你确实见过的坑。 每条规则都应该能回答：这条规则防什么错误？

Karpathy 的 4 条防的是他在 1 月见过的失败模式：沉默假设、过度工程、正交损伤、弱成功标准。它们是地基。

我加的 8 条防的是 5 月才浮出来的问题：没预算的 agent 循环、没检查点的多步骤任务、不真测的测试、静默成功藏着静默失败。它们是增量。

你那边可能不一样。不跑多步骤流水线？规则 10 跟你没关系。代码库有 linting 统一风格？规则 11 是多余的。把那 12 条过一遍，留下那些对应你真实踩过的坑的，砍掉那些你永远用不上的。

6 条对准你的真实问题，比 12 条里面有 6 条对你没用的强得多。

翻译完了。原文最值钱的地方在于每条规则背后都有一个具体的翻车故事——不是拍脑袋写的。我个人觉得最实用的两条是规则 6（硬 Token 预算）和规则 10（检查点），前者控制损失，后者保进度，基本上是 Claude Code 中长任务必配的安全带。

至于那个 12 条模板，先全量贴进去跑两周，再砍掉你用不上的，浓缩成你自己的版本。

如果觉得有用，欢迎点赞、在看、转发！你给 Claude Code 写 CLAUDE.md 了吗？有什么踩坑经验？评论区聊聊！

cover_image

Original AI兴观点程叙架构与AI.

内容效果不满意？点此反馈