一份据称是 Andrej Karpathy 实际使用的 CLAUDE.md 正在开发者社区流传。
文件开头第一句是这么写的：
「这些不是建议。这些是规则。遵守它们，你产出的代码就不需要被重写。忽视它们，你产出的代码也许看起来很厉害，但会在生产环境中出问题。」
语气像技术债见得太多的老前辈在教训新人，但这份文档不是写给人类新人看的，是写给 Claude Code 看的。
CLAUD.md 是 Anthropic 为 Claude Code（以及集成 Claude 的编辑器）设计的项目级说明文件。放在项目根目录，Claude 会在工作时自动读取。你告诉它"项目用 React，用 fetch 不用 axios，prefer 函数组件"，它就记住了。
这份被归到 Karpathy 名下的版本在网上疯传，部分原因是他的名气，但主要原因是：它做了一件很多开发者隐约感觉到但没系统表达过的事——把 LLM 在代码生成上的系统性缺陷，做成了诊断手册和对应的流程治理方案。
一、LLM 编程的最大问题：它不把自己当团队一员
大多数开发者每天都在和 AI 结对编程，但真正让他们头疼的，不是 AI 写不出代码，而是 AI 写出的代码总是"不太对"。
语法没错。逻辑没错。但放在项目里，怎么看怎么不对劲。
Karpathy（或者说这份文档的背后提炼者）精准地描述了这种不对劲的来源：当 LLM 写代码时，它做的其实是模式匹配——从训练数据里找到最接近当前请求的代码片段，然后生成。它没有先读当前项目的代码库。
这是根本性的。如果人类开发者接手一个项目，第一件事就是读代码、看文件结构、理解既有模式。LLM 不做这件事。它的"一次推理"里没有"先扫描代码库"这个步骤。
所以你会看到以下症状：一个全部用 fetch 的代码库里，AI 引入了 axios。一水 snake_case 的项目里，新加的变量用了 camelCase。没有装饰器模式的项目里，它给你加了一个装饰器。原因是它的训练数据里大量包含这些模式，当前输入触发了那个模式。
文档的第一条规则——「在写任何代码之前，先阅读你即将修改的文件」——就是针对这个根因。不是教 LLM 怎么读代码，而是强制它在写入之前把"代码库上下文加载"作为第一步。
二、文档里的所有规则，其实只针对 LLM 的五种失败模式
整个文档如果只看表面，是一堆"怎么做"的指令，覆盖了从阅读代码到写 commit message 的方方面面。但这堆指令背后其实是在针对 LLM 的五种系统性失败模式——
失败一：不读代码库就生成（Context Blindness）
症状：代码语法正确但风格不匹配，引入不必要的依赖，复制了项目里不存在的模式。
对应规则：写之前先读。检查 import，检查测试文件，检查已有模式。
失败二：不做决策仅做猜测（Invisible Decision Making）
症状：用户说"加认证"，LLM 选一种方案默默实现。用户收到代码才发现不是自己想要的。
对应规则：说清楚假设，说清楚取舍，不默默替人决策。
失败三：过度设计（Premature Abstraction）
症状：只发一种邮件却写 EmailService + 策略模式。只用一个接口却做抽象基类。
对应规则：保持简单。先写最少代码，真正需要抽象时再抽象。
失败四：盲目验证（Confirmation Bias）
症状：看到错误就根据错误类型生成修复方案，不读错误信息。改了三处但不知道哪处修好了 bug。
对应规则：先复现。一次只改一件事。读 stack trace。先写测试。
失败五：知识幻觉（Knowledge Hallucination）
症状：用了一个不存在的 API、两个版本前就被移除的参数、幻想出来的库特性。
对应规则：不确定就说出来。查文档。看实际源码。
这五种失败模式不是随机发生的。它们是 LLM 的架构特征在编程场景中的具体表现——上下文有限、推理无回溯、置信度与实际准确度不关联。CLAUDE.md 不是魔法，是承认这些限制之后的流程补偿。
三、框架：从「代码生成」到「代码开发」的迁移
读完整份文档，最值得提炼的并不是任何一条具体规则。而是它的隐含前提：
目前的 LLM 缺的不是代码生成能力，而是"作为团队成员参与开发"的意识。
把这套规则抽象为一个框架，它其实是三个阶段：
第一阶段：读代码（了解项目上下文、模式、约束）
→ 第二阶段：做决策（明确假设、需求、取舍，先计划后执行）
→ 第三阶段：写代码（最小改动，验证正确性，沟通清楚）
大多数开发者用 LLM 时，直接进入第三阶段——写。结果就是反复发生第一阶段的失败：代码写完了，然后发现用错了库、风格不对、项目里早有更好的方案。
CLAUDE.md 想要做到的事，本质上就是把"读→想→写"这个人类工程师已经内化的流程，变成显式的、可执行的步骤，让 LLM 在每次生成代码前都跑一遍。
有社区开发者基于 Karpathy 的公开吐槽整理了一个 github 项目《andrej-karpathy-skills》，测试效果是将 Claude 的代码错误率从 41% 降到了 11%。这不是幻觉——当 LLM 先读代码库再写代码，坏代码生成率就是会显著下降。
四、这个框架的推演
同样的分析框架也适用于 Claude Code 之外的其他工具：
Cursor Tab 模式 vs Chat 模式——Tab 模式在文件内补全时，上下文就是当前文件，所以更擅长"风格一致"的补全。Chat 模式可以跨文件，但如果没有显式要求它先读代码库，它就容易跑偏。
Copilot CLI 的模式问题和代码质量问题——Copilot CLI 最近在内部替代 Claude Code，很大程度上不是因为能力不够，而是因为多轮对话下它容易偏离项目风格。如果 Copilot CLI 有一个类似的"项目级约束文件"，很多 token 浪费可以避免。
为什么大神们都在写自己的 CLAUDE.md——不是因为他们比普通人更懂怎么"调教"AI，而是因为他们更清楚项目的代码风格是一个沉淀了团队习惯和社会约定的产物，不是"正确代码"能概括的。他们在把这种隐性知识显式化。
一旦你理解了"读→想→写"这个框架，你就会意识到：所谓"AI 辅助编程"的天花板，从来不是 LLM 能写多复杂的代码，而是 LLM 能不能把自己当做代码库的一部分来思考。CLAUDE.md 就是帮助它做到这一点的桥梁。
五、落到行动
如果你在用 Claude Code 写代码 → 花 30 分钟为你的项目写一个 CLAUDE.md。不用抄 Karpathy 的全文，把它当清单检查：你的项目用什么库用什么风格有什么约定。写完之后你一定会发现它的"读代码"意愿明显提升。
如果你在用其他 AI 编程工具 → 检查它有没有类似的"项目级约束文件"机制。如果没有，可以尝试在每次对话的开头手动加上一句「先读一遍项目根目录和最近的几个源文件，告诉我这个项目用了什么库和风格，然后我们再开始写代码」。
如果你是独立开发者 → 建议把 CLAUDE.md 做成团队 onboarding 文档的一部分。它解决的问题——项目风格、约定、技术栈偏好——本来应该是 README 或贡献指南的一部分，但没人读。AI 会读。所以把给 AI 看的那份写好，实际上等于强迫你自己把隐形知识写下来。
最后一件小事：那份原文档里有句话值得反复读——
"目前的失败模式是：LLM 生成了一段『正确』的代码，但它和所在代码库完全格格不入。它可以运行，但看起来像是另一个人写的，因为确实是另一个实体写的。于是，人类开发者要么必须把它重写成符合项目风格的样子，要么永远忍受代码库内部的不一致。这两种结果都很糟糕。"
当工具能写出 100% 正确的代码，但让代码库的可维护性下降 30%，它到底是在帮你还是在害你？CLAUDE.md 的核心价值就是把这个问题从"会后知后觉"推到了"事前规划"。这不只是给 AI 看的规则，这是给整个 AI 辅助编程范式的一个操作说明书。
来源：36氪《大神Karpathy用Claude的方式，原来是这样的？》/(原文出自机器之心) / GitHub multica-ai/andrej-karpathy-skills