Karpathy的4条CLAUDE.md规则减少30%错误，我加了4条后降到5%
背景
超过200行的提示词，AI的遵从率直线下降，Agent会默默地忽略你的规则。
2026年1月，Andrej Karpathy 公开发难，剖析了 Claude Code 在生产代码库中的失败模式：静默假设、过度工程、正交损害。
一位开发者把他的抱怨打包成4条 CLAUDE.md 规则，发布到 GitHub。结果它成了今年增长最快的仓库——一夜之间传遍开发者社区。
但现在是5月。AI 生态在加速进化。我们正在运行越来越多的多步骤、自主 Agent 工作流。
当我在部署自主 Agent 重构数据摄入层时，遇到了新的摩擦：Agent 前三步完美执行，第四步开始产生幻觉，然后静默地覆盖了工作代码。
Karpathy 的原始规则无法防御多步骤退化。
通过精确设计4条额外规则——专门针对现代 Agent 编排——错误率进一步降低。
基础层：Karpathy的4条规则
这4条规则封堵了大约40%的标准单次提示失败模式：
规则1：先思考，再编码
不准静默假设。 如果存在更简单的方案，Agent 必须提出质疑。不确定就要问。
这是最基础的规则。大多数 AI 错误始于一个错误的前提假设——”我认为用户想要X”——然后基于它构建整个方案。
规则2：简单优先
最少代码解决问题。 没有推测性功能。不需要抽象就不要创造抽象。
这条规则专门针对 AI 的”过度工程”倾向——花哨的泛化、提前优化的抽象层、永远不会被调用的辅助函数。
规则3：手术式修改
只动你必须动的。 不要”改进”相邻的格式、注释、代码风格。
Karpathy 说的”正交损害”——AI 在修一个 bug 时顺手改了30行无关代码的格式。
规则4：目标驱动执行
定义成功标准，循环直到验证通过。 不要盲目遵循固定步骤，而是定义成功标准并独立迭代。
为什么这些规则在今天会失效？ 这些规则对多步骤流水线沉默不语。它们不给 Agent 设定 Token 预算，不强制检查点，而且假设 Agent 已经理解了周围的代码库。
执行层：4条新的Agent规则
规则5：硬性 Token 预算
没有预算的 Agent 会在同一个错误消息上消耗5万 Token 的上下文，直到它崩溃。
具体规则：
- 每个任务预算：4,000 Token
- 每个会话预算：30,000 Token
- 如果接近预算限制，强制 Agent 总结并重启会话
- 超支必须主动报告，而不是静默超限
# 在 CLAUDE.md 中的 Token 预算配置
budget:
per_task: 4000 # 每个独立任务
per_session: 30000 # 每次会话
on_breach: summarize_and_restart
我自己的经验：上线这条规则后，API 账单直接砍掉了一半。不是因为用的少了，而是因为 Agent 不再在一个死循环里浪费 Token。
规则6：先读后写
Karpathy 的规则说”不要碰相邻代码”，但它们没有说”理解相邻代码”。这导致 AI 盲目地编写重复函数——而同样的功能已经存在于30行之外。
具体规则：
- 在修改文件前，强制 Agent 读取文件的导出接口、直接调用方、共享工具函数
- “看起来不相关”是一个危险的假设
## Rule 6 — Read Before You Write
Before adding code to any file:
1. Read the file's exports and public API
2. Read immediate callers of the function you're modifying
3. Check shared utilities in the same module
If unsure why code is structured a certain way, ASK before writing.
规则7：每步检查点
如果一个6步重构在第4步出错，Agent 会愉快地在错误状态上执行第5步和第6步，破坏整个分支，最终只能手动 git reset。
具体规则：
- 每完成一个重要步骤，Agent 必须总结：已验证了什么 + 还剩下什么
- Agent 不能从一个它无法描述的状态继续执行
## Rule 7 — Checkpoint After Every Significant Step
After each operation step:
✓ Summarize what was done
✓ State what was verified
✓ State what remains
→ Stop and restate if you can't describe the current state back to me
这是最具杀伤力的一条。多步骤流水线中的错误传播是 Agent 中最常见的失败模式——一条链的强度取决于最薄弱的环节。
规则8：大声失败
最昂贵的失败看起来和成功一模一样。”迁移完成”是一句谎言——如果30条数据库记录因为约束违规被静默跳过。
具体规则：
- 默认暴露不确定性
- Agent 跳过任何内容，必须大声失败并立即通知用户
- “测试通过”是错误的——如果有任何测试被跳过
## Rule 8 — Fail Loud
- "Completed" is WRONG if anything was silently skipped
- "Tests pass" is WRONG if any were skipped
- Default to surfacing uncertainty, not hiding it
- When in doubt, over-communicate: tell me what you're unsure about
完整 CLAUDE.md 模板
将以下内容保存为项目根目录的 CLAUDE.md，然后在下方向追加你项目的具体技术栈信息：
# CLAUDE.md — 8条规则架构
以下规则适用于本项目中的每个任务，除非被显式覆盖。
偏向：在非琐碎工作上谨慎优先于速度。琐碎任务上使用判断。
## 规则1 — 先思考再编码
- 显式陈述假设。如果不确定，提问而不是猜测。
- 当存在更简单的方案时，提出质疑。困惑时停下来。
## 规则2 — 简单优先
- 解决问题的最少代码。不做推测性功能。
- 不超出需求范围的功能。不为一次性代码做抽象。
## 规则3 — 手术式修改
- 只动你必须动的。只清理你自己的混乱。
- 不要"改进"相邻代码、注释或格式。匹配现有风格。
## 规则4 — 目标驱动执行
- 定义成功标准。循环直到验证。
- 不遵循固定步骤。定义成功并独立迭代。
## 规则5 — Token 预算不是建议
- 每个任务：4,000 Token。每个会话：30,000 Token。
- 接近预算时，总结并重新开始。报告超支情况。
## 规则6 — 先读后写
- 添加代码前，读取导出接口、直接调用方、共享工具函数。
- 如果不确定代码为什么是某种结构，提问。
## 规则7 — 每步检查点
- 每个重要步骤后：总结做了什么、验证了什么、还剩什么。
- 不要从一个你无法描述的状态继续。停下来重新陈述。
## 规则8 — 大声失败
- "完成"是错的——如果任何内容被静默跳过。
- "测试通过"是错的——如果有任何测试被跳过。
- 默认暴露不确定性，而不是隐藏它。
我的看法
我从3周前开始使用这套8规则架构。变化是立竿见影的。
Token 预算是救命稻草。 之前我的 Agent 有时会在同一个问题上反复循环——修改代码→测试→失败→修改代码→测试→失败。每次循环吃掉几千 Token，直到我手动停下来。规则5强制 Agent 在接近预算时主动报告，让我从旁观者变成了管理者。
每步检查点规则彻底改变了代码质量。 以前 Agent 完成6步操作后给我看结果，我经常发现第3步就有问题。现在每分钟收到一次状态更新，可以在Agent继续之前纠正方向。
“大声失败”帮我抓到了一个数据迁移 bug。 Agent 报告”迁移完成”，但规则8强制它检查是否所有记录都已转换。结果发现了30条被约束违规跳过记录——手动 review 永远发现不了的那种。
Karpathy 定义了自动补全编码的问题。我们正在编排自主、多步骤 Agent——需要不同的约束体系。
说人话的总结
Karpathy的4条规则 → 堵住单次交互的坑（约40%）
我的4条新规则 → 堵住多步骤流水线的坑（再降约25%）
8条规则一起用 → 错误率降到5%以下
CLAUDE.md 不是一个一次性文件。它是一个严格的行为合约，旨在关闭特定的、代价高昂的失败模式。把它放到你的项目根目录，加上你的技术栈细节，然后看你的 Agent 表现大幅提升。
锁住环境、强制执行 Token 预算、要求检查点——这三点就能把 AI Agent 从”玩具”变成”工具”。
版权所有，本作品采用知识共享署名-非商业性使用 3.0 未本地化版本许可协议进行许可。转载请注明出处：https://www.wangjun.dev//2026/06/karpathy-claude-md-rules/