别只靠4条老规则，加8条新的才能搞定今天的问题
今年1月，大神Andrej Karpathy发帖抱怨Claude写代码的三个毛病：自己瞎猜导致逻辑错、把简单事情搞复杂、改A代码时把B代码弄坏。有个叫Forrest Chang的人看了帖子，把抱怨翻译成4条规则，放到一个CLAUDE.md文件里扔到GitHub上。结果第一天就拿了5828个星星，两周内6万个书签，现在已经12万星星，成了2026年增长最快的单文件仓库。
我把这4条规则在30个代码库上测了6周。它们确实管用，那些以前犯错率40%的任务，在合适的场景下能降到3%以下。但问题是，这套模板是为了修1月份的问题写的。现在都5月份了，Claude Code的生态出了新毛病：AI代理自己跟自己打架、钩子（hook）连环触发、技能加载冲突、多步骤任务在不同会话之间断开。所以我加了8条规则。下面就是完整的12条规则，外加Karpathy原模板在哪些地方悄悄失效。
为什么要认真对待CLAUDE.md这个文件
CLAUDE.md是整个AI编程工具箱里最被低估的文件。大多数开发者要么把它当垃圾桶，塞进所有偏好，搞到4000多个令牌（token，AI处理文本的计数单位），然后Claude听话率掉到30%。要么直接跳过，每次对话都重新敲指令，浪费5倍令牌量，还做不到会话间一致。官方的说明书也明说了：CLAUDE.md只是个建议，Claude大概有80%的时间会听。一旦超过200行，听话率就直线下降，因为重要规则被淹没了。
Karpathy的模板用一个文件、65行、4条规则就解决了这个问题。这是底线，但不是天花板。加上下面8条规则，你不仅能覆盖1月份那些代码写作问题，还能解决5月份才出现的AI代理协调问题。
原版4条规则在做什么
如果你没看过那个爆火仓库，我先说一下这4条规则是啥：
1、 思考后动手，别猜
不允许默默假设。你要说出你在假设什么，把权衡选择摆上台面，不确定就问，有更简单的路径就退回。别自己瞎编。
2、 简单优先
写最少代码解决问题。不要写将来可能用到的功能，不要给只用一次的东西搞抽象。如果资深工程师看了会说“这搞复杂了”，那就简化。
3、 精准修改，别碰不该碰的
只改你非改不可的地方。别“顺手”改旁边的代码、注释或者格式。别重构没坏的东西。照着现有的风格写。
4、 目标驱动，别给步骤清单
定义什么算成功，然后反复迭代直到达成。别告诉Claude该先做哪步后做哪步，只告诉它成功长什么样，让它自己转圈直到对上。
这4条堵住了我看到的那些无监督Claude会话里大约40%的失败。剩下的60%藏在下面的空隙里。
我加的8条规则以及为什么加
每一条都是来自真实场景：Karpathy的4条不够用了。我会说清楚当时发生了什么，然后给出规则。
规则五：别让AI做非语言类的工作
Karpathy的规则没提这事。AI会自己决定哪些该由确定性的代码来做，比如要不要重试API请求、消息怎么路由、什么时候升级处理。每周决策都不一样。用AI写一个if-else判断，每次花0.003美元，结果还不稳定。
别让AI做路由、重试、状态码处理、确定性转换这些事。AI只用来做分类、起草、总结、从非结构文本里提取信息。如果一个状态码本身就能回答的问题，让普通代码来回答。
这条规则来自一个真实事故：有一段代码调用AI去“决定503错误要不要重试”，前两周跑得好好的，后来AI开始把请求正文也当作决策背景，重试策略就完全随机了，因为输入的提示词本身是随机的。
规则六：令牌预算硬性卡死，没例外
没有预算限制的CLAUDE.md等于给AI开了张空白支票。每个循环都可能螺旋膨胀到5万令牌的上下文。AI不会自己喊停。
每个任务预算4000令牌，每个会话预算30000令牌。如果快超了，就总结一下然后重新开始会话，别硬撑。报告超限比默默超限要好。
事故场景：一次调试跑了90分钟。AI很happy地在那反复折腾同一个8KB的错误信息，慢慢忘掉哪些修复方案已经试过了。到最后，它开始推荐我在40条消息前就已经拒绝的方案。如果有令牌预算，12分钟就给它掐掉了。
规则七：暴露冲突，别搞平均
当代码库的两个部分互相矛盾时，AI会试图两边都讨好，结果就是代码变浆糊。
如果现有代码里存在两种矛盾的模式，不要混合它们。选一个出来（选更新的或者测试更充分的），解释为什么选它，然后把另一个标记为待清理。那种两边规则都满足的“平均”代码是最糟糕的。
事故：有个代码库同时存在两种错误处理模式，一种是async/await加显式try/catch，另一种是全局错误边界。AI写新代码把两个都用上了，双重错误处理器。我花了半小时才搞清楚为什么错误被吞了两次。
规则八：先读代码再写代码
Karpathy的“精准修改”规则告诉AI不要碰旁边的代码，但没告诉AI要先理解旁边的代码。没有这条，AI写的新代码会和30行以外的代码打架。
在添加代码之前，先读这个文件导出了什么、调用方是谁、任何明显共享的工具函数。如果你不理解现有代码为什么是现在这个结构，先问清楚再往上加。“看起来跟我不相干”是代码库里最危险的一句话。
事故：AI在已有函数旁边加了一个一模一样的函数，因为它没先读一遍。两个函数干同一件事，新函数因为导入顺序排在前面，覆盖了老的。老的那个可是6个月的真理之源。
规则九：测试验证意图，不只验证行为
Karpathy的目标驱动执行隐含地把测试当作成功标准。但在实际操作中，AI会把“测试通过”当成唯一目标，然后写出能通过浅层测试但弄坏其他一切的代码。
每个测试都必须编码“为什么这个行为重要”，而不只是“它做了什么”。一个只检查getUserName返回值等于John的测试毫无意义，如果那个函数其实是写死了一个ID的话。如果你写不出一个会在业务逻辑改变时失败的测试，那这个函数本身就有问题。
事故：AI为一个身份验证函数写了12个测试，全过了。结果生产环境里身份验证是坏的。那些测试只是在测函数返回了什么东西，而不是返回的东西对不对。函数返回的是常量，当然过了。
规则十：长任务要有检查点
Karpathy的模板假设每次交互都是一锤子买卖。真正的Claude Code工作是多步骤的，比如跨20个文件重构、一个会话里搭整个功能、跨多个提交调试。如果没有检查点，走错一步就全丢了。
完成多步骤任务里的每一步之后，总结一下：做了什么、验证了什么、还剩下什么。不要从一个你自己都描述不清楚的状态继续往前走。如果你搞丢了进度，停下来重新说明。
事故：一个6步重构在第4步出了错。等我发现的时候，AI已经基于那个错误状态继续做完了第5步和第6步。拆解重来比全部重做还费时间。要是有检查点，第4步就抓住了。
规则十一：惯例优先于新颖
在一个已经有既定模式的代码库里，AI喜欢引入自己的写法。就算它的写法“更好”，两种模式并存也比任何一种单独存在更糟糕。
如果代码库用蛇形命名法，就算你更喜欢驼峰命名法，也给我用蛇形。如果代码库用类组件而你喜欢函数组件，就用类组件。有不同意见是另一场对话。在代码库内部，遵守规矩比品味更重要。如果你真的觉得某个规范有害，把它提出来，别偷偷分叉。
事故：AI在一个类组件代码库里引入了React函数组件。它们能跑，但也破坏了代码库的测试模式，因为测试假定的是componentDidMount生命周期。花了半天时间删掉重写。
规则十二：失败要响亮，别静悄悄
最昂贵的AI失败是那些看起来像成功的失败。一个函数能跑但返回错误数据。一个迁移做完但跳过了30条记录。一个测试通过只是因为断言写错了。
如果你不能确定某件事成功了，就明确说出来。“迁移完成”这个说法，如果悄悄跳过了30条记录，那就是错的。“测试通过”如果跳过了任何测试，那就是错的。“功能正常”如果没有验证我问过的边界情况，那就是错的。默认做法是暴露不确定性，而不是隐藏它。
事故：AI说数据库迁移“成功完成”。它悄悄跳过了14%的记录，因为这些记录触发了约束冲突。跳过这件事被记在日志里，但没有暴露出来。11天后报表开始出错才发现问题。
数字说话：从41%到3%
我在30个代码库上追踪了50个代表性任务，持续6周。对比了三组配置：没有规则、只用Karpathy的4条、用全部12条。
错误率定义为：任务需要人工纠正或重写才能符合意图。错误类型包括：默默错误的假设、过度工程、殃及池鱼的改动、静默失败、违反惯例、平均化冲突、丢失检查点。
4条规则把错误率从41%打到11%。再加8条，从11%打到3%。有趣的是，从4条变成12条，听话率几乎没有下降，从78%到76%。新规则覆盖了原4条没处理的失败模式，它们不竞争同一个注意力预算。
Karpathy模板在哪几个地方悄悄失效
四个场景下，原4条规则不够用，就算不加新规则也一样出问题。
长时AI代理任务。Karpathy的规则针对的是AI写代码的那一瞬间，完全没提AI跑多步骤流水线时该怎么办。没有预算规则，没有检查点规则，没有失败要响亮规则。流水线会自己飘走。
多代码库一致性。“匹配现有风格”假定只有一种风格。在一个有12个服务的单体仓库里，AI得挑哪个风格。原规则没告诉它怎么挑，结果就是随机选或者搞平均。
测试质量。目标驱动执行把“测试通过”当作成功，没说测试要有意义。结果就是测了一堆没用的东西，但AI自己觉得很自信。
生产代码与原型代码。同一套保护生产代码不过度工程的规则，在早起的原型阶段也会乱开枪，因为原型可能合法需要写100行探索性代码去找方向。Karpathy的“简单优先”对早期代码有点过火了。
我加的8条规则不是替换Karpathy的4条，而是打补丁。他1月份那套是针对自动补全式编程的，而5月份的工作已经是代理驱动、多步骤、多代码库的了。
哪些尝试失败了
在敲定12条规则之前，我试过别的东西，都没成。
加我从Reddit或X上看到的规则。大部分要么是Karpathy那4条的换种说法，要么是领域专用的规则（比如“永远用Tailwind CSS类”），不通用。全砍了。
超过12条规则。我试过最多18条，听话率从76%掉到52%。超过200行的天花板是真实存在的。超过之后，AI开始模式匹配“有规则存在”而不真正读它们。
依赖不一定存在的工具的规则。“永远用eslint”在eslint没装的时候就会崩，规则静默失效。我改成了不依赖具体能力的说法，比如“匹配代码库强制执行的风格”而不是“用eslint”。
在CLAUDE.md里放例子而不是规则。例子比规则重。三个例子消耗的上下文相当于10条规则，而且AI会过拟合到例子上。规则是抽象的，例子是具体的。用规则。
“小心点”“使劲想”“真专注”。纯噪音。因为这些没法测试，听话率掉到30%左右。换成具体指令比如“明确说出假设”。
告诉AI要做“资深工程师”。没用。AI已经觉得自己是资深了。差距在于“觉得”和“做到”之间。指令性规则能弥合这个差距，身份提示不行。
完整12条规则模板直接复制用
把下面这个保存成CLAUDE.md放在你的仓库根目录。项目专属规则可以加在12条下面（比如技术栈、测试命令、错误模式），但总计别超过200行，超了听话率就跌。
CLAUDE.md — 12条规则模板
本规则适用于本项目的每一个任务，除非明确覆盖。原则：在非琐碎工作上谨慎优先于速度，在明显琐碎的任务上自己判断。
规则一 思考后动手
明确说出假设。如果不确定，先问而不是猜。遇到模糊情况给出多种解释。发现有更简单的路径就退回。困惑时停下，说出哪里不清楚。
规则二 简单优先
写最少代码解决问题，不要写以后可能用得上的功能，不要给只用一次的东西搞抽象。检验标准：资深工程师会说这搞复杂了吗？如果是，就简化。
规则三 精准修改
只动你必须动的地方。只清理你自己造成的混乱。不要“顺手”改进旁边的代码、注释或格式。别重构没坏的东西。照着现有风格写。
规则四 目标驱动执行
定义成功标准，反复迭代直到验证。不要告诉AI该走哪几步，告诉它成功长什么样，让它自己迭代。强大的成功标准能让AI独立转圈。
规则五 只让AI做判断性工作
用AI做分类、起草、总结、从非结构化文本提取信息。不让AI做路由、重试、确定性转换。如果纯代码能回答，就让纯代码回答。
规则六 令牌预算不是建议
每个任务预算4000令牌，每个会话预算30000令牌。快超了就总结并重新开始会话，别硬扛。报告超限比默默超限要好。
规则七 暴露冲突别平均化
如果两种模式矛盾，选一个出来（选更新的或测试更充分的）。解释为什么选它，把另一个标记为待清理。不要混合矛盾的模式。
规则八 先读代码再写代码
加代码之前，先读当前文件的导出、直接调用方、任何共享的工具函数。“看起来跟我不相干”很危险。如果不确定为什么代码是现在这个结构，先问清楚。
规则九 测试验证意图不只验证行为
每个测试必须编码为什么这个行为重要，而不只是做了什么。一个会在业务逻辑改变时不会失败的测试就是错的。
规则十 每个重要步骤后做检查点
总结做了什么、验证了什么、还剩下什么。不要从一个你描述不清楚的状态继续往前走。如果搞丢了进度，停下来重新说明。
规则十一 匹配代码库惯例即使你不同意
在代码库内部，遵守规矩比品味重要。如果你真的觉得某个规范有害，提出来，别偷偷分叉。
规则十二 失败要响亮
“完成”这个词，如果任何东西被悄悄跳过了，就是错的。“测试通过”如果有任何测试被跳过了，就是错的。默认做法是暴露不确定性。
怎么安装到你的项目
两步走。第一步，把Karpathy那4条规则基线追加到你的CLAUDE.md。第二步，把本文的规则5到12粘贴到下面。那个加号很重要，它是追加而不是覆盖，这样不会弄丢你已有的项目专属规则。
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
把规则5到12粘贴到下面，保存到仓库根目录。
心理模型：CLAUDE.md不是许愿清单
CLAUDE.md不是许愿清单，而是一份行为合同。每一条规则都应该回答一个问题：这条规则防止什么错误？
Karpathy的4条防止的是他1月份看到的那几类错误：默默假设、过度工程、殃及池鱼、弱成功标准。它们是地基，不要跳过。
我加的8条防止的是5月份新冒出来的错误：无预算的代理循环、无检查点的多步骤任务、不测试的测试、隐藏不确定性的静默成功。它们是叠加层。
你的情况会不一样。如果你不跑多步骤流水线，规则10对你没用。如果你的代码库风格统一且由lint工具强制，规则11就是多余的。读这12条，只保留那些对应你真实犯过的错误的规则。一个有6条且精准命中你真错误模式的CLAUDE.md，好过一个有12条但其中6条你永远用不上的。
Karpathy今年1月的帖子是一通抱怨。Forrest Chang把它变成了4条规则。12万开发者给那个仓库点了星。他们中的大多数人今天仍然在跑那4条规则。模型进步了，生态变了，多步骤代理、钩子瀑布、技能加载、多代码库工作，这些东西在Karpathy写帖子的时候还不存在。那4条规则没错，但不完整。加8条，6周测试跨30个代码库，错误率从41%降到3%。今晚就把这12条规则贴进你的CLAUDE.md里。