用 AI 编码 Agent 干活的工程师，大多经历过同一类憋屈时刻：明明只让它修一个空指针，它顺手重构了半个文件；明明需求有歧义，它自作主张选定一种理解，然后一路狂奔出一千行代码。一个针对这类问题的项目近来在 GitHub 上病毒式传播——andrej-karpathy-skills，主体只是一份从 Andrej Karpathy 公开观点提炼出的 CLAUDE.md 行为准则，star 数很快站上两万量级，衍生版本无数。本文按"概述 → 失败模式 → 核心原则 → 规则拆解 → 安装接入 → 本质思考 → 总结"组织全文。
1、项目概述
GitHub 仓库 andrej-karpathy-skills 由开发者 forrestchang 整理开源（现由 multica-ai 组织维护），采用 MIT 协议。项目内容源于 Andrej Karpathy 在 X 上发表的一篇谈 LLM（Large Language Model，大语言模型）编码陷阱的长文：他没有夸模型多聪明，而是罗列了一串 AI 编码助手令人头疼的慢性毛病。维护者把这些观点整理成一份拿来即用的行为准则，再配上各工具的适配目录。
仓库结构大致如下：
- 主体
CLAUDE.md：四条行为原则及其细则 skills/karpathy-guidelines/：技能化打包版本.cursor/rules/：Cursor 规则文件适配README.zh.md与EXAMPLES.md：中文说明与正反示例
一个没有任何算法创新的纯文本文件能火到这个量级，本身就说明痛点足够普遍：问题不在模型会不会写代码，而在它以什么方式写。
2、四类慢性失败模式
Karpathy 点名的四类问题，用过的工程师都会有既视感。原文大意如下：
模型会静默做出错误假设，并基于假设一路狂奔；在 100 行就够的地方，盖出一座 1000 行的臃肿建筑。
对应到日常工作里，症状可以归纳为四类：
| 失败模式 | 典型症状 |
|---|---|
| 过度设计 | 100 行够用写出 1000 行，防御不可能的场景 |
| 范围蔓延 | 塞入没人要求的功能、抽象与配置项 |
| 改动过量 | 修小 bug 顺手重构、重排无关代码 |
| 擅自假设 | 需求有歧义时不问，静默选定一种理解 |
这四类失败单独看都不致命，累积起来却让 diff 不可审、返工不断。更关键的是，它们不是能力不足导致的错误——恰恰相反，是模型能力过剩而约束缺位时，自然长出来的形状。所以解法不在换更强的模型，而在补约束。
3、四条行为原则
CLAUDE.md 把对策归纳为四条原则，与四类失败模式一一对应：
| 原则 | 一句话内核 |
|---|---|
| Think Before Coding | 显式陈述假设，不确定就问 |
| Simplicity First | 最小代码解决问题，零投机设计 |
| Surgical Changes | 每行改动都能追溯到用户请求 |
| Goal-Driven Execution | 先定成功标准，循环验证到通过 |
Think Before Coding（先想后写）要求存在多种理解时全部列出，而不是静默选一种；有困惑就停下来，指出具体困惑点再提问。
Simplicity First（最小实现）不做没被要求的功能、抽象层和可配置性，也不为几乎不可能发生的场景写错误处理。它给的自检标准很直接：资深工程师会不会说这段代码过度复杂？
Surgical Changes（外科手术式修改）不动邻近代码，不"顺手优化"，遵循既有风格；只清理自己的改动产生的孤儿代码，无关的死代码提一句即可，不删。
Goal-Driven Execution（目标驱动执行）把任务翻译成可验证的目标，例如"先写一个能复现 bug 的失败测试，再修到它通过"。LLM 擅长循环迭代直到达成明确目标，所以要给它目标，而不是手把手的步骤。
4、规则原文拆解
CLAUDE.md 原文极短，核心条目摘录如下：
## Think Before Coding
- State your assumptions explicitly. If uncertain, ask.
- If something is unclear, stop. Name what's confusing. Ask.
## Simplicity First
- Minimum code that solves the problem. Nothing speculative.
- Would a senior engineer say this is overcomplicated?
## Surgical Changes
- Touch only what you must. Clean up only your own mess.
- Every changed line should trace directly to the user's request.
## Goal-Driven Execution
- Define success criteria. Loop until verified.
细读会发现，这些规则没有一个字在教模型怎么写代码，全部在规定"什么时候停、什么时候问、动多大范围"。文件开头的定位也很坦率：这些准则偏向谨慎而非速度（bias toward caution over speed）。它的成功度量同样工程化——不必要的 diff 变少、过度复杂导致的返工变少、澄清问题发生在动手之前而不是出错之后。这份度量清单本身，就可以拿来对照自己团队的 Agent 使用状况。
5、安装与接入
Claude Code 用户首选插件方式，在 REPL 里依次执行两条命令：
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
插件方式全局生效，后续随插件市场自动更新。更适合团队推广的是直接落一份项目级 CLAUDE.md，引导命令如下：
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
新项目用 -o 直接生成文件；已有 CLAUDE.md 的项目把 -o 换成 >> 追加到末尾即可。仓库里的 skills/karpathy-guidelines/ 目录也可以整体拷贝到 ~/.claude/skills/，基于 Anthropic 的 Agent Skills 机制作为独立技能按需加载。
由于本体是纯 Markdown，它天然跨工具：Cursor 用户有现成的 .cursor/rules/karpathy-guidelines.mdc 适配；OpenCode、Codex、ChatGPT 这类支持自定义规则或系统提示的工具，把内容粘进去同样能用。社区还有大量 fork 与衍生版本提供一键安装等入口，细节见中文版 README。
6、行为契约的本质
这个项目最值得琢磨的，是它背后的判断：LLM 编码的瓶颈往往不在模型能力，而在人与 Agent 之间缺一份行为契约。
人类协作里，这些约束靠 code review、团队规范和沟通惯性兜底；换成 Agent，这些默认机制全部消失，模型只忠实执行字面需求，而没说出口的期待，它只能靠猜。CLAUDE.md 这类文件做的事情，就是把"团队工程共识"显式写成 Agent 读得懂的契约：怎么问、怎么收敛范围、怎么验证。
由此还能推出一个反直觉的结论：模型越强，这份契约越重要。能力弱时跑偏的能量小；能力强时，一次擅自假设就是一千行的错误方向。行为约束是在给能力上笼头，而不是给能力打补丁。
7、使用建议与局限
上手前建议先读 EXAMPLES.md 示例集，看同一任务在规则前后的 diff 差异，比读规则本身更直观。也有几点需要心里有数：
- 谨慎是用速度换的：提问变多，短平快任务更啰嗦
- 它防行为性失败，防不了模型的知识性错误
- 全盘套用未必合适，按团队节奏裁剪条目更好
- "最小实现"要配套验证标准，否则易成偷懒借口
再对照 Claude Code 官方文档中关于 CLAUDE.md 加载机制的说明，就能准确判断该全局安装还是项目级安装。
8、总结
andrej-karpathy-skills 用一份几百行的 CLAUDE.md 证明：AI 编码的多数慢性问题是行为问题，可以用行为契约来治。四条原则——先想后写、最小实现、外科手术式修改、目标驱动执行——分别对应过度设计、范围蔓延、改动过量、擅自假设四类失败模式；安装成本极低，不过是两条插件命令或一行 curl。
对于日常使用 AI 编码 Agent 的工程师，建议先把它装进一个真实项目跑一周，观察 diff 是否明显变干净，再决定推广范围；对于搭建团队 Agent 工作流的负责人，更建议把它当作行为契约的起点模板，结合自己的 code review 标准增删条目。模型能力交给厂商去卷，行为契约这件事，得自己来。
