网传 Karpathy 的 CLAUDE.md 曝光: 10条铁律管住Claude Code！

一份疑似来自AI大牛Karpathy的Claude Code内部配置清单，10条铁律直击AI编程助手最常见的翻车现场。
核心内容：
1. 网传Karpathy配置文件的10条核心规则解析
2. 从4条到10条：规则从“防乱写”到“促自检”的演进
3. 如何将这些工程化约束应用到自己的项目中

这两天有一份 CLAUDE.md 文件在 X 上流传，据说是 Andrej Karpathy 加入 Anthropic 之后，在内部使用的 Claude Code 使用配置。

目前为止，这个出处没有公开确认，Karpathy 本人也没认领。

但这份配置文件还是值得一看。

里面的 10 条规则，基本都不是“请你写出高质量代码”这种空话。

它写的是 Claude Code 在真实项目里最容易出问题的地方：没读代码就开写、顺手重构、过度抽象、乱加依赖、没有复现就修 bug、觉得自己修好了但没跑测试。

这些问题，只要你稍微多用几次 Claude Code，大概率都见过。

八卦先放一边。

这份东西最有用的地方，是可以拆开抄进自己的 Claude Code 项目配置。

先看完整 10 条。

只看这个表，也能看出这份 CLAUDE.md 的底色：少一点自作主张，多一点工程约束。

从 4 条到 10 条，变化不只是变长了

这次流传的版本，和之前社区里已经传播过的 Karpathy 风格 CLAUDE.md 有一个明显区别：之前常见的是 4 条规则，现在这份截图里变成了 10 条。

之前那 4 条规则，大致解决的是 Claude Code 在“写代码前”和“写代码时”的问题：写之前先想清楚，不要猜；保持简单，不要过度设计；小范围修改，不要顺手重构；先定义完成标准，不要边做边想。

这 4 条规则已经很有用。很多 Claude Code 的失败，不是模型写不出来，而是它太快开始写。

但这次新增的 6 条，方向明显不一样。

它开始管代码写完之后的事情：怎么验证，怎么调试，怎么处理依赖，怎么沟通不确定性，怎么识别自己正在进入哪种失败模式。

旧版 4 条规则，是让 Claude Code 少乱写。新版 10 条规则，是让 Claude Code 开始自检。

这个变化很关键。

因为我们现在用 Claude Code，通常不是让它回一段代码就结束。它会读文件、改文件、跑测试、修报错，再继续迭代。任务越长，光要求它“写得好”越不够，还要让它知道什么时候验证，什么时候停，什么时候问。

这就是这份 10 条规则最值得看的地方。

别把 CLAUDE.md 写成许愿池

很多人写 CLAUDE.md，容易写成一堆愿望：

“你是一个资深工程师。”

“请写出高质量代码。”

“请遵循最佳实践。”

这些话不是完全没用，但太软了。

Claude Code 缺的不是鼓励。它缺的是边界。

好的 CLAUDE.md，应该把这些边界写清楚：动手前先读什么，遇到模糊需求怎么处理，哪些改动不能顺手做，修 bug 前要先证明什么，引入依赖前要问什么，范围扩大时什么时候必须停。

这份配置文件比较好的地方，就是它不写愿望，写约束。

它不说“请你遵循最佳实践”，而是直接说：先读文件，别乱改，别重构无关代码，先复现再修，新增依赖要说明理由。

下面按使用场景拆成 4 类。英文只摘截图里能看清、也值得复用的句子，不做完整搬运。

第一类：开工前，先阻止它凭感觉开写

这里对应的是 Read Before You Write、Think Before You Code 和 Goal-Driven Execution。这三条适合放在 CLAUDE.md 的最前面。

因为 Claude Code 最常见的第一反应，就是看到任务以后，立刻在训练数据里找一个相似模式，然后开始生成。

但真实项目不是面试题。真实项目有自己的目录结构、已有工具函数、测试习惯、命名风格、历史包袱。它没有读进去，就很容易写出一段“单独看没问题，放进项目里很奇怪”的代码。

截图里有一句话特别值得保留：

这句话很狠，也很适合放在第一条。

不是“浏览一下”，不是“看一眼”，是读。它管的是 Claude Code 的第一步：不要先写，先进入项目语境。

同一条规则里还有几个动作也很实用：

这几句放在一起，就是一个开工前检查清单：

先看相关文件，再看类似实现，再看项目已经在用什么库，再看测试怎么定义预期行为。

我建议你把这类句子放进所有项目的 CLAUDE.md。尤其是老项目、团队项目、或者已经有固定代码风格的项目。

第二条 Think Before You Code，管的是需求不清楚时不要猜。

截图里有一句很典型：

还有一句更关键：

这就是很多人用 Claude Code 时最容易忽略的地方。

我们总是希望它快点动手。但在真实项目里，快不一定是好事。尤其是“加认证”“优化性能”“补一个校验”这种需求，背后可能有很多实现路径。

Claude Code 如果悄悄选了一个方案，后面就会把这个方案一路执行到底。等你发现方向不对，可能已经多改了十几个文件。

所以这条规则的价值，是让它先把隐含假设说出来。

第三条 Goal-Driven Execution，我认为是整份文件里最值得抄的一条。

它要求每个任务在开始前都要有清楚的成功标准。

截图里的表达很直接：

它还给了几个转换例子，比如把“Add validation”变成更具体的结果：哪些输入要被拒绝，返回什么错误，哪些测试要通过。

这才是 Claude Code 能稳定工作的前提。

因为“修一下 bug”“优化一下体验”“加个校验”这种话，人能靠经验补上下文，但模型很容易补错。你必须把“完成”定义成机器能验证的状态。

这一类规则，我建议在 CLAUDE.md 里这样保留原意：

## Before Writing Code

- Read the files you're about to modify. Not skim. Read.
- Look at how similar things are done elsewhere in the project.
- Check the imports at the top of the file.
- Look at the test files.
- State your assumptions before coding.
- If something is confusing, stop and ask.
- Every task should have a clear success criterion before you start writing code.

这段不花哨，但很管用。它会让 Claude Code 慢半拍。

对 AI 编程来说，很多时候慢半拍就是质量。

第二类：修改中，防止它把小任务做大

这里对应的是 Simplicity、Surgical Changes 和 Dependencies。这三条规则，适合放在所有生产项目里。

Claude Code 很容易有一个倾向：为了把答案写完整，它会把问题做大。

你让它补一个函数，它可能抽一个服务类。你让它修一个边界条件，它可能顺手调整几个相邻模块。你让它处理一个日期格式，它可能加一个新依赖。

看起来积极，实际上危险。

截图里的 Simplicity 写得很直接：

后面还有一个判断标准也很值得记住：

这句话我很喜欢。

很多 AI 写出来的过度设计，本质上都在回应一个未来可能存在的问题。但真实工程里，“以后可能需要”通常不是需求，只是猜测。

如果现在只需要发一封欢迎邮件，就不要先抽象出一套 EmailService、provider、template engine、retry policy。原文里的例子就是这个意思。

Surgical Changes 管的是另一个问题：不要顺手改。

截图里有几句非常适合直接抄：

这几句话可以救很多代码评审。

AI 很喜欢“顺手”。顺手改命名，顺手调 import，顺手格式化，顺手把旧写法现代化。问题是，这些顺手修改会把 diff 变脏，让真正的改动被淹没。

所以这条规则不是反对你把代码改好。

它反对的是顺手改。

当前任务没有要求的变量名、import 顺序、格式化风格、旧代码清理，都先别碰。

原文还有一个非常好的 diff 检查：

这句话建议放进 CLAUDE.md。每一行改动都要能解释它和当前任务的关系。解释不了，就不应该出现。

再看 Dependencies。

截图里这条规则的基本立场是：

它还提醒，每个新增依赖都是你不能控制、但会永久进入项目的代码。

这句话对 Claude Code 尤其重要。因为模型很容易为了省事加包。一个日期格式化、一个 UUID、一个简单 map 操作，它都可能联想到某个库。

但项目真正的成本不只是一行 package.json。还有维护、安全、体积、团队理解成本，以及未来升级时的兼容问题。

这一类规则，可以整理成这样：

## Keep Changes Small

- Write the minimum amount of code that solves the problem.
- "In case we need to" is not a requirement.
- Don't touch what you weren't asked to touch.
- Match the existing style.
- Clean up after yourself, not after others.
- Don't reformat.
- Can you justify every single changed line?
- Don't add dependencies without thinking about it.

这段适合所有“让 Claude Code 改现有代码”的场景，尤其是小修小改。它管的不是能力，是手别太长。

第三类：出错后，防止它自信瞎修

这里对应的是 Verification 和 Debugging。如果只能从这份文件里选两条放进自己的项目，我会优先选这两条。

因为 AI 修 bug 时，最危险的句子往往是：this should fix it。

看起来像修好了，实际上没有证据。

Verification 这条规则开头就把这个差异说清楚了：

后面还有一句更硬：

这里不是在推崇某种测试流派。

它只是给 Claude Code 加了一个很硬的约束：修 bug 之前，先证明 bug 存在。

如果它不能复现问题，就很容易修症状，而不是修原因。

截图里还有一条我建议保留：

这句话非常适合真实项目。

因为有时候测试本来就失败。如果 Claude Code 没有先跑一遍，它后面就分不清哪些失败是自己造成的，哪些是历史问题。最后总结时一句“测试失败”，你也不知道该怪谁。

Debugging 这条规则更像一套调试流程。

截图里几个关键动作是：

这些句子都很朴素，但正好克制了 Claude Code 最容易犯的错：看到一个报错类型，就立刻生成一个看似合理的修复。

真实调试要先读完整错误和堆栈，要复现，要一次只改一个变量。

否则 bug 消失了，你也不知道是哪一处改动让它消失的。更麻烦的是，其他改动可能又埋了新问题。

这一类规则可以这样放：

## Debugging And Verification

- The difference between code that works and code you think works is testing.
- Write the test first when fixing bugs.
- Run existing tests before and after your changes.
- Read the error message.
- Reproduce first.
- Change one thing at a time.
- Don't add workarounds without understanding the root cause.

这段特别适合放在有测试体系的项目里。

如果项目测试很少，也不是没用。至少可以要求 Claude Code 提供最小复现、手动验证步骤，或者说明为什么暂时无法写测试。

重点就一句：不要让“感觉修好了”成为交付标准。

第四类：长任务中，让它知道什么时候该停

这里对应的是 Communication、Common Failure Modes，还有强化后的 Goal-Driven Execution。这部分是新版 10 条里最有进阶感的地方。

前面几条规则管的是怎么写。

这一类规则更狠一点：它管什么时候不能继续写。

Communication 里面有几句很适合放进配置：

这三句解决的是 Claude Code 交付时的沟通质量。

我不需要它写一大段“本次实现遵循了最佳实践”。我需要它告诉我：改了什么，为什么这样改，哪里还有不确定，哪些风险需要我知道。

尤其是不确定性。

原文里有个判断很实用：说“我不确定这个库是否支持 streaming”是有用信息；说“我觉得应该能工作”没什么用。

前者告诉人应该验证什么。后者只是安慰。

Common Failure Modes 是整份文件里最像“自检协议”的部分。

它把常见失败模式直接命名了：Kitchen Sink、Wrong Abstraction、Invisible Decision、Optimistic Path、Knowledge Hallucination、Style Drift、Runaway Refactor。

这些名字很重要。模式有了名字，就可以被写进停止条件。

比如 Kitchen Sink，就是让它做一件事，它顺手做了一堆事。

Wrong Abstraction，就是为了一个只出现一次的问题，做出一套漂亮但多余的抽象。

Invisible Decision，是它悄悄做了架构选择，比如数据库结构、API 形状、认证策略，但没有告诉你这是一个需要确认的决策。

Optimistic Path，是代码只处理 happy path，不管空输入、接口 500、文件不存在、用户乱填。

Knowledge Hallucination，是它自信地调用一个不存在的 API，或者使用一个早就被移除的参数。

Style Drift，是它写出自己偏好的风格，而不是当前项目的风格。

Runaway Refactor，是最危险的一种：修一个点，牵出另一个点，再牵出第三个点，最后改了十几个文件，已经忘了最开始要解决什么。

这类规则适合写成停止条件：

## Communication And Stop Conditions

- Say what you did and why.
- Flag concerns.
- Be precise about what you're uncertain about.
- If you notice a common failure mode, stop and reconsider.
- Watch for: Kitchen Sink, Wrong Abstraction, Invisible Decision, Optimistic Path, Knowledge Hallucination, Style Drift, Runaway Refactor.

这段尤其适合长任务。

比如你让 Claude Code 连续修测试、补实现、跑验证，或者配合 /goal 做目标驱动执行时，最需要的不是让它一路狂奔，而是让它在发现范围扩大时停下来。

能一直继续不稀奇。

知道什么时候该停，才是长任务里更稀缺的能力。

如果你只想抄作业，可以先抄这一版

下面这份是简化版。

不是原文件完整翻译，也不是我重新写的一套规则。它只保留原文件里最适合直接放进项目配置的句子。

你可以先复制进去，再根据项目实际情况增删。

# CLAUDE.md

## Before Writing Code

- Read the files you're about to modify. Not skim. Read.
- Look at how similar things are done elsewhere in the project.
- Check the imports at the top of the file.
- Look at the test files.
- State your assumptions before coding.
- If something is confusing, stop.
- Every task should have a clear success criterion before you start writing code.

## Keep Changes Small

- Write the minimum amount of code that solves the problem.
- "In case we need to" is not a requirement.
- Don't touch what you weren't asked to touch.
- Match the existing style.
- Clean up after yourself, not after others.
- Don't reformat.
- Can you justify every single changed line?
- Don't add dependencies without thinking about it.

## Debugging And Verification

- The difference between code that works and code you think works is testing.
- Write the test first when fixing bugs.
- Run existing tests before and after your changes.
- Read the error message.
- Reproduce first.
- Change one thing at a time.
- Don't add workarounds without understanding the root cause.

## Communication And Stop Conditions

- Say what you did and why.
- Flag concerns.
- Be precise about what you're uncertain about.
- If you notice a common failure mode, stop and reconsider.
- Watch for: Kitchen Sink, Wrong Abstraction, Invisible Decision, Optimistic Path, Knowledge Hallucination, Style Drift, Runaway Refactor.

我建议你不要无脑复制完就结束。

更好的做法是，把这份摘要当底座，然后继续补三类东西：

第一，补项目自己的技术栈和命令。比如用什么包管理器，怎么跑测试，怎么启动开发环境。

第二，补团队自己的代码约定。比如目录结构、命名习惯、提交格式、是否允许自动格式化。

第三，补你自己的停止条件。比如超过几个文件要先问，新增依赖必须确认，涉及数据库迁移必须先给方案。

到这一步，它才会从“网传配置”变成你自己项目里的配置。

最后叨叨几句

我看完这份文件，反而觉得它一点都不玄。

里面很多话都很朴素：读代码，少改动，先验证，不乱加依赖，不确定就说，不要重构失控。

这些本来就是好工程师每天该做的事。

但问题在于，Claude Code 不会天然继承你的工程习惯。你不写，它就只能按自己的方式猜。

所以 CLAUDE.md 里最没用的一句话，可能就是“你是资深工程师”。

太空了。

更应该写进去的是这些边界：

哪些事动手前必须读。

哪些事不能顺手做。

哪些结果必须验证。

哪些不确定性必须说出来。

哪些失败模式一出现就要停。

旧版 4 条规则，让 Claude Code 少犯写代码时的错。

新版 10 条规则，更像是在给它加一层自检协议。

Claude Code 越强，越不能只追求它“多做一点”。

真实项目里，更重要的是让它少做不该做的事，在该停的时候停下来，在该验证的时候拿出证据。

好的 CLAUDE.md，最后管的不是模型智商。

管的是工程习惯。

登录查看剩余 70% 内容