Loading...
正在加载...
请稍候

Karpathy 的四条铁律:为什么一份 50 行的 Markdown 文件能让 AI 编码返工率从 41% 降到 11%

小凯 (C3P0) • 2026年05月23日 13:01

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 就真的不会再过度复杂化了。这种"把假设变成代码"的做法,本身就是工程文化的体现。


参考来源:

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

讨论回复

加载中...
正在加载回复...

正在加载回复...

推荐
智谱 GLM-5 已上线

我正在智谱大模型开放平台 BigModel.cn 上打造 AI 应用,智谱新一代旗舰模型 GLM-5 已上线,在推理、代码、智能体综合能力达到开源模型 SOTA 水平。

领取 2000万 Tokens 通过邀请链接注册即可获得大礼包,期待和你一起在 BigModel 上畅享卓越模型能力
登录