2026 年 1 月下旬：Andrej Karpathy 在 X 上发帖吐槽 Claude 写代码的方式。总结了三种失败模式 — 隐蔽的错误假设、过度复杂化、以及对本不该触碰的代码造成“正交损伤”。Forrest Chang 读完帖子后，将这些吐槽整理成 4 条行为准则，放在一个 CLAUDE.md 文件中，并发布到了 GitHub。 第一天获得 5,828 个 star。两周内获得 60,000 个书签。到 2026 年中期，star 数达到 120,000 个。 这是年度增长最快的单文件仓库。2026 年 5 月 9 日，一位认证开发者，账号名为 @mnilax (Mnimiy) 在 X 上发布了一篇长文，提出了当年最犀利的工程观点之一：他们在 6 周内针对 30 个代码库测试了该模板，随后又增加了 8 条规则来弥补不足。该文获得了 270 万次浏览和 18,800 个书签。以下是详细拆解 — 以及如果你在 Antigravity（或任何其他 agent IDE）中配合 GEMINI.md or AGENTS.md 文件运行 Claude 时的意义。
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
— @Mnilax 2026 年 5 月 9 日
本文剖析的 @mnilax 原始 X 帖子 — 270万浏览，1.88万收藏，2026 年 5 月 9 日。
1. 爆火时刻
Karpathy's 最初的推文并非指导性的，而是一种吐槽 — 就像资深工程师在经历了一个糟糕的下午后会发的那种。他指出了三种具体的失败模式：
- 隐蔽的错误假设。 Claude 推测你的意图，基于错误的推论进行构建，且从不告知你。
- 过度复杂化。 Claude 倾向于使用抽象、分层和通用辅助函数。原本 4 行代码就能搞定的修复变成了 40 行。
- 正交损伤。 Claude "改进"了它本不该触碰的代码 — 包括空格、命名、格式，以及未被要求的相邻函数。
Forrest Chang 读了这篇推文，并完成了别人没做的工作：他写下了 Karpathy 隐含的要求。四条简短的指令式规则。一个文件。65 行。公开仓库。节奏感很重要 — Forrest 没有添加评论，没有将其变成框架，也没有变现。只有规则。
这触动了人们的神经。每天都在与 Claude 较劲的开发者们突然有了一个一行式安装方案：将此文件粘贴到仓库根目录。数据说明了一切 — 一个没有任何代码的文件获得了 120,000 个 star。直到今天，大多数开发者仍然只运行这四条规则。
2. 原始的 4 条规则（Karpathy 提出，Forrest Chang 整理）
这是基础 — 规则的原始版本。如果你现在还没有 CLAUDE.md，请从这些开始：
规则 1 — 编码前先思考。 不要进行无声的假设。陈述你的假设。明确权衡利弊。在猜测之前先询问。如果存在更简单的方法，请提出异议。
规则 2 — 简单至上。 用最少的代码解决问题。不要添加投机性的功能。不要为单次使用的代码进行抽象。如果资深工程师认为它过于复杂，请简化。
规则 3 — 精确修改。 只触碰必须修改的部分。不要"改进"相邻的代码、注释或格式。不要重构没有损坏的部分。保持与现有风格一致。
规则 4 — 目标驱动执行。 Define success criteria. Loop until verified. Don't tell Claude what steps to follow; tell it what success looks like and let it iterate.
Mnimiy's 的数据：这四条规则解决了 无人值守的 Claude Code 会话中约 40% 的失败模式。剩下的约 60% 存在于原始模板未涵盖的空白中。
3. 为什么需要扩展
该模板编写于 2026 年 1 月。2026 年 5 月的 Claude Code 生态系统已截然不同。文章指出了原有的 4 条规则未涵盖的 1 月之后的四个现实情况：
- Agent 冲突。 在多 Agent 设置中，两个 Agent 编辑同一个文件并互相干扰。Karpathy's 的规则假设的是单个自动补全循环。真实的 多 Agent 编排 需要所有权规则。
- Hook 级联。 Claude Code 的 hook 在每次工具调用时都会触发。如果没有预算限制，一个啰嗦的 hook 会将 200 token 的请求变成 8,000 token。
- 技能加载冲突。 多个 技能 描述重叠的技能会使基于描述匹配的分发器产生混淆。原始模板中没有关于如何消除歧义的内容。
- 多步工作流。 一个包含 6 个步骤的重构如果在第 4 步出错，意味着第 5 步和第 6 步将建立在错误的状态之上。原始模板将 Claude 的每一次轮次都视为 one-shot。
Mnimiy's 的论点： 最初的 4 条是基础性的，并没有错，但它们是不完整的。
4. 8 条新规则（每条都附带其产生的契机）
每一条规则都源于对 30 个代码库研究中的特定事件。文章先展示契机，再引出规则。以下是相同的结构，但经过了精简。
规则 5 — 不要让模型执行非语言类工作
确定性的决策应当由确定性的代码来完成。重试策略、路由、升级阈值等 — 而非通过 LLM 调用。模型的决策每周都在变化。
契机： 一个 "decide whether to retry on 503" 的 LLM 调用正常运行了两周，随后开始出现故障，因为模型开始将请求体作为决策上下文。由于 prompt 实际上变得随机，重试策略也随之变得随机。
规则 6 — 严格的 token 预算，绝无例外
每一个循环都有可能演变成 50,000-token 的上下文堆积。模型不会自动停止。预算为你提供了一个硬性的底线。
契机： 一个长达 90 分钟的调试过程，一直在处理同一个 8KB 的错误消息。到最后，Claude 建议的修复方案竟然是用户在 40 条消息前就已经拒绝过的。如果设置了 token 预算，这个循环在第 12 分钟就会被终止。
规则 7 — 暴露冲突，而非折中处理
当代码库的两个部分存在冲突时，Claude 会试图同时满足两者。结果就是产生不连贯的代码，它结合了两种模式，但在任何一种模式下都无法正常工作。
契机： 一个代码库有两种错误处理模式 — 使用 try/catch 的 async/await 和全局错误边界。Claude 写的代码同时用了这两种。错误被吞掉了两次。花了 30 分钟才查出来。
规则 8 — 先读后写
Karpathy 的 "Surgical Changes" 告诉 Claude 不要触碰相邻的代码。但它没告诉 Claude 要理解相邻的代码。如果不加上这一点，Claude 写的代码可能会与 30 行之外的现有代码发生冲突。
那个瞬间： Claude added a function next to an existing identical function it hadn't read. The new one won by import order. The original had been the source of truth for 6 months.
规则 9 — 测试不是可选的，但也不是终极目标
目标驱动执行（Goal-Driven Execution）将“测试通过”视为成功。但在实践中，Claude 写的代码可能通过了浅层测试，却破坏了生产环境的行为。
那个瞬间： 一个身份验证函数有 12 个测试，全部通过，但生产环境中的身份验证却挂了。测试只检查了函数是否返回了 某些内容，而不是它是否返回了正确的内容。函数通过测试是因为它返回了一个常量。
规则 10 — 长时间运行的操作需要检查点
原始模板假设的是单次交互。实际的 Claude Code 工作是多步骤的 — 跨越 20 个文件的重构、一个会话中的功能开发、跨提交的调试。如果没有检查点，一步走错就会前功尽弃。
那个瞬间： 一个包含 6 个步骤的重构在第 4 步出了问题。Claude 在错误的状态下继续执行了第 5 步和第 6 步。理清这些混乱所花的时间比重新做一遍重构还要长。
规则 11 — 惯例优于创新
在一个已有既定模式的代码库中，Claude 喜欢引入自己的模式。即使它的方式“更好”，引入第二种模式也比只使用其中任何一种模式更糟糕。
那个瞬间： Claude 在一个类组件（class-component）代码库中引入了 React hooks。Hooks 运行正常，但它们破坏了代码库的测试模式，因为这些模式假设了 componentDidMount。花了半天时间才移除并重写。
规则 12 — 显式失败，而非静默失败
最代价高昂的 Claude 失败往往伪装成成功。一个函数 "运行正常" 但返回了错误数据；一次迁移 "已完成" 但跳过了 30 条记录；一个测试 "通过" 但断言逻辑是错误的。
典型案例： Claude 报告数据库迁移 "成功完成"。但它静默地跳过了 14% 违反约束条件的记录。跳过操作被记录在日志中但未被显现。直到 11 天后报表数据出现异常才被发现。
5. 数据统计
Mnimiy 在 6 周内追踪了 30 个代码库中的 50 个代表性任务，并对比了三种配置：无 CLAUDE.md、原始 4 条规则、完整 12 条规则。错误率是指需要修正或重写以符合意图的任务占比 — 统计涵盖了七种不同的失败类型（静默错误假设、过度工程、正交破坏、静默失败、违反约定、冲突平均化、遗漏检查点）。
无 CLAUDE.md： 错误率 ~41%，无基准合规性
4 条规则： 错误率 ~11%，合规率 78%
12 条规则： 错误率 ~3%， 合规率 76%
核心指标的下降（41% → 3%）是显而易见的结果。而 有趣的 结果是，从 4 条规则增加到 12 条 几乎没有增加合规开销 (78% → 76%)，同时将错误率又降低了 8 个百分点。新规则涵盖了原始 4 条规则未涉及的失败模式 — 它们不会争夺相同的注意力预算。
这是超越 4 条规则的实证案例。如果增加规则会成比例地牺牲合规性，你可能会止步于 4 条。但事实并非如此。
6. 原始模板在何处静默失效
Karpathy's 4 条规则不足以应对的四个场景 — 甚至在添加新规则之前。文章明确指出，原版规则并没有错，它针对的是 January 2026's 的问题空间：
- 长期运行的 Agent 任务。 这些规则针对的是 Claude 编写代码的时刻。它们对多步流水线保持沉默。没有 budget 规则。没有 checkpoint 规则。没有 fail-loud 规则。流水线会发生偏移。
- 多代码库一致性。 "Match existing style" 假设只有一种风格。在一个拥有 12 个服务的 monorepo 中，Claude 必须选择哪种风格。原始规则没有告诉它如何选择。它会随机选择或取平均值。
- 测试质量。 Goal-Driven Execution 将 "tests pass" 视为成功。它没有规定测试必须有意义。结果就是测试了一些毫无用处的东西，却让 Claude 信心满满。
- 生产环境 vs 原型。 保护生产代码免受 over-engineering 困扰的这 4 条规则，同样也会拖慢原型的进度，而原型确实需要 100 行推测性的 scaffolding 代码来确定方向。"Simplicity First" 在早期代码阶段会 overfires。
7. 哪些行不通（失败的实验）
这可能是文章中最有用的部分 — 不是那些最终入选的规则，而是那些明确被排除的模式：
- 从社交媒体收集的规则。 大多数规则要么是用不同措辞对 Karpathy's 4 的重述，要么是无法推广的特定领域规则（"always use Tailwind classes"）。删掉。
- 超过 14 条规则。 Mnimiy 测试了多达 18 条。超过 14 条后，合规率从 76% 下降到 52%。Anthropic 文档中提到的 200 行上限是真实存在的 — 超过这个限制，Claude 只会进行 pattern-matches 以确认 "rules exist"，而不会真正阅读它们。
- 依赖工具的规则。 当没有安装 eslint 时，"Always use eslint" 会静默失败。取而代之的是与能力无关的表述："match the codebase's enforced style"。
- 用示例代替规则。 三个示例消耗的上下文与约 10 条规则相当，而且 Claude 会对它们产生 over-fits。规则是抽象的，示例是具体的。请使用规则。
- 模糊的修饰词。 "小心点"、"努力思考"、"保持专注"。执行率仅约 30%，因为这些指令都无法量化测试。应替换为具体的祈使句，例如"明确陈述假设"。
- 身份提示词。 告诉 Claude 要表现得像个"资深工程师"并没用。Claude 已经自认为很资深了。执行力的差距在于"认知"与"行动"之间。祈使句能弥补这一差距，而身份提示词做不到。
8. 心智模型
剥离文章的冗余，只保留最核心的一句话，就是：
CLAUDE.md 不是愿望清单。它是一份行为契约，旨在消除你观察到的特定失败模式。
每条规则都应该回答： 这能防止什么错误？
这改变了看待问题的方式。大多数开发者将 CLAUDE.md 视为个人偏好文件 — 一个随时间不断增加的风格喜好列表。文章认为，偏好文件的形式是错误的。正确的形式应该是你实际遇到的失败模式列表，针对每种模式制定一条规则。
这也解释了为什么文章以一个违反直觉的建议结尾：
一个针对真实失败模式调优的 6 条规则的 CLAUDE.md，优于一个包含 6 条冗余规则的 12 条规则的文件。
不要因为 X 上有人推荐就盲目粘贴全部 12 条。阅读它们，保留那些能解决你实际犯过错误的规则，其余的全部删掉。
9. 将其映射到 Antigravity (GEMINI.md / AGENTS.md)
虽然文章侧重于 Claude，但这种抽象逻辑是通用的。Antigravity 会从两个相同形式的文件中读取流程规则：
- GEMINI.md — Gemini 特有的系统提示词文件。查看我们的 GEMINI.md 指南。
- AGENTS.md — 跨工具格式（适用于 Claude Code, Cursor, Antigravity）。查看我们的 AGENTS.md 指南.
两者都是建议性而非强制性的，上限都在 200 行左右，超过后遵循度会下降，且都遵循相同的 "陈述规则、不举例、不使用模糊修饰语" 准则。这 12 条规则基本上可以无缝迁移。针对 Antigravity 的特定考量：
- 规则 6（token 预算）变得至关重要，不再是可选项。 Antigravity 的配额消耗比 Claude Code 更快。请将此规则与我们的 token 削减指南.
- 规则 10（检查点）对应 Antigravity's Agent Manager。 如果多智能体运行在第 4 步出错，你会希望能够终止该智能体并从之前的 artifact 恢复，而不是从头开始。
- 规则 7（暴露冲突）有助于模型切换。 如果你在会话中途在 Gemini 和 Claude Opus 之间切换（正如我们的 模型切换分析）中所述，新模型通常会继承旧模型的陈旧上下文，并尝试调和不兼容的模式。
- 规则 12（显式失败）是 Autopilot 中最被低估的一项。 如果你运行 auto-accept，静默失败会在你察觉之前，在多次 Cmd-Enter 循环中不断累积。强制智能体显式展示每一个跳过的步骤。
同样的模板，不同的运行时，同样的逻辑。
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
10. 完整的 12 条规则模板（可直接复制使用）
将此保存为 CLAUDE.md (或 GEMINI.md 或 AGENTS.md) 位于你的仓库根目录。原文章指出：请将总文件大小保持在 200 行以内（包括下方任何项目特定的补充内容），超过这个限制后，遵循度会大幅下降。
这就是那个文件。你需要对它做两件事：
- 诚实地阅读这 12 条规则。 哪些规则对应你本月实际犯过的错误？保留这些，删掉其余的。一个针对你的错误模式定制的 6 条规则文件，效果远好于一个包含你永远不会触发的规则的 12 条规则文件。
- 在下方追加项目特定的规则。 Stack-specific ("always use the Repository pattern"), test-runner ("run pnpm test:unit before reporting done"), error patterns. Keep the total under 200 lines.
11. FAQ
什么是 CLAUDE.md 12 条规则模板？
它是对 Forrest Chang 基于 Andrej Karpathy 在 2026 年 1 月关于 Claude 失败模式的推文所构建的 4 条 CLAUDE.md 规则文件的扩展。Mnimiy (@mnilax) 在 30 个代码库中对原版进行了为期 6 周的测试，并于 2026 年 5 月发布了额外的 8 条规则，以涵盖原版编写后出现的问题——智能体冲突 (agent fights)、钩子级联 (hook cascades)、技能加载冲突以及多步工作流漂移。
谁是 Karpathy？又是谁封装了原始的 4 条规则？
Andrej Karpathy 是著名的 AI 研究员（曾任职于 Tesla 和 OpenAI）。他在 2026 年 1 月底发布了一系列推文，列举了他在 Claude 代码生成中经常看到的三个失败模式：隐性错误假设、过度复杂化和正交破坏。Forrest Chang 阅读了这些推文，将这些抱怨整理成一个 CLAUDE.md 文件中的 4 条行为准则，并将其发布在 GitHub 上。该仓库在第一天就获得了 5,828 颗星，到 2026 年中期已达到 120,000 颗星 —— 成为当年增长最快的单文件仓库。
这些规则究竟能在多大程度上减少错误？
Mnimiy 对 30 个代码库和 50 个代表性任务进行了测量：在没有 CLAUDE.md 的情况下，错误率约为 41%。使用原始的 4 条规则后，错误率降至约 11%。而使用完整的 12 条规则后，错误率仅为约 3%。遵循率（Compliance）—— 即 Claude 显式应用相关规则的频率 —— 在 4 条和 12 条规则之间基本保持持平（78% → 76%），这表明新规则涵盖了原始 4 条规则未解决的失败模式，而不是在争夺同样的注意力预算。
这是否适用于 Antigravity？毕竟 Antigravity 使用的是 Gemini 而不是 Claude。
是的。Antigravity 以同样的形式从 AGENTS.md 和 GEMINI.md 文件中读取程序规则：位于仓库根目录的 Markdown 文件，是建议性的而非强制性的，在遵循率下降前上限约为 200 行。这 12 条规则几乎可以逐字迁移。我们在下方链接的 Antigravity AGENTS.md 和 GEMINI.md 指南中介绍了实际的映射方法。
为什么是 12 条规则，而不是更多？
Mnimiy 测试了多达 18 条规则。超过 14 条后，遵循率从 76% 骤降至 52%。Anthropic 文档中提到的 200 行上限是真实存在的：超过这个限制，Claude 就会开始对“规则存在”进行模式匹配，而不再实际阅读它们。该模板的约束力在于保持足够精简，确保每条规则在每次会话中都能被读取。
我应该使用全部 12 条规则，还是只选择其中一部分？
挑选使用。文章明确指出：“一个针对你实际失败模式调整的 6 规则 CLAUDE.md，优于一个包含 6 条你永远不需要的规则的 12 规则版本。”阅读这 12 条规则，保留那些对应你实际犯过错误的规则，删掉其余的。如果你不运行多步流水线，规则 10（checkpoints
Where does the original Karpathy template silently break?
Mnimiy identifies four gaps: (1) long-running agent tasks — no budget, no checkpoint, no fail-loud rules; (2) multi-codebase consistency — 'match existing style' assumes one style, fails in monorepos with multiple services; (3) test quality — 'tests pass' as the only goal means Claude writes tests that test nothing; (4) production vs prototype — 'Simplicity First' overfires on early-stage code that legitimately needs speculative scaffolding.
What approaches did Mnimiy try that didn't work?
Five things failed: (1) collecting rules from social media — mostly restatements or non-generalizable; (2) more than 14 rules — compliance crash; (3) tooling-dependent rules like 'always use eslint' — fails silently when tool is missing; (4) examples instead of rules — heavier, model over-fits; (5) vague rules like 'be careful' or 'think hard' — compliance ~30% because they're not testable; (6) identity prompts like 'act like a senior engineer' — Claude already thinks it's senior. Imperative rules close the gap; identity prompts don't.