Karpathy 的 CLAUDE.md，到底解决了什么问题

用过 Claude Code 的人，多少都踩过这么几个坑：你让它改一个函数，它顺手把旁边三个文件的格式也重排了；你要一个二十行的工具函数，它给你整出一套抽象基类加工厂方法加配置对象；你说"修这个 bug"，它闷头写了两百行代码，方向完全跑偏，你审代码的时候才发现它理解错了需求。

这些不是偶发的，是 LLM 写代码的系统性毛病。Andrej Karpathy 在今年年初发了一系列关于 LLM 编程陷阱的观察，社区里有人（Forrest Chang）把这些观察提炼成了一个六十行的 CLAUDE.md 文件，四条原则，放进项目根目录，Claude Code 每次启动都会读。

先把原文贴出来：

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

四条原则各自在干什么

Think Before Coding -- 治的是"默默跑偏"。Claude Code 拿到有歧义的需求，不问你就自己选一个方向开干。加了这条后，它会在回复里先把假设说出来——"我假设你要在 API 层做校验"——你同意就继续，不同意纠正，代码还没写，成本为零。

Simplicity First -- 治的是"过度工程"。你要一个函数，它给你一个类继承体系外加三个 optional 参数标注着"for future flexibility"。这条是四条里效果最明显的，投机性抽象大幅减少。

Surgical Changes -- 治的是"顺手乱改"。你改一个地方，diff 里出现四个文件的变动，import 被重排，旧注释被删，旁边的代码被格式化了一轮。加了这条后，drive-by reformatting 基本消失。

Goal-Driven Execution -- 治的是"模糊执行"。把"修这个 bug"转化成"写一个能复现的测试，然后让它通过"。但这条有个特殊之处：它要求改变的是你写 prompt 的方式，不是模型的行为。你不改写法，这条就是摆设。

能做什么

说白了，这个文件解决的是执行纪律问题——LLM 写代码时那些让你反复手动纠正的坏习惯：瞎猜需求、过度设计、乱动代码、没有明确完成标准。如果你每天都在跟这几个问题较劲，这个文件第一次用就能感受到区别。

它特别适合一种场景：你已经有自己的 CLAUDE.md，里面写的是项目级的规则——用什么技术栈、代码风格怎么定、错误处理的约定。但你发现模型虽然知道了"该做什么"，执行过程中还是会跑偏、会加戏。Karpathy 这个文件补的就是"怎么做"这一层——行为约束，不是业务规则。

所以正确的用法是补充，不是替代。你的项目 CLAUDE.md 管"做什么"，Karpathy 的原则管"怎么做"，两层分清楚。

不能做什么

不能替代好的 prompt。 四条原则都是行为修正，不是理解力增强。你的需求描述本身就模糊，再多行为约束也救不回来。

不能做架构决策。 用 Postgres 还是 DynamoDB，这不是 CLAUDE.md 能管的事。它能管的是"决定用 Postgres 之后，别给两张表的需求生成六张表的 schema"。

不能解决长会话漂移。 Claude Code 的上下文窗口越往后，早期指令的影响力越弱，这是模型本身的特性，CLAUDE.md 改不了。

不能覆盖你 prompt 里的紧迫感。 你写"快速修一下，马上要部署了"，谨慎原则就会被紧迫语气覆盖。

原则之间会打架。 最典型的：你的项目规则写"所有 API 端点要完整的错误处理"，Karpathy 说"不给不可能的场景写错误处理"。两条都对，模型得自己裁决，结果不稳定。所以追加进已有 CLAUDE.md 的时候，得检查一遍有没有冲突，项目规则尽量写具体，别给模型留裁量空间。

怎么用

如果你还没有 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

顺序有讲究。项目规则在前建立"这个项目是什么"，行为原则在后约束"在这个项目里怎么干活"。反过来放，模型会把行为原则当主要上下文，你的项目规则反而变成了参考建议。

另外留意 token 预算。CLAUDE.md 里的每一行都在跟你的实际工作抢上下文空间。六十行原则加上你自己的项目规则，总量控制在一百五十行以内比较稳，再多模型的遵循度会明显下降。

本质上，Karpathy 这个文件编码的是你本来就会手动做的纠正。执行纪律的修正器，不是思维能力的放大器。分清楚它解决的是哪类问题，比盲目安装更重要。