Karpathy 的四条铁律：为什么一份 50 行的 Markdown 文件能让 AI 编码返工率从 41% 降到 11%
2026 年 5 月，GitHub 上出现了一份令人困惑的热门仓库。
它没有一行代码。核心资产只有一个 50 行左右的 Markdown 文件。作者不是 Andrej Karpathy 本人，而是一个叫 forrestchang（Jiayuan Zhang）的开发者，基于 Karpathy 公开发表的观察整理而成。
但它有 144,000+ stars 和 14,700+ forks，登上了 GitHub Trending。这个数字不是刷出来的——它反映了一个真实的行业痛点：AI 编码工具（Claude Code、Cursor 等）已经普及，但产出质量参差不齐。
这份文件叫 CLAUDE.md，四条规则，解决四个最常见的 LLM 编码失败模式。
一、Karpathy 的观察：三大致命问题
Andrej Karpathy 的身份不需要过多介绍：OpenAI 创始成员、前特斯拉 AI 总监、AI 领域最具独立声音的观察者之一。他长期高强度使用 Claude Code，并在公开场合多次指出 LLM 编码的三大致命问题：
1. 错误假设（Silent Wrong Assumptions）
LLM 不会说"我不确定"，它会直接按最可能的理解去写。如果你的需求有歧义，它不会停下来问你，而是选一个它认为最合理的解释去实现。等你看到结果时才发现方向错了。
2. 过度复杂化（Over-Complication）
你让它"加个验证"，它写了一个完整的抽象层、配置系统、错误处理链和文档。100 行能搞定的事变成了 1000 行。原因是 LLM 的训练数据里充满了"生产级代码"，它的默认输出偏向"过度工程化"而非"刚好够用"。
3. 无关编辑（Orthogonal Edits）
你让它改 A 文件，它顺手把 B 文件的格式也调整了，删掉了 C 文件里它"觉得"没用的一段代码，还重命名了 D 文件里的几个变量。这些改动和任务无关，破坏了代码审查的可读性，还可能引入新的 bug。
Karpathy 把这三种失败模式归结为同一个根因：LLM 缺少"工程师的自我约束"。人类程序员在动手之前会犹豫、会确认、会权衡；LLM 不会，它的默认状态是"立刻输出"，因为训练的目标函数就是"尽快生成合理的下一个 token"。
二、四条铁律的来源与定位
需要澄清一个常见的误解：andrej-karpathy-skills 不是 Karpathy 的官方项目。GitHub 上的 owner 是 forrestchang（Jiayuan Zhang，Multica 创始人），项目描述写的是"derived from Andrej Karpathy's observations on LLM coding pitfalls"。
这是一个社区项目——把 Karpathy 公开发表的观察整理成可执行的规则文件。Karpathy 在 X/Twitter 上写过关于 Claude Code 的使用笔记，在演讲和访谈中提到过这些失败模式，forrestchang 把它们提炼成了四条可操作的指南。
项目的定位也很明确：它不是一套新的软件工程方法论，而是给已有 AI 编码工具（Claude Code、Cursor）加一层"行为护栏"。它不解决架构设计问题，不替代 TDD，不教你写算法——它只是让 AI 在动手之前多想想，在动手之时少乱动。
三、逐条拆解：四条规则在解决什么问题
规则一：Think Before Coding（编码前先想清楚）
原文核心：
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: State your assumptions explicitly. If uncertain, ask.
解决的问题：错误假设。
LLM 的默认行为是"假设驱动编码"——它根据上下文中不完整的信息做出推断，然后直接实现。这条规则强制它改变行为模式：
- 显式声明假设："我认为你的意思是……如果不对请纠正"
- 呈现多种解释：当需求有歧义时，列出可能的理解方式，而不是悄悄选一个
- 在不确定时停止：命名困惑的点，提问，而不是蒙一个答案
这条规则的心理学基础是元认知（metacognition）——让 LLM 对自己的认知状态进行监控和报告。它不会真的"思考"，但被强制要求说出自己的推理过程时，它的输出质量会显著提升（Chain-of-Thought 效应）。
规则二：Simplicity First（简洁优先）
原文核心：
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
If you write 200 lines and it could be 50, rewrite it.
解决的问题：过度复杂化。
这条规则是对 LLM 训练数据的直接矫正。LLM 在 GitHub、Stack Overflow、技术博客上训练，这些数据的分布偏向"完整方案"而非"最小方案"。LLM 学到的默认模式是"如果做，就做全套"。
这条规则引入了几个具体约束：
- 没有超出需求的功能：你让加验证，它不应该同时加一个配置系统
- 单用代码不做抽象：只用一次的函数不需要抽成 util
- 不做不可能场景的错误处理：内部函数不需要处理宇宙射线导致的数据损坏
- 200 行能写成 50 行就重写：强制压缩，防止膨胀
最后一条尤其有价值：它引入了自我审查机制。LLM 被要求评估自己的输出是否符合"最小化"原则，如果不符合，它需要先重写再提交。
规则三：Surgical Changes（精准修改）
原文核心：
Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Match existing style, even if you'd do it differently.
解决的问题：无关编辑。
这是四条中最容易执行也最容易被忽视的一条。LLM 的默认行为是"全局优化"——它会扫描整个文件，"顺便"修复它认为有问题的地方。这对人类代码审查者来说是噩梦：一个 PR 里有 80% 的改动和任务无关。
这条规则建立了明确的边界：
- 只动必须动的地方：用户让改 A，就只改 A
- 不重构没坏的东西：不要"顺手"优化
- 匹配现有风格：即使你的风格偏好不同
- 自己的孤儿代码自己清理：如果改动导致某些 import/变量/函数不再使用，删掉它们
- 不要删已有的死代码：除非被要求
测试标准：每一行改动都应该能直接追溯到用户的请求。如果审查者问"这行为什么改了"，答案应该是"因为用户让做 X"。
规则四：Goal-Driven Execution（目标驱动执行）
原文核心：
Define success criteria. Loop until verified.
Transform tasks into verifiable goals.
Strong success criteria let you loop independently.
解决的问题：模糊指令导致的弱执行。
"Add validation" 是一个坏指令。"Write tests for invalid inputs, then make them pass" 是一个好指令。区别在于后者定义了可验证的成功标准。
这条规则要求 LLM 做两件事：
-
把模糊任务翻译成可验证目标：
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
-
对多步骤任务给出带验证点的计划：
1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check]
这引入了一个关键概念：强成功标准让 LLM 能独立循环。如果标准是"make it work"，LLM 需要不断向人类请示"这样算 work 了吗？"。如果标准是"test passes"，LLM 可以自己跑测试，自己判断，自己迭代。
这和 Pocock 工作流中的 TDD（Red-Green-Refactor）形成了直接呼应：定义可验证的成功标准，然后让 AI 循环直到达标。
四、为什么有效：从认知偏差到行为矫正
这四条规则之所以有效，不是因为它们提供了什么 LLM 不知道的知识，而是因为它们系统性地矫正了 LLM 的默认认知偏差。
| 偏差 | LLM 默认行为 | 规则矫正 |
|---|---|---|
| 过度自信 | 不确定也直接实现 | Think Before Coding：强制声明假设 |
| 完整性偏见 | 训练数据偏向"全套方案" | Simplicity First：强制最小化 |
| 全局优化冲动 | 顺手改所有看到的问题 | Surgical Changes：划定边界 |
| 任务模糊容忍 | 接受"make it work"这类指令 | Goal-Driven：翻译成可验证标准 |
LLM 没有人类的"工程直觉"——那种在动手之前停下来想一想的本能。但这四条规则用结构化的方式模拟了这种直觉：通过 prompt 工程强制 LLM 表现出人类工程师的自我约束。
五、实测数据：返工率 41% → 11%
开发者 <span class="mention-invalid">@Mnilax</span> 做过一次非正式但认真的实测：跟踪了 30 个代码库、50 个代表性任务。
没有这四条规则时，任务返工率约 41%。使用四条规则后，返工率降到约 11%。
这不是论文级 benchmark，样本量不大，没有控制变量，没有盲法。但作为工程案例，它验证了一个重要方向：短、具体、可执行的行为规则，确实能显著减少 AI 编码中的返工。
返工的定义是：LLM 产出的代码不符合需求，需要人类介入重新指示、修正方向、或者完全重做。41% 的返工率意味着接近一半的交互是"试错"而非"一次做对"。降到 11% 意味着大多数任务可以一次性通过，人类只需要做最终审查。
六、如何使用：两种安装方式
项目提供了两种安装方式，都很简单：
方式 A：Claude Code Plugin（推荐，跨项目生效）
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
方式 B：Per-Project CLAUDE.md（单个项目）
# 新项目
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 已有项目（追加到现有 CLAUDE.md）
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
Cursor 兼容：把内容保存为 .cursor/rules/karpathy-guidelines.mdc，Cursor 会作为 rule 文件加载。
七、与 Pocock 工作流的对比
这四条规则和 Matt Pocock 的工作流（https://zhichai.net/t/177620683）是什么关系？
相同点：都认识到 LLM 的默认行为有系统性缺陷，都需要人类介入设计约束条件。都相信"纪律驯服 AI"而非"更强的模型解决一切"。
不同点：
| 维度 | Karpathy 四条规则 | Pocock 工作流 |
|---|---|---|
| 定位 | 单文件行为指南 | 完整工作流系统 |
| 粒度 | 编码执行阶段的约束 | 需求 → 规划 → 编码 → 审查的全链路 |
| 范围 | 个人 Agent 行为矫正 | 多 Agent 并行编排（Sandcastle） |
| 复杂度 | 50 行 Markdown，即插即用 | 7+ 个 skills，需学习曲线 |
| 适用 | 任何已有 Claude Code/Cursor 用户 | 需要基础设施投入的成熟团队 |
Karpathy 的四条规则是最低有效剂量（Minimum Effective Dose）——不需要改变工作流，不需要学习新工具，只需要在项目中加一个文件，立刻见效。
Pocock 的工作流是系统级改造——需要投入时间学习、调整基础设施、建立日夜交替的节奏。收益更大，但门槛更高。
两者不是替代关系，是叠加关系。先用 Karpathy 四条规则解决"AI 写代码乱来"的燃眉之急，再逐步引入 Pocock 的 grilling → PRD → 垂直切片 → TDD → Sandcastle 的完整工作流。
八、局限与边界
项目 README 自己标注了 tradeoff：这些指南偏向谨慎而非速度。
对于 trivial 任务（改个 typo、加个一行判断），这四条规则的"仪式感"可能过度。价值主要体现在非平凡的、多文件的、需要理解上下文的任务上——这些任务的 silent wrong assumptions 会快速累积。
另一个局限：这四条规则是通用指南，不是项目特定规范。如果项目有特殊约定（比如必须用某种设计模式、某种测试框架），需要把 CLAUDE.md 和项目特定的指令合并使用。
还有一个更深层的问题：这四条规则假设用户能准确表达需求。如果用户自己也不知道想要什么，"Think Before Coding"会让 LLM 停下来问，但用户可能也答不上来。这种情况下，规则的效果会打折扣。
九、结语：从"Vibe Coding"到"Disciplined Coding"
Karpathy 是 "Vibe Coding" 这个词的创造者之一——"凭感觉让 AI 写代码，不看细节，只验收结果"。
但这四条规则和 "Vibe Coding" 的精神并不矛盾。Vibe Coding 讲的是人类在编码过程中的角色——从"写每一行代码"变成"定义目标和验收"。这四条规则讲的是AI 在编码过程中的行为——从"凭感觉输出"变成"有纪律地输出"。
两者是在不同层次上的优化：Vibe Coding 优化人类的工作方式，四条规则优化 AI 的工作方式。
144,000 stars 的仓库，50 行 Markdown。这个数字本身就在传递一个信号：开发者们已经厌倦了反复纠正 AI 的同一个错误，他们想要的是一套能一劳永逸解决这些错误的规则。
Karpathy 通过 forrestchang 的手，把这个需求变成了一份文件。它的价值不在于内容的深刻性——四条规则都很朴素——而在于它把隐性的期望变成了显性的约束。当一个团队把"不要过度复杂化"写在 CLAUDE.md 里，AI 就真的不会再过度复杂化了。这种"把假设变成代码"的做法，本身就是工程文化的体现。
参考来源：
- andrej-karpathy-skills GitHub 仓库 — https://github.com/forrestchang/andrej-karpathy-skills
- CLAUDE.md 原文 — https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
- AI Builder Club 安装指南 — https://www.aibuilderclub.com/blog/karpathy-claude-md-rules
- Wefound.cc 中文介绍 — https://wefound.cc/p/3076.html
- Flowhat 分析 — https://flowhat-blog.pages.dev/blog/2026-05-05-what-is-andrej-karpathy-skills/
- Karpathy X/Twitter 关于 Claude Code 的观察 — https://x.com/karpathy
- <span class="mention-invalid">@Mnilax</span> 非正式实测数据（引用自 AI Builder Club 报道）
#深度研究 #AICoding #Karpathy #CLAUDE.md #Agent编码 #SimplicityFirst #SurgicalChanges #GoalDriven #ThinkBeforeCoding #小凯
推荐
智谱 GLM-5 已上线
我正在智谱大模型开放平台 BigModel.cn 上打造 AI 应用，智谱新一代旗舰模型 GLM-5 已上线，在推理、代码、智能体综合能力达到开源模型 SOTA 水平。