Karpathy CLAUDE.md曝光 10条铁律管住Claude Code

最近，一份名为 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，管的是需求不清晰时不要猜测。截图中有一句很典型：State your assumptions. 还有一句更关键：If something is confusing, stop. 这正是许多人使用 Claude Code 时最容易忽略的地方。我们总是希望它快点动手，但在真实项目中，快不一定是好事。尤其是“加认证”“优化性能”“补一个校验”这类需求，背后可能有多条实现路径。如果 Claude Code 悄悄选择了一个方案，它就会沿着该方案一路执行下去，等你发现方向不对时，可能已经多改了十几个文件。因此，这条规则的价值在于让它先把隐含假设说出来。

第三条 Goal-Driven Execution，是整份文件中最值得借鉴的一条。它要求每个任务在开始前都必须有清晰的成功标准。截图中的表达非常直接：Every task should ha ve a clear success criterion before you start writing code. 它还给出了几个转换示例，例如将“Add validation”转化为更具体的结果：哪些输入要被拒绝，返回什么错误，哪些测试必须通过。这才是让 Claude Code 稳定工作的前提。因为“修一下 bug”“优化一下体验”“加个校验”这类模糊表述，人类可以依靠经验补充上下文，但模型很容易补错。你必须将“完成”定义成机器可验证的状态。

这一类规则可以这样保留原意：

## 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 ha ve a clear success criterion before you start writing code.

这段内容不花哨，但非常实用。它会让 Claude Code 慢半拍。对 AI 编程而言，很多时候慢半拍就意味着质量。

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

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

Claude Code 很容易出现一个倾向：为了把答案写完整，它会将问题扩大化。你让它补一个函数，它可能抽出一个服务类；你让它修一个边界条件，它可能顺手调整几个相邻模块；你让它处理一个日期格式，它可能添加一个新依赖。看起来积极主动，实则相当危险。

截图中的 Simplicity 写得很直接：Write the minimum amount of code that solves the problem. 后面还有一个判断标准也很值得铭记："In case we need to" is not a requirement. 这句话值得反复品味。很多 AI 写出的过度设计，本质上都是在回应一个未来可能存在的问题。但在真实工程中，“以后可能需要”通常不是需求，只是猜测。如果当前只需要发送一封欢迎邮件，就不要先抽象出一套 EmailService、provider、template engine、retry policy。

Surgical Changes 约束的是另一个问题：不要顺手修改。截图中几句非常适合直接抄录：Don't touch what you weren't asked to touch. Match the existing style. Clean up after yourself, not after others. Don't reformat. 这几句话可以拯救很多代码评审。AI 很喜欢“顺手”——顺手改命名，顺手调 import，顺手格式化，顺手把旧代码现代化。问题在于，这些顺手修改会让 diff 变得混乱，使真正的改动被淹没。因此，这条规则并非反对你把代码改好，而是反对顺手修改。当前任务没有要求的变量名、import 顺序、格式化风格、旧代码清理，都先不要碰。原文还有一个非常好的 diff 检查：Can you justify every single changed line? 这句话建议放入 CLAUDE.md。每一行改动都要能解释其与当前任务的关系，解释不了就不应该出现。

再看 Dependencies。截图中这条规则的基本立场是：Don't add dependencies without thinking about it.

它还提醒，每一个新增依赖都是你无法控制、但会永久进入项目的代码。这句话对 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 这条规则一开头就把这个差异说清楚了：The difference between code that works and code you think works is testing.

后面还有一句更硬核：Write the test first when fixing bugs. 这里并非推崇某种测试流派，而是给 Claude Code 加了一个非常严格的约束：修复 Bug 之前，先证明 Bug 存在。如果它无法复现问题，就很容易修复症状而非根本原因。截图中还有一条值得保留：Run existing tests before and after your changes. 这句话非常适合真实项目。因为有时测试本来就失败，如果 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 中有几句很适合放入配置：Say what you did and why. Flag concerns. Be precise about what you're uncertain about.

这三句解决的是 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 ha ve 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，最后管理的不是模型智商，而是工程习惯。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Karpathy CLAUDE.md曝光 10条铁律管住Claude Code要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题