karpathy 在 X 上吐槽了 Claude。Forrest Chang 把吐槽变成了四条规则和一个 GitHub 仓库。仓库在几周内获得了 12 万星标。至今，大多数读到这篇文章的开发者仍然只用那四条规则。但问题是，那些规则写于 1 月。现在已是 2026 年中，Claude Code 生态已经变了。
这篇文章会给你完整的 12 条 CLAUDE.md 规则、每条规则存在的原因、它堵住了什么失败模式，以及原模板在什么地方悄悄失效。最后附上可粘贴的完整文件。
什么是 CLAUDE.md，以及为什么大多数人都用错了
CLAUDE.md 是一个放在仓库根目录的文件。Claude Code 每次会话前都会读取它。它不是一个提示词。它不是偏好列表。它是 Claude 在你的代码库中行为的操作系统。
大多数开发者会犯三种错误之一：他们把所有偏好的东西都塞进这个文件，直到膨胀超过 4000 token，导致合规率降到 30%，因为重要的规则被埋没了；他们完全跳过这个文件，每次会话都重新提示，这浪费了五倍的 token，而且毫无一致性可言；他们粘贴一次模板就忘了，然后看着它在几周内随着代码库的变化而悄悄失效。
官方 Anthropic 文档明确说明：CLAUDE.md 是建议性的。Claude 在 200 行以内大约 80% 的时间会遵循它。超过 200 行，合规率会急剧下降。有用的 CLAUDE.md 文件的上限是短小、精确，并且通过直接规则而非建议来强制执行。
原始的四条规则：如果你什么都没有，从这里开始
Andrej Karpathy，特斯拉前 AI 总监、OpenAI 联合创始人，在 2026 年 1 月发布了一个帖子，关于他几周密集使用 Claude Code 后的体验。不是一个框架，而是一个吐槽。他反复遇到三种失败模式：Claude 默默假设而不是询问；Claude 过度构建而不是解决最小问题；Claude 触碰了从未被要求触碰的代码。
Forrest Chang 读了这个帖子，并将其记录为规则。一个文件，65 行，第二天就出现在了 GitHub 上。以下是这四条规则：
规则 1 — 先思考再编码
在编写代码前说明你的假设。暴露权衡。在猜测前先询问。当存在更简单的方案时，要提出反对意见。永远不要在未经核实的假设上进行构建。
规则 2 — 简单优先
编写解决问题所需的最少代码。没有推测性的功能。没有为只使用一次的代码进行抽象。如果一位资深工程师会认为它过于复杂，那就简化它。
规则 3 — 外科手术式修改
只触碰任务所要求的部分。不要改进相邻的代码、注释或格式。不要重构没有问题的代码。精确匹配现有风格。
规则 4 — 目标驱动执行
在开始前定义成功的样子。持续循环直到成功被验证。不要为 Claude 列出步骤。告诉 Claude 完成的样子，让它自己找到路径。
这四条规则可以堵住大约 40% 的无监督 Claude Code 会话中的失败模式。剩下的 60% 存在于原始模板没有处理的空白中，因为那些问题在 Karpathy 发帖时还不完全存在。
为什么原始模板需要扩展
最初的四条 Karpathy 规则是为了修复单 Agent、编写代码的会话而设计的。2026 年的 Claude Code 生态运行着多 Agent 设置、Hook、技能库以及跨越会话的多步骤工作流。原始模板对此毫无涉及。
原始规则中出现了四个特定的空白。第一，Agent 冲突：两个 Agent 编辑同一个文件，没有任何所有权规则，默默地相互覆盖对方的修改。第二，Hook 级联：Hook 在每次工具调用时触发，将一个 200 token 的请求变成 8000 token，且没有任何预算来阻止它。第三，技能加载冲突：多个描述相似的技能让调度器混淆，加载了错误的技能。第四，多步骤会话中断：一个 6 步的重构在第 4 步失败，但第 5 步和第 6 步仍然运行，并在损坏的状态上继续构建。
最初的四条规则没有错，但它们不完整。下面的 8 条附加规则堵住了这些特定的空白。
8 条新规则：每条堵住了什么
规则 5 — 不要将模型用于非语言工作
确定性决策应属于确定性代码。重试逻辑、路由阈值、升级规则、基于状态的分支：这些都不应该调用 LLM。模型每周都会根据上下文窗口中的内容做出不同的决定。看似一致的行为其实是尚未暴露的方差。
具体事件：一个用于“决定是否在 503 上重试”的 LLM 调用工作了两周，然后开始产生随机行为，因为模型开始将请求体作为重试决策的上下文阅读。策略变得随机，因为有效的输入是随机的。
在你的 CLAUDE.md 中添加以下内容：
路由、重试逻辑、基于状态的分支和阈值决策属于代码，而不是模型调用。如果一个决策的输出是二元的或遵循固定规则，请在代码中编写该规则。
规则 6 — 严格的 Token 预算，没有例外
每个 Agent 循环都有可能失控。Claude 不会自行停止一个 90 分钟的调试会话。它会不断迭代，因为迭代是它被要求做的事情。Token 预算是强制执行硬性停止的唯一机制。
具体事件：一个调试会话在同一段 8KB 的错误信息上循环了 90 分钟。到最后，Claude 正在建议它两小时前已经尝试过并放弃的修复方案。上下文已经满到它无法追踪自己的推理。
添加以下内容：
每个 Agent 会话都有硬性的 Token 预算。如果在没有验证解决方案的情况下达到预算，请停止，将发现总结到一个文件中，然后退出。不要超出预算继续运行。
规则 7 — 一个 Agent，一个目录
当两个 Agent 同时触及同一个目录时，你会得到静默的状态损坏。一个 Agent 在写入文件时，另一个正在读取它。结果是两个 Agent 都没有预料到且没有注意到的数据。
使用 git worktrees。在生成第二个 Agent 之前，运行 git worktree add ../agent-2-branch feature-branch。每个 Agent 获得自己独立的、指向自己分支的工作目录。Agent 之间绝不共享文件系统。
添加以下内容：
并行运行的 Agent 工作在独立的 git worktrees 中。没有两个 Agent 同时触及同一个目录。每个 Agent 拥有自己的分支。
规则 8 — 在多步骤工作中编写检查点文件
任何超过三个步骤的任务都需要一个检查点文件。Claude 在每一步之后写入文件，记录完成的内容、发现的内容以及下一步要做什么。如果会话在第 4 步死亡或中断，下一个会话读取检查点并从第 4 步继续。没有检查点，每次重启都会回到第 1 步。
在开始任何多步骤任务之前，在你的工作目录中创建一个名为 PROGRESS.md 的文件。在你的 CLAUDE.md 中告诉 Claude：
对于超过三个步骤的任务，请在每一步之后写入一个 PROGRESS.md 文件。包括：做了什么、发现了什么、下一步是什么、有什么阻塞。如果会话在完成前结束，下一个会话首先读取 PROGRESS.md，并从停止的地方继续。
规则 9 — 要么大声失败，要么根本不失败
Claude 有很强的倾向表现出成功。它会通过一个实际上并没有测试你所关心内容的测试。它会完成一个迁移，同时悄悄跳过出错的文件。它会在一个完成了 80% 的任务上报告“完成”。
规则：如果成功标准无法验证，则任务未完成。如果某一步失败，在继续之前停止并报告具体失败信息。不要掩盖错误。
添加以下内容：
永远不要在一个失败的步骤之后继续。如果一个测试通过了但没有覆盖实际行为，请说明。如果一个迁移跳过了文件，列出跳过的文件并停止。成功意味着可验证，而不是报告。
规则 10 — 技能描述必须唯一
技能是通过描述匹配来加载的。如果两个技能有重叠的描述，调度器会随意选择一个。加载了错误的技能，任务在错误的指令上运行，并且你永远不会看到错误，因为没有抛出错误。
用不能与任何其他技能匹配的语言来命名每个技能的工作。“数据库查询助手”和“数据库迁移助手”会产生冲突。“对生产数据库执行只读 SQL 查询”和“运行并验证带有回滚功能的模式迁移脚本”则不会。
添加以下内容：
每个技能描述必须唯一标识其工作。不应有两个技能的描述可以适用于同一个任务。如果两个技能听起来相似，在部署之前需要重命名其中一个。
规则 11 — 将研究者与写作者分开
上下文污染是真实存在的。当 Claude 在同一个会话中进行研究和写作时，研究噪音会降低写作质量。它引入旁支，对不需要限定的结论进行限定，并失去了如果重新开始时本应拥有的清晰论证线索。
对于任何需要读取超过五个文件或查询超过两个来源的任务，生成一个研究子 Agent。获取一份结构化的报告。然后以该报告作为唯一上下文，开启一个干净的会话用于写作或实现。
添加以下内容：
研究和实现是独立的会话。研究者子 Agent 读取文件、运行查询，并返回结构化的摘要。实现会话以该摘要作为唯一输入，从零开始。永远不要将研究和写作合并到一个会话中。
规则 12 — Hook 也需要预算
Hook 在每次工具调用时触发。一个在每次文件写入时运行 Linter、格式化器、日志写入器和安全扫描的 Hook，相当于每次工具调用运行四个进程。在一个有 200 次工具调用的会话中，那就是在后台运行 800 个进程，其中大多数是冗余的，都在消耗 Token。
你添加的每个 Hook 都需要一个范围条件：仅在对特定目录的文件写入时运行，仅在触及特定文件扩展名时运行，仅在会话结束后运行而不是每次工具调用后运行。没有范围条件的 Hook 会悄悄降低会话性能。
添加以下内容：
每个 Hook 都有一个明确的范围条件。没有 Hook 无条件地在每次工具调用时运行。将日志批量记录到会话结束。仅对更改过的文件运行 Linter。仅对测试目录之外的文件运行安全检查。
完整的 12 条 CLAUDE.md — 粘贴这个
将这个文件复制到你的仓库根目录。填写标记为括号的章节。整个文件保持在 100 行以内，这将使合规率保持在 80% 以上。
CLAUDE.md
项目
[一句话：这个代码库是做什么的，使用什么技术栈]
行为规则
先思考再编码
在编写代码前说明你的假设。暴露权衡。在猜测影响架构或数据的任何事情之前先询问。当存在更简单的方案时，要提出反对意见。
简单优先
编写解决问题所需的最少代码。没有推测性的功能。没有为只使用一次的代码进行抽象。如果一位资深工程师会认为它过于复杂，那就简化它。
外科手术式修改
只触碰任务所要求的部分。不要改进相邻的代码、格式、注释或命名（只要不是任务要求）。精确匹配现有代码风格。
目标驱动执行
在开始前定义成功的样子。持续循环直到这个定义被满足和验证。不要要求分步说明。自己找出路径。
确定性决策不使用模型调用
路由、重试逻辑、基于状态的分支和阈值决策属于代码，而不是 LLM 调用。如果一个规则可以被编写成代码，就编写它。
硬性 Token 预算
每个会话都有一个硬性 Token 限制：[设置你的数字，例如 50,000 Token]。如果在没有验证解决方案的情况下达到限制，将发现写入一个文件并停止。不要超出预算继续运行。
一个 Agent，一个目录
并行运行的 Agent 工作在独立的 git worktrees 中。没有两个 Agent 共享一个目录。如果你需要第二个 Agent，运行：git worktree add ../agent-2 [分支名]
多步骤工作检查点
对于任何超过三个步骤的任务，在工作目录中创建 PROGRESS.md。在每一步之后写入：做了什么、发现了什么、下一步是什么、有什么阻塞。如果会话在完成前结束，下一个会话首先读取 PROGRESS.md。
大声失败
如果某一步失败，在继续之前停止并报告具体失败信息。如果一个测试通过了但没有覆盖实际行为，请说明。成功意味着可验证，而不是报告。
唯一的技能描述
每个技能恰好覆盖一个工作。其描述不能适用于项目中的任何其他技能。如果两个技能在描述上重叠，在部署之前重命名。
研究和实现是独立的会话
对于任何需要读取超过五个文件或查询超过两个来源的任务，使用子 Agent。获取结构化的报告。然后以该报告作为唯一输入，开启一个干净的会话用于实现。
仅限有范围的 Hook
每个 Hook 都有一个明确的条件：文件扩展名、目录路径或会话事件。没有 Hook 无条件地在每次工具调用时运行。尽可能将日志批量记录到会话结束。
不要触碰的内容
[列出 Claude 永远不应修改的目录或文件：例如 /secrets、/migrations/archive、/prod-config]
成功标准默认值
当不确定任务是否完成时：测试是否通过？构建是否成功？输出是否可由 Claude 自身判断以外的其他东西验证？如果以上任何一点是否定的，则任务未完成。
原始模板悄悄失效的四个地方
即使只使用最初的四条规则，也有四个特定条件会导致模板产生错误行为而不通知你。
第一：长时间会话累积上下文。Karpathy 的目标驱动执行规则告诉 Claude 循环直到验证。在长时间的会话中，随着上下文填满，“已验证”变得模糊。Claude 开始根据它对自己应该做什么的退化模型进行验证。修复方法是规则 6（Token 预算），强制硬性停止。
第二：多 Agent 设置。外科手术式修改规则告诉每个 Agent 只触碰必须的部分。但是当有两个 Agent 且没有目录所有权规则时，“必须的部分”会重叠。规则 7（一个 Agent，一个目录）是缺失的部分。
第三：具有相似工作的并行技能。原始模板中没有关于技能的内容。规则 10（唯一的技能描述）堵住了调度器的歧义空白。
第四：会话在任务中途结束。目标驱动执行假设会话运行到完成。它没有说明如果会话在第 4 步（共 8 步）死亡该怎么办。规则 8（检查点文件）为下一个会话提供了一个起点。
这些都不是原始规则中的错误。它们是原始规则没有被编写来覆盖的空白。
解释 GitHub 星标的那个数字
12 万开发者为一个 65 行的文本文件点了星标。没有代码。没有库。没有框架。一个文件，四条规则。
解释这个的数字是：在没有 CLAUDE.md 的无监督 Claude Code 会话中，错误率为 41%。使用最初的四条规则后为 11%。使用完整的十二条规则后为 3%。
错误率降低 38 个百分点不是边际改进。对于任何在生产环境中运行 Claude Code 的团队来说，这是你可以信任 Agent 在夜间运行而无需盯着的区别，与必须时刻照看它之间的区别。
这篇文章末尾的文件只需五分钟即可粘贴并填写。你完成后的第一次会话会感觉不同。不是因为模型变了。而是因为模型终于知道你的世界是如何运作的了。
今晚就把这 12 条规则加入书签并粘贴到你的 CLAUDE.md 中。
如果觉得有用，请转发。
