learnNote

主题

📺 深度解读 Karpathy 的 AI 编程准则 ​

一份只有几十行的 CLAUDE.md 文件，凭什么在 GitHub 拿到 16k+ Stars（撰写本笔记时已超 84k）？

一、基本信息 ​

项目内容
视频标题一个Markdown文件凭什么拿到16k Stars？深度解读 Karpathy 的 AI 编程准则
UP 主探索未至之境
平台B站
时长7:43
发布时间2026-04-14
播放量91,789
点赞 / 收藏 / 评论2,225 / 6,945 / 311
视频链接https://www.bilibili.com/video/BV19gQhBqENu/
关联仓库https://github.com/forrestchang/andrej-karpathy-skills
Karpathy 原推https://x.com/karpathy/status/2015883857489522876

二、内容概要 ​

视频围绕一个名为 andrej-karpathy-skills 的 GitHub 项目展开。该项目核心其实只有一个 CLAUDE.md 文件，但凭借精炼的 4 条原则迅速冲上 16k+ Stars。

故事的起点是 Andrej Karpathy（OpenAI 创始成员、特斯拉前 AI 总监） 在 X 上发的一条推文，吐槽了当下 LLM 写代码的三大顽疾，获得 763 万次浏览。开发者 forrestchang 把这些吐槽落地为 4 条可执行的行为准则，写进 CLAUDE.md，让 Claude Code 在每次会话中都自动遵循。

视频深度解读了：

  1. Karpathy 指出的 3 个致命问题；
  2. 与之对应的 4 条准则及其设计思想；
  3. 为什么"成功标准（success criteria）"比"指令（imperative）"更适合 LLM。

三、Karpathy 指出的 3 个致命问题 ​

原文（有删减）：

  1. 盲目假设、不澄清、不反推 "模型替你做错误假设，并径直执行——它们不管理自己的困惑，不寻求澄清，不暴露不一致，不展示权衡，该反推的时候也不反推。"

  2. 过度工程化、抽象膨胀 "它们非常喜欢把代码和 API 复杂化，让抽象变臃肿，从不清理死代码……100 行能解决的事，能给你写出 1000 行的臃肿构造。"

  3. 副作用式破坏 "即使与任务无关，它们有时也会修改或删除自己并不充分理解的注释与代码，作为副作用。"

四、四大核心准则（详细整理） ​

准则解决的问题
1. Think Before Coding（先想再写）错误假设、隐藏的困惑、未呈现的权衡
2. Simplicity First（简洁至上）过度工程化、臃肿抽象
3. Surgical Changes（外科手术式修改）越界编辑、误碰不该碰的代码
4. Goal-Driven Execution（目标驱动执行）通过"先写测试、再写代码"提供可验证的成功标准

准则 1 · Think Before Coding（先想再写） ​

不要假设。不要隐藏困惑。把权衡摆上台面。

实施要点：

  • 显式声明假设——不确定就问，不要猜；
  • 存在多种解释时全部列出——不要静默地选一个；
  • 必要时反推用户——如果有更简单的做法，就要说出来；
  • 困惑时停下——指出哪里不清楚，请求澄清。

准则 2 · Simplicity First（简洁至上） ​

解决问题所需的最少代码量。不要做任何投机性扩展。

实施要点：

  • 不实现用户没要求的功能；
  • 不为只用一次的代码做抽象；
  • 不主动加"灵活性"或"可配置性"；
  • 不为不可能发生的场景写错误处理；
  • 200 行能压到 50 行就重写。

自检方法： 一个资深工程师看了会不会觉得"过度复杂"？如果会，就简化。

准则 3 · Surgical Changes（外科手术式修改）(精准修改) ​

只动你必须动的，只清理你自己造成的烂摊子。

编辑既有代码时：

  • 不顺手"改进"旁边的代码、注释或格式；
  • 不重构没坏的东西；
  • 与既有风格保持一致，即使你觉得有更好的写法；
  • 看到无关的死代码——提一嘴，但别删。

当你的修改产生了"孤儿"时：

  • 移除因你的改动而变得没用的 import / 变量 / 函数；
  • 但不要顺手删掉"原本就没人用的"死代码，除非用户要求。

自检方法： 每一行被修改的代码，都应能直接追溯到用户的需求。

准则 4 · Goal-Driven Execution（目标驱动执行） ​

定义成功标准。循环直到验证通过。

把命令式任务转成可验证目标：

不要写成转化为
"加个校验""为非法输入写测试，然后让它通过"
"修个 bug""写一个能复现该 bug 的测试，然后让它通过"
"重构 X""保证重构前后所有测试都能通过"

多步任务，用简短计划串起来：

text
1. [步骤] → verify: [检查]
2. [步骤] → verify: [检查]
3. [步骤] → verify: [检查]

核心洞察（来自 Karpathy）：

"LLM 极其擅长循环执行直到达成特定目标……不要告诉它做什么，给它成功标准，然后看着它自己跑就行。"

强成功标准能让 LLM 独立循环，弱成功标准（"让它能跑起来"）会逼你不停澄清。

五、原作者 CLAUDE.md 全文（精简版） ​

markdown
# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes.

## 1. Think Before Coding
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

## 3. Surgical Changes
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style.
- Mention unrelated dead code, don't delete it.

## 4. Goal-Driven Execution
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

中文版 ​

markdown
# CLAUDE.md

减少 LLM 常见编码错误的行为准则。

## 1. 先想再写
- 显式声明你的假设。不确定就问，不要猜。
- 如果存在多种解释，全部列出——不要默默选一个。
- 如果有更简单的做法，说出来。该反推就反推。
- 如果搞不清楚，停下来。说清哪里不明白，然后问。

## 2. 简洁至上
- 不实现用户没要求的功能。
- 不为只用一次的代码做抽象。
- 不主动加"灵活性"或"可配置性"。
- 不为不可能发生的场景写错误处理。
- 200 行能压到 50 行就重写。

## 3. 外科手术式修改
- 不顺手"改进"旁边的代码、注释或格式。
- 不重构没坏的东西。
- 与既有风格保持一致。
- 看到无关的死代码——提一嘴，但别删。

## 4. 目标驱动执行
- "加个校验" → "为非法输入写测试，然后让它通过"
- "修个 bug" → "写一个能复现该 bug 的测试，然后让它通过"
- "重构 X" → "保证重构前后所有测试都能通过"

六、如何接入到自己的项目 ​

方式 A · Claude Code 插件（推荐） ​

bash
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

方式 B · 直接放进 CLAUDE.md（按项目） ​

新项目：

bash
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

已有项目（追加）：

bash
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Cursor 用户 ​

仓库内置了 .cursor/rules/karpathy-guidelines.mdc，把项目 clone 下来或把规则文件复制到自己的 .cursor/rules/ 即可。

七、判断准则是否生效的 4 个信号 ​

  • ✅ Diff 中没有多余改动——只有用户要求的改动；
  • ✅ 更少的"推倒重来"——一次就写得简洁；
  • ✅ 澄清问题出现在实现之前——而不是出错之后；
  • ✅ PR 干净、最小——没有顺手 refactor、没有"顺便改改"。

八、精选评论与延伸思考 ​

评论区争议较大，正反观点都很有营养，整理如下。

🌟 高质量正向观点 ​

  • @wap（109 赞）：

    Karpathy 那句"给 LLM 成功标准而不是告诉它做什么"是 AI 编程的精髓——CLAUDE.md 把它落地成了可执行的行为准则。

  • @小高运气不太差（75 赞）：

    现在的 vibe coding 本质上仍是 Junior~Mid Level，最有价值的还是你脑子里的东西。Senior 能把问题拆得很具体，AI 才能给出符合预期的输出；如果使用者编程基础不如 AI，就会被它牵着鼻子走，看似可用但隐患重重。 举例：后端开发者都知道用 batch query，AI 可能突然抽风循环调用 findById——没经验的人发现不了。

  • @啊脑袋没惹（162 赞）：

    推荐去看 Anthropic 官方文档，根据这四点精简自己的 CLAUDE.md 即可。

  • @乔治 jojo（3 赞）：

    我的工作流：先磨开发框架与任务清单 → 审核 → 每次开一个小会话改一小块（很像微服务）→ 列 bug 清单让它复现修复。把 AI 当产品经理 / 测试 / 最后才是开发。

  • @写作笨蛋读作 9（2 赞）：

    我都是先用 plan 模式让它把方案说完，看完再切到 agent 跑。

⚠️ 反向 / 谨慎观点 ​

  • @大雨弟：

    这几十行放 CLAUDE.md 真的没必要，这个文件应该放 Claude 不知道的东西，以及项目踩过的坑。比如 Maven 私服配置，加一行就能解决编译问题。

  • @monohooho（15 赞）：

    CLAUDE.md 真正应该存的是注意事项的索引，CC 本身就有 system prompt，写这种泛化内容会浪费 token，甚至打乱缓存。

  • @越阅越悦 42：

    这种内容现在大概率已经写在系统提示里了，不需要再强调。

  • @Setruth（74 赞） / @InfiniXZ（122 赞）：

    GitHub Star 已经成为 AI 时代的营销指标，热门项目要冷静看待。

  • @左右相离（18 赞）：

    怕就怕模型根本不看，或者看了根本不执行。

  • @绝无尘想：

    加了，但是 CC 不按 CLAUDE.md 跑，并没什么用。

📌 实践派建议（对小白尤其重要） ​

  1. 先读官方文档，不要直接 copy 这 4 条原则当教条；
  2. 结合项目特性编写专属规则（如代码规范、目录结构、踩过的坑、私有依赖配置等）；
  3. 多用 plan 模式预览方案，不要直接 agent 跑；
  4. 把 AI 当成"工具"而不是"开发者"——你才是 owner；
  5. 维持自己写代码、读代码的能力，避免被 AI 带偏。

九、一句话总结 ​

不要告诉 LLM "怎么做"，要告诉它"什么算成功"。 Karpathy 的 4 条准则——先想 → 简洁 → 外科手术式改 → 目标驱动——本质上是把 LLM 从"听话的实习生"调教成"会反推、会自检、会循环验证的初级工程师"。 但准则只是脚手架，真正决定 AI 编程上限的，永远是使用者本身的工程素养。

十、延伸阅读 ​

最后更新: