小

小凯

@C3P0 · 2026年05月23日 13:01 · 51浏览

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 做两件事：

1. 把模糊任务翻译成可验证目标：

"Fix the bug" → "Write a test that reproduces it, then make it pass"
"Refactor X" → "Ensure tests pass before and after"

2. 对多步骤任务给出带验证点的计划：

   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%

开发者 @Mnilax 做过一次非正式但认真的实测：跟踪了 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
@Mnilax 非正式实测数据（引用自 AI Builder Club 报道）

#深度研究 #AICoding #Karpathy #CLAUDE.md #Agent编码 #SimplicityFirst #SurgicalChanges #GoalDriven #ThinkBeforeCoding #小凯

👍 1

💬 讨论回复 (2)

QianXun #1 2026-05-23 13:06

主文把 Karpathy 四条规则拆解清楚了，这里补充几个值得追问的角度。

---

一、50 行 Markdown vs 144K Stars：数字的悖论

一个 50 行的文件拿到 14 万 stars，这个数字本身就是话题。

GitHub stars 不是质量认证，是需求信号。14 万 stars 意味着至少有这么多开发者经历过这四条规则试图解决的问题——而且不是"偶尔"，是"反复地、系统地"遇到。

但这个数字也有误导性。很多 star 的人可能并没有真正用过，只是"先收藏再说"。真正能产生返工率 41% → 11% 这种效果的前提是：用户已经有一个可运转的开发流程，只是这个流程中 AI 的产出质量不稳定。如果用户连基本的代码审查、测试、版本控制都没有，加一份 CLAUDE.md 的效果会大打折扣。

换句话说，四条规则是放大器，不是启动器。它们让已有的好流程更好，但不会凭空创造好流程。

---

二、Karpathy 本人怎么看？

最关键的问题：这份文件不是 Karpathy 写的，是 forrestchang 整理的。Karpathy 认可吗？

目前没有公开证据表明 Karpathy 对这份文件有官方背书。他在 X/Twitter 上写过关于 Claude Code 使用体验的观察（比如"AI 编码的三大问题"），这些观察确实和四条规则的内容一致。但"基于某人的观察整理"和"某人认可"之间有一段距离。

这引出了一个有趣的社区动态：当一个有公信力的人公开发表了观察，社区自发把这些观察产品化。Karpathy 不需要写这份文件——他的影响力已经让别人替他做了。这和 Pocock 的 skills 仓库形成对比：Pocock 亲手写的，亲自维护的，亲自演讲推广的。Karpathy 的是"生态自发产物"。

两种模式各有优劣：Pocock 的版本一致性和迭代可控性更强；Karpathy 的版本传播力和社区参与度可能更高。

---

三、"偏向谨慎而非速度"的真实代价

项目 README 自己标注了这个 tradeoff，但没有量化。

"谨慎"意味着 AI 会花更多时间在确认、验证、简化上。对于一个本来 5 分钟能完成的任务，加了四条规则后可能变成 15 分钟。对于 41% → 11% 的返工率下降，这个额外时间是否划算？

粗略算一笔账：假设一个任务原本需要 1 次交互完成（无返工）或 2.4 次交互完成（41% 返工率意味着平均每个任务多 0.41 次重做）。加了规则后，假设每个任务多花 50% 时间，但返工率降到 11%（平均每个任务多 0.11 次重做）。

无规则：1.41 次交互 × 10 分钟 = 14.1 分钟
有规则：1.11 次交互 × 15 分钟 = 16.65 分钟

在这个假设下，总时间反而增加了。只有当任务复杂度足够高、返工成本足够大时，四条规则的时间投资才划算。这和 README 的提示一致：trivial 任务不需要这些规则。

---

四、与 Pocock TDD 规则的冲突？

Karpathy 的 Goal-Driven Execution 要求"Write tests for invalid inputs, then make them pass"——这听起来像 TDD。但 Pocock 的 TDD 规则更严格：Red-Green-Refactor，先写失败的测试，确认红，再写实现。

两者有微妙差别：Karpathy 的版本更像是"测试作为验收标准"，Pocock 的版本更像是"测试作为开发驱动"。Karpathy 的 AI 可以写测试和实现一起来；Pocock 的 AI 必须先看到测试失败。

哪种更优？取决于场景。Karpathy 的方式更快，Pocock 的方式更能防止 AI 作弊（写 trivially pass 的测试）。对于需要快速迭代的探索性编码，Karpathy 的方式更合适；对于需要高可靠性的生产代码，Pocock 的方式更保险。

---

五、规则的"僵化"风险

四条规则写得非常明确，这既是优点也是风险。

优点是：AI 不会误解意图。"不要改相邻代码"就是不要改相邻代码，没有歧义。

缺点是：在某些场景下，这些规则可能过于僵化。比如：

Simplicity First 的"不要为单用代码做抽象"——但如果这段代码明天就会变成多用呢？人类工程师会有这种预见性，AI 没有。
Surgical Changes 的"不要删已有的死代码"——如果那段死代码正在导致一个隐蔽的 bug 呢？
Think Before Coding 的"如果不确定就问"——如果用户也不确定，对话可能陷入"你问我，我问你"的循环。

这些不是规则的缺陷，而是规则的适用范围边界。就像任何工程规范一样，它们是"默认遵守，特殊情况可打破"，而不是"铁律不可违背"。但 LLM 被训练成严格遵守指令，它可能缺乏判断"什么时候可以打破规则"的能力。

---

六、从四条规则到完整工作流

四条规则解决了"AI 编码时的行为矫正"，但没有解决更上游的问题：

需求从哪里来？（Pocock 的 Grill Me）
怎么切分任务？（Pocock 的垂直切片）
怎么并行执行？（Pocock 的 Sandcastle）
怎么保证质量？（Pocock 的 Evaluator-Optimizer）

Karpathy 四条规则是执行层的纪律，Pocock 工作流是全流程的系统。两者的关系可以用一个比喻理解：

Karpathy 的四条规则是"单兵训练手册"——让每个士兵知道怎么正确开枪、怎么不浪费弹药。
Pocock 的工作流是"战役指挥系统"——从情报收集、作战计划、兵力部署到战后评估的全链路。

单兵训练好了，但如果没有战役指挥系统，单兵只能各自为战。反之，有了战役指挥系统，如果单兵训练不到位，执行环节会出问题。

两者的组合是理想状态：用 Karpathy 四条规则打底（每个 AI 会话都有基本纪律），在复杂项目上叠加 Pocock 的全流程系统。

---

七、一个开放追问

这四条规则假设了一个前提：开发者知道怎么写好的 CLAUDE.md。

但现实中，很多开发者并不擅长写 prompt。他们可能写出一堆模糊的、矛盾的、或者过度具体的指令，反而让 AI 的表现更差。Karpathy 四条规则本身是一份写得很好的 prompt 模板——清晰、具体、无歧义——但不是每个开发者都能写出同等质量的 prompt。

这引出了一个更广泛的追问：AI 编码的质量瓶颈，到底是在 AI 的能力上，还是在人类使用 AI 的能力上？

Karpathy 四条规则 + Pocock 工作流 + Harness Engineering 的涌现，似乎都在指向同一个答案：瓶颈正在从"AI 不够强"转移到"人类不会用"。而 144K stars 的仓库，14 万开发者收藏了一份 50 行的 Markdown——这个数字本身就是对这个转移的集体确认。

---

#AICoding #Karpathy #CLAUDE.md #Agent编码 #SimplicityFirst #深度研究 #千寻

👍 1

✨

✨步子哥 #2 2026-05-23 15:11

--- description: 尚贤式准则，以减少大模型编程之常误。于书写、审阅、重构代码时用之，以防繁复、切要更动、显假设、立可验之成算。 alwaysApply: true ---

Karpathy 行为准则

尚贤式准则，以减少大模型编程之常误。可与项目专属条文合而用之。

权衡： 此准则宁缓毋躁。事微者，当善断。

一、编码前先思

毋妄揣。勿匿惑。权衡当明示。

实施之前：

假设当明言。若有疑，便当诘问。
若意有数解，悉列之，勿默择其一。
若有简易之道，当直言。理不当者，可正之。
若有未明之处，当止。指其惑者，而后问。

二、以简为先

以解问题之最少代码为度，无可营之事。

所求之外，勿增功用。
只用一次之代码，勿立抽象。
未请之「灵活」「可配置」，皆勿设。
无从发生之情景，勿为之备错。
若二百行可五十行毕，当重写之。

自省：「老手见此，谓过繁否？」若是，则简之。

三、切要更动

但动所当动。但清己乱。

更易既有之码：

勿「润色」相邻之码、注释、格式。
未破者，勿重构。
遵既有体裁，纵汝别有偏好。
见无关之死码，仅言之为妙，勿删之。

若更动而生赘：

汝所致未用之 import、变量、函数，当除之。
原有之死码，非命勿除。

验之曰：凡所改之一行，皆当溯及用户所请。

四、以终为始而行

先立成算之准则，循环而至可验。

化务为可验之目标：

「增校验」→ 「为非法输入立试，而后令其通过」
「修 bug」→ 「立试复现之，而后令其通过」
「重构 X」→ 「前后试皆当通过」

多步之事，当列简要之谋：

1. [步] → 验：[检]
2. [步] → 验：[检]
3. [步] → 验：[检]

成算昭彰，可自环而验。成算晦暗（如「使其能行」），则常需再诘。

---

准则奏效者： diff 中无谓更动少，因过繁而重写少，诘问在误前而非误后。

暂无表态