文章总结： 本文基于30个代码库6周测试数据，提出12条改进ClaudeCode准确性的工程规则，将错误率从41%降至3%。核心规则包括明确假设、保持简洁、精准修改、定义成功标准、合理使用模型判断、设置Token硬约束、解决模式冲突、先读后写、验证测试意图、设置检查点、遵循代码库规范、显式报错。文档提供可直接复用的CLAUDE.md模板，强调规则应对具体错误场景而非泛泛偏好。 综合评分： 85 文章分类： 安全开发,技术标准,解决方案,安全工具,AI安全
我用这12条规则，把Claude Code的出错率从41%压到了3%
原创
i3eg1nner&林00 i3eg1nner&林00
SecureNexusLab
2026年5月11日 09:15 北京
在小说阅读器读本章
去阅读
❝
以下内容来自博主 Mnimiy 的实践分享，原文基于对30个代码库、6周测试的真实数据。
❞
今年一月，Andrej Karpathy发了一篇帖子，指出Claude在代码任务上的三类系统性失败，静默假设、过度设计引入不必要的抽象层、以及对不相关代码的误伤。然后有个叫Forrest Chang的开发者看到了这个帖子，把这些问题整理成4条可执行的行为约束，放进一个叫CLAUDE.md的配置文件，丢到了GitHub上。
第一天，5828颗星，两周，6万个收藏，现在，12万颗星，已经成为2026年增长最快的单文件仓库。
一位X上的博主Mnimiy当时也star了，然后没有立刻用起来。直到在30个代码库上系统测试了6周，才发现，这4条规则确实有效，但覆盖的失败模式远不完整，因此他在实践中新增了八条规则。
在看完这份CLAUDE.md后，我发现CLAUDE.md不应该是偏好清单，而应当是一份针对已知失败模式的行为约束合约。
衡量一条规则是否该加进去只有一个标准，它能防止哪个具体的、已经发生过的错误？如果你说不清楚，那条规则可能就不值得占用上下文空间。
Karpathy的4条，防住了2026年1月单次代码生成场景下的核心失败，静默假设、过度抽象、误伤邻近代码、成功标准不可验证。那是基础，不要跳过。
Mnimiy加的8条，防住了2026年5月Agent驱动、多步骤、多代码库场景下出现的新失败，无预算的循环、无检查点的状态积累、覆盖率虚高的测试、以及观测层和执行层之间的不一致。是补丁，不是替代。
你的情况可能不一样，精简到你真实需要的规则数量，一个6条但每条都对应实际踩过的坑的CLAUDE.md，比一个12条但有6条永远不会触发的，效果要好。
先说结论，我把原来的4条规则扩展到了12条，错误率从41%掉到了3%。但在我讲后面8条之前，我想先说一件让我有点意外的事。
这个CLAUDE.md，是Claude Code里最被低估的工程配置。
大多数开发者对它的处理方式只有三种，往里面堆所有偏好直到超过4000 token、完全不用靠每次手动prompt补偿、或者复制一份模板之后再也不碰它。
Anthropic的文档说得很清楚，CLAUDE.md是advisory的，Claude大概80%的时间会遵守。超过200行之后，关键规则会被上下文噪音稀释，合规率明显下降。
Karpathy那个模板的设计取舍就在这，65行，4条规则，精准覆盖他观察到的核心失败模式，而不是把所有想法都写进去。
那4条规则是这样的，先说一遍：
1，写代码前先想清楚，明确说出假设，有疑问就问，不要猜。
2，能简单就简单，不要写没人要的功能，不要为了一次性的代码做抽象。
3，只动该动的地方，不要顺手”优化”旁边那些没问题的代码。
4，定义成功标准，循环迭代直到验证，别跟我说步骤，告诉我什么叫成功。
这4条，管住了大概40%的错误。
剩下60%呢？就是我后来加的那8条要解决的问题。
我加的第一条，是关于一个容易被忽视的架构边界问题。
有一次，代码里有一段逻辑，调用Claude来「决定遇到503错误要不要重试」。
听起来合理，让模型来做判断。
它工作了整整两周，然后开始表现不稳定。排查之后发现，Claude在处理请求时开始把request body的内容纳入决策上下文，导致重试逻辑随着每次请求的body变化而漂移。
重试策略变成了概率性的，因为决策prompt是非确定性的。
这就是第5条规则要解决的问题，把确定性逻辑交给了概率性系统。
「规则5，只把判断类的事交给模型。」
分类、起草、总结、从非结构化文本里提取信息，这些交给Claude。路由、重试、状态码处理、确定性的转换，这些不要交给Claude。如果一个状态码已经能回答问题，就用代码回答，不需要再绕一圈。
接下来这条，是最容易在工程上被忽略的资源控制问题。
没有Token预算的CLAUDE.md，是一张无上限的授权书。
有一次调试会话跑了90分钟。Claude在同一份8KB的错误日志里反复迭代，上下文窗口逐渐被历史对话填满，新的推理开始受到早期错误尝试的干扰，到最后开始重新提出40条消息之前已经被明确否掉的修复方案。
这是context window污染的典型症状，不是模型变蠢了，是上下文质量在持续劣化。
要是一开始设了硬性预算，这个会话在第12分钟就应该被截断，然后带着干净的上下文重开。
「规则6，Token预算不是建议，是硬性约束。」
每个任务4000个Token，每个会话30000个Token。接近上限时，总结内容，开一个新会话继续。主动报告，不要悄悄超支。
第7条，我叫它「冲突平均化」问题。
代码库里有两套错误处理方案并存，一套是async/await加显式try/catch，另一套是全局错误边界。两种都在，历史遗留。
Claude写新代码时，把两套都接进去了。
结果是error event被两个handler分别捕获了一次，某些错误路径下触发了双重处理，日志里出现了重复上报，实际的错误却在其中一个handler里被提前消化掉了。排查了半小时才还原出调用链。
这是模型在缺乏明确约束时的默认策略，在两种模式之间取最大公约数，而不是做选择。
「规则7，遇到冲突，选一个，不要混。」
如果代码库里有两种互相矛盾的模式，选更新或者更经过测试的那个，说明原因，把另一个标记为待清理。混合了两种冲突模式的代码，是最差的代码。
第8条，是Karpathy「精准修改」规则的一个漏洞补丁。
那条规则告诉Claude不要动不该动的代码，但没有要求Claude在写新代码之前，先建立对上下文的完整理解。
有一次，Claude在一个文件里新增了一个函数，放在一个已经存在了6个月、功能完全相同的函数旁边。两个函数的签名不同，但语义等价。新函数因为import顺序的优先级更高，悄悄接管了调用方，把那个作为数据来源稳定运行了6个月的函数架空了，没有任何报错。
「规则8，写之前先读。」
在一个文件里加代码之前，先读清楚它的exports、直接的调用方、和明显的共享工具函数。如果不明白现有代码为什么这样组织，先问，再动。
「看起来跟我的改动没关系」，这句话在这个代码库里是最危险的话。
第9条，是关于测试覆盖率虚高的问题。
有一次，Claude为一个认证函数写了12个测试，全部通过。生产环境的认证随后挂掉了。
那12个测试在验证什么呢？在验证函数有返回值。
函数实现里hardcode了一个常量返回，所有断言都满足了。但认证逻辑本身是断的。这不是Claude写错了测试，是测试的断言没有对齐业务约束，属于测试设计问题，不是实现问题。
「规则9，测试要验证意图，不只是验证行为。」
每个测试都要能回答「为什么这个行为是重要的」，不只是「这个行为存在」。一个当业务逻辑变了也不会挂掉的测试，是没有意义的测试。
第10条，是专门针对多步骤Agent任务的状态管理问题。
Karpathy的4条规则基本针对单次代码生成的场景，隐含假设是一个原子操作，执行，观察结果，结束。
但真实的Claude Code工作往往不是这样，跨20个文件的重构，在一个会话里完成多步功能开发，跨多个commit的调试。这些是有状态的、多阶段的操作序列。
有一次，一个6步重构在第4步产生了错误。等问题被发现时，Claude已经在错误状态的基础上完成了第5步和第6步。后续的修改依赖了第4步引入的错误假设，相互耦合，拆解的成本比从第4步重做还要高。
「规则10，每完成一个重要步骤，就打一次检查点。」
总结已经做了什么，已经验证了什么，还剩什么。不要从一个你自己都描述不清楚的状态继续往前推进。如果跟丢了，就停下来，重新说清楚当前状态。
第11条，看起来简单，但在工程层面影响往往比预期大。
有一次，Claude在一个全部用类组件实现的React项目里引入了Hooks。
Hooks本身没有问题，逻辑也是正确的，运行时没有报错。
问题在测试层，这个代码库的测试体系基于类组件的生命周期方法构建，大量测试用例通过mock componentDidMount来验证行为。Hooks的引入打破了这个假定，导致测试无法正确反映组件状态。花了半天时间做测试层的适配。
这是典型的「局部正确，全局破坏」，新代码在功能上没有问题，但破坏了代码库其他部分对它的隐式假设。
「规则11，匹配代码库的规范，就算你不同意它。」
代码库用snake_case，你就用snake_case。用类组件，你就用类组件。如果你觉得某个规范有问题，把这个问题单独提出来讨论，不要在代码里悄悄开另一个分叉。
代码库内部，统一性大于品味。
最后一条，第12条，从工程角度看是最昂贵的失败模式。
最危险的不是模型返回错误，而是模型返回「成功」，但成功是虚假的。
有一次数据库迁移，Claude报告「迁移已成功完成」。
11天后，下游报表开始出现数据异常。
回溯之后发现，那次迁移里有14%的记录触发了约束冲突，被静默跳过了。跳过事件写入了日志，但Claude没有将其纳入状态判断，也没有在最终报告里提及。从执行层面看，迁移「完成了」，从数据完整性角度看，迁移是失败的。
这是观测层和执行层之间的不一致，是分布式系统里最难排查的一类问题，在AI辅助任务里同样存在。
「规则12，大声报错，而不是静默成功。」
「迁移完成」，如果有任何记录被跳过，就是错的说法。「测试通过」，如果跳过了任何测试，就是错的说法。「功能正常」，如果你没有验证我问过的那个边界情况，就是错的说法。
默认暴露不确定性，而不是藏起来。
好，12条规则讲完了，以下是完整的CLAUDE.md模板整理在下面，可以直接复制粘贴。
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 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 CodingState 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 FirstMinimum 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 ChangesTouch 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 ExecutionDefine 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 callsUse 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 advisoryPer-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 themIf 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 writeBefore 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 behaviorTests 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 stepSummarize 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 disagreeConformance > 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.
把这个存在你的仓库根目录，然后在12条规则下面加你的项目特定规则，技术栈、测试命令、常见错误模式。不要超过200行，超过之后，合规率会掉下去。
我测试了6周，50个有代表性的任务，横跨30个代码库，三个配置对比，无规则、Karpathy的4条、以及完整的12条，错误率分别是41%、11%、3%。
有一个数据值得单独拿出来说，从4条规则扩展到12条，合规率几乎没有变化，78%降到76%，但错误率又下降了8个百分点。
这说明新的8条规则覆盖的是原来4条没有触及的失败模式，两组规则在注意力竞争上没有明显干扰，是互补关系而不是替代关系。
以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～
谢谢你看我的文章，我们，下次再见。
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：SecureNexusLab i3eg1nner&林00 i3eg1nner&林00《我用这12条规则，把Claude Code的出错率从41%压到了3%》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论