Karpathy's CLAUDE.md：个人生产力到团队标准的 4 个缺口与 3 层修复

一句话结论

Karpathy 的 CLAUDE.md 解决了 1 个工程师管理 1 个 agent 的问题，但工程团队需要额外的 4 层机制（入职、版本控制、执行、冲突解决）才能将个人纪律文件转化为团队标准。

适用场景

• 适合的任务：

  • 理解 CLAUDE.md 从个人到团队的扩展路径

  • 设计工程团队的 CLAUDE.md 标准

  • 解决多工程师使用不同 CLAUDE.md 导致的漂移问题

  • 处理共享代码库中的配置冲突

• 不适合的任务：

  • 个人开发者的简单项目（直接使用 Karpathy 版本即可）

  • 不需要团队协作的场景

• 适用的模型版本：Claude Opus 4.7

• 适用的客户端、Agent 或 API：Claude Code CLI

• 推荐的推理档位和参数：N/A（方法论指导，不涉及具体参数）

可直接使用的内容

Karpathy 的原始 CLAUDE.md 解决了什么

2026 年 1 月 26 日，Karpathy 在 X 上发布了对 AI 编码代理的挫败感。第二天，开发者 Forrest Chang 将这些挫败感编码为 65 行的 CLAUDE.md，推送到 GitHub（multica-ai/andrej-karpathy-skills）。该文件成为 Claude Code 的行为标准。

Karpathy 命名了 3 个失败模式：

1. 编码代理做出错误假设并运行，不检查

2. 过度复杂化代码，膨胀抽象，发送 1000 行实现而 100 行就够

3. 更改或删除他们不完全理解的代码，即使与任务无关

Chang 的文件将每个挫败转化为命名原则：

• Think Before Coding：明确陈述假设，困惑时停止，不猜测

• Simplicity First：编写解决 stated 问题的最小代码，不添加未请求的抽象

• Surgical Changes：不触及与请求无关的代码，即使相邻代码看起来可改进

• Goal-Driven Execution：在开始前将模糊任务转换为可验证的成功标准

工作流反转：

• 2025 年 11 月：80% 手动编码，20% 通过代理

• 2026 年 1 月底：20% 审查和修饰，80% 由代理生产

• 8 周内完成反转

团队级别的 4 个组织失败模式

场景 1：漂移问题

3 个工程师，同一代码库。每人在 6 周前复制了 CLAUDE.md。每人为自己的偏好修改了它。

• 工程师 A 放宽了 Surgical Changes，因为她正在进行大规模迁移

• 工程师 B 收紧了 Goal-Driven Execution，因为他的团队曾因代理发送无测试功能而受伤

• 工程师 C 从未修改文件，但不知道其他人做了

文件现在说不同的话。代理为每个工程师表现不同。没人知道。不存在检测漂移的机制。

后果在代码审查时出现，审查者注意到工程师 A 的最近 PR 触及的文件比她的工单建议的要多，但无法追踪原因。

场景 2：共享服务问题

工程师 A 的 CLAUDE.md 告诉代理可以清理孤立导入作为任务的一部分。工程师 A 的任务触及 services/shared/auth.py 中的工具。工程师 B 的服务依赖于该工具，工程师 B 的代理在不同的 CLAUDE.md 下操作，围绕现有导入结构构建。

1 个工程师的"清理你自己的混乱"成为另一个工程师周一早上的集成测试失败。

代理完全按照他们的文件告诉他们的那样做。文件告诉他们不同的事情。共享代码付出了代价。

场景 3：入职问题

新工程师周二加入。周三获得仓库访问权限。周四复制 CLAUDE.md。没人解释团队对文件的特定添加意味着什么，为什么文件与公共 Karpathy 版本不同，或者当代理做了文件未涵盖的事情时该怎么做。

标准存在。标准的传递不存在。

场景 4：执行天花板

公共仓库中的 PR #54 为所有 4 个原则提出咨询 hooks。PR 自己的设计哲学部分将 hooks 描述为咨询性的，在 stderr 上退出警告而不阻止，并在收到畸形输入时失败打开。

纯 Markdown 文件中的纯指令是建议。建议不是标准。

仓库最活跃的贡献者正在围绕限制构建。编写的原则在工程组织最重要的时刻失败：代理在无人看管的情况下大规模运行。

工程组织真正需要的 4 个缺口

缺口 1：入职

问题：新工程师不知道团队对文件的特定添加意味着什么。

解决方案：

• 创建团队特定的 CLAUDE.md 入职文档

• 解释每个原则的团队特定解释

• 提供当代理做文件未涵盖的事情时的升级路径

缺口 2：版本控制

问题：每个工程师修改自己的副本，导致漂移。

解决方案：

• 将 CLAUDE.md 作为团队标准存储在版本控制中

• 使用拉取请求进行更改

• 为个人偏好提供覆盖机制（如 .claude.local.md）

缺口 3：执行

问题：纯指令是建议，不是标准。

解决方案：

• 实现执行 hooks（不仅是咨询性的）

• 在 CI/CD 中验证合规性

• 为无人看管的情况提供失败安全机制

缺口 4：冲突解决

问题：当不同工程师的 CLAUDE.md 冲突时，没有解决机制。

解决方案：

• 定义共享代码的权威来源

• 为共享服务创建团队级别的 CLAUDE.md

• 建立冲突解决流程

正确设计的 CLAUDE.md 工程团队标准看起来像什么

三层结构：

1. 核心原则（不可变）：

   • 从 Karpathy 的 4 个原则开始

   • 通过拉取请求更改

   • 所有工程师必须遵守

2. 团队特定（受控可变）：

   • 团队对原则的解释

   • 通过拉取请求更改

   • 团队内所有工程师必须遵守

3. 个人偏好（本地覆盖）：

   • 存储在 .claude.local.md

   • 不提交到版本控制

   • 不能覆盖核心或团队特定原则

执行机制：

• 使用 hooks 验证合规性

• 在 CI/CD 中检查

• 为无人看管的情况提供失败安全

冲突解决：

• 共享代码的权威来源

• 团队级别的 CLAUDE.md 用于共享服务

• 明确的升级路径

测试/工作流步骤

1. 评估当前状态：

   • 检查团队中每个工程师的 CLAUDE.md

   • 识别漂移和冲突

2. 建立三层结构：

   • 创建核心原则（从 Karpathy 的 4 个原则开始）

   • 创建团队特定原则

   • 为个人偏好提供覆盖机制

3. 实现版本控制：

   • 将 CLAUDE.md 存储在版本控制中

   • 使用拉取请求进行更改

   • 为个人覆盖使用 .claude.local.md

4. 实现执行：

   • 使用 hooks 验证合规性

   • 在 CI/CD 中检查

   • 为无人看管的情况提供失败安全

5. 建立入职流程：

   • 创建团队特定的入职文档

   • 解释每个原则的团队特定解释

   • 提供升级路径

6. 建立冲突解决：

   • 定义共享代码的权威来源

   • 为共享服务创建团队级别的 CLAUDE.md

   • 建立冲突解决流程

7. 定期审查：

   • 每月审查 CLAUDE.md 的更改

   • 识别和解决漂移

   • 更新入职文档

原始证据与数据

• Karpathy 的 CLAUDE.md 在 GitHub 上有约 184k 星和 97 个开放拉取请求（截至 2026 年 6 月 28 日）

• 该文件实际上不是由 Karpathy 编写的，而是由 Forrest Chang 于 2026 年 1 月 27 日编码

• Karpathy 的工作流在 8 周内从 80% 手动编码反转为 80% 代理生产

• 公共仓库有 138 个拉取请求，其中 97 个开放

• 核心原则自 1 月 27 日以来未改变，尽管有 5 个月的社区扩展提案

适用边界

• 该分析针对工程团队，不适用于个人开发者

• 三层结构需要根据团队规模和需求调整

• 执行 hooks 可能需要额外的开发和测试

• 冲突解决流程需要根据团队文化定制

来源摘录或观察（仅做合规短引）

文章核心观点："The file was designed for 1 engineer managing 1 agent in 1 repo. It is excellent at that. Engineering organizations are a different problem."

"Many developers copied the file into their repo and moved on. That is a personal productivity move. It is not a team standard, and the difference matters more than the star count suggests."