一个 70 行的文件，6 万 Star：Karpathy 的 AI 编程守则

[mqyqingfeng]

你好，我是冴羽。

一个只有 70 行的文件，在 GitHub 上已经有了 6 万 Star。

不是框架，不是库，不是应用。就是一个配置文件——CLAUDE.md。

你可能觉得这很离谱。一个文本文件能有什么用？

但如果你用过 Claude Code、Cursor、Copilot 这些 AI 编程助手，你就会懂：

AI 写代码确实快，但它经常把事情搞砸。

你让它修个 bug，它重写半个文件。你让它加个功能，它给你造一整套抽象层。你让它帮个忙，它自信满满地用错误的假设往前冲……

Reddit 上有个被广泛认同的说法：AI 就像一个自信的初级开发者。 聪明、快速、但容易犯低级错误。

而这个 CLAUDE.md 文件，就是给这个“初级开发者”设置的护栏。

1. 故事的起点

2026 年 1 月，OpenAI 联合创始人、前特斯拉 AI 负责人 Andrej Karpathy 发了条推特。

他没有分享工具或代码，而是列出了一堆吐槽——关于 AI 写代码时的各种毛病：

• 默默做假设，从不问清楚

• 过度设计，搞一堆用不上的抽象

• 改 A 的时候顺手“优化”B、C、D

• 从不验证自己写的代码是否真的解决了问题

每一条都是痛点。

开发者 Forrest Chang 看到后，做了件很实际的事：把这些吐槽变成了一份行为准则。

他创建了一个 GitHub 仓库 forrestchang/andrej-karpathy-skills，里面只有一个核心文件：CLAUDE.md。

不到两个月，这个仓库就成了 GitHub 上增长最快的 AI 工具类项目之一。

2. AI 编程的 4 大坑

Karpathy 总结的问题，其实可以归为四类。每一类都对应一个常见的“翻车现场”：

坑 1：默默做假设

你说“给用户数据加个导出功能”。

AI 不问格式（CSV? JSON? Excel?），不问范围（全部数据还是筛选后的？），不问权限（谁能导出？），直接开始写代码。

结果你拿到的功能，和你想要的完全不是一回事。

坑 2：过度设计

你说“写个计算折扣的函数”。

AI 给你搞出一套策略模式：抽象基类、工厂方法、配置文件……200 行代码。

但你只需要一个 10 行的函数。

坑 3：顺手“优化”

你说“修复邮箱验证的 bug”。

AI 改了 bug，顺便把单引号改成双引号，加了类型注解，重写了返回逻辑，调整了缩进……

你看 diff 的时候完全分不清哪些改动是修 bug 必须的，哪些是它“顺手”加的。

坑 4：不验证结果

你说“重构这段代码”。

AI 重构完了，信心满满地说“完成了”。

但它没跑测试，没检查是否引入新 bug，甚至没确认代码能不能编译通过。

这 4 个坑，你踩过几个？

3. 4 条原则

Forrest Chang 把 Karpathy 的观察提炼成了 4 条原则。每一条都直击一类问题：

原则	解决的问题
编码前先思考	错误假设、隐藏的困惑、缺失的权衡
简单优先	过度复杂、臃肿的抽象、投机性功能
外科手术式修改	无关的编辑、顺手改代码、风格漂移
目标驱动执行	模糊的实现、没有验证、弱成功标准

我们一条条看。

3.1. 原则 1：编码前先思考

核心： 不要假设。不要隐藏困惑。把权衡摆出来。

在写代码之前，AI 必须：

• 明确说出自己的假设。如果不确定，就问

• 如果有多种理解方式，列出来让你选

• 如果有更简单的方案，说出来

• 如果有什么不清楚的，停下来，说明白哪里困惑

举个例子：

用户说：“给用户数据加个导出功能”

❌ 错误做法： 直接开始写 CSV 导出代码

✅ 正确做法：

我需要先确认几点:
1. 导出格式:CSV、JSON 还是 Excel?
2. 数据范围:全部用户还是当前筛选结果?
3. 权限控制:是否需要管理员权限?
4. 数据量:如果用户很多,是否需要分页或异步处理?

3.2. 原则 2：简单优先

核心： 能解决问题的最少代码。不要投机性功能。

规则很严格：

• 不要加没被要求的功能

• 单次使用的代码不要搞抽象

• 不要加没被要求的“灵活性”

• 不要为不可能的场景写错误处理

• 如果 200 行能缩成 50 行，就重写

测试标准： 资深工程师会不会说这太复杂了？如果会，就简化。

举个例子：

用户说：“写个计算折扣的函数”

❌ 错误做法：

// 策略模式 + 工厂 + 配置文件,200 行代码
class DiscountStrategy { ... }
class PercentageDiscount extends DiscountStrategy { ... }
class FixedDiscount extends DiscountStrategy { ... }
class DiscountFactory { ... }

✅ 正确做法：

// 一个函数,10 行代码
function calculateDiscount(price, discountPercent) {
  return price * (1 - discountPercent / 100);
}

等真的需要多种折扣类型时，再重构。

3.3. 原则 3：外科手术式修改

核心： 只改必须改的。只清理自己弄乱的。

编辑现有代码时：

• 不要“改进”相邻的代码或格式

• 不要重构没坏的东西

• 匹配现有风格，即使你不喜欢

• 如果发现死代码，提一句——但别删

如果你的改动产生了“孤儿代码”:

• 只清理你的改动直接导致 的无用代码

• 不要顺手清理其他无关的旧代码

测试标准： 每一行改动都应该能直接追溯到用户的要求。

举个例子：

用户说：“修复空邮箱导致验证器崩溃的 bug”

❌ 错误做法：

# 修了 bug,顺便:
# - 单引号改成双引号
# - 加了类型注解
# - 加了 docstring
# - 重构了返回逻辑
# - 调整了空格

✅ 正确做法：

# 只加一行空值检查,其他代码一个字都不动
if not email:
    return False

3.4. 原则 4：目标驱动执行

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

这是 Karpathy 认为是最高杠杆的洞察：

把命令式任务转化为声明式目标。

不要说……	而是说……
“加个验证”	“写测试覆盖非法输入，然后让测试通过”
“修这个 bug”	“写个能复现 bug 的测试，然后让它通过”
“重构 X”	“确保重构前后测试都通过”

对于多步骤任务，AI 应该先说明计划：

我的计划:
1. 写测试复现 bug
2. 运行测试确认失败
3. 修复代码
4. 确认测试通过
5. 检查是否引入回归

4. 完整的 CLAUDE.md 文件

这就是完整的文件内容。不到 70 行：

# CLAUDE.md

减少常见 LLM 编码错误的行为准则。
根据需要与项目特定指令合并。

**权衡:**这些准则偏向谨慎而非速度。
对于简单任务,请自行判断。

## 1. 编码前先思考

**不要假设。不要隐藏困惑。把权衡摆出来。**

实现之前:

- 明确说出你的假设。如果不确定,就问。
- 如果存在多种理解方式,列出来。
- 如果有更简单的方案,说出来。
- 如果有什么不清楚,停下来。说明哪里困惑。

## 2. 简单优先

**能解决问题的最少代码。不要投机性功能。**

- 不要加没被要求的功能
- 单次使用的代码不要搞抽象
- 不要加没被要求的"灵活性"
- 不要为不可能的场景写错误处理
- 如果 200 行能缩成 50 行,就重写

## 3. 外科手术式修改

**只改必须改的。只清理自己弄乱的。**

- 不要"改进"相邻的代码或格式
- 不要重构没坏的东西
- 匹配现有风格,即使你不喜欢
- 如果发现死代码,提一句——但别删

## 4. 目标驱动执行

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

把任务转化为可验证的目标:

- "加个验证" → "写测试,然后让测试通过"
- "修这个 bug" → "用测试复现,然后修复"
- "重构 X" → "确保重构前后测试都通过"

就这些。

它的威力在于简洁——短到能完整放进 AI 的上下文窗口，又长到能编码关键的行为护栏。

5. 怎么用？

两种方式：

方式 A: Claude Code 插件（推荐）

这会把准则安装为 Claude Code 插件，在所有项目中生效：

# First, add the marketplace
/plugin marketplace add forrestchang/andrej-karpathy-skills

# Then install the plugin
/plugin install andrej-karpathy-skills@karpathy-skills

方式 B：单个项目的 CLAUDE.md

# 新项目
curl -o CLAUDE.md https://raw.githubusercontent.com/
  forrestchang/andrej-karpathy-skills/main/CLAUDE.md

# 现有项目(追加)
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/
  andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

6. 什么是 CLAUDE.md?

简单说：它是 AI 编程助手的“入职文档”。

每次 Claude Code 启动时，它都会读这个文件，获取持续的上下文。

就像给新员工的 onboarding 文档——只不过 AI 每次都会重新读一遍。

6.1. CLAUDE.md 最佳实践（2026）

章节	内容
项目概述	2-3 句话说明项目是干什么的
技术栈	语言、框架、关键库
架构	代码库地图（源码、组件、配置）
命令	dev、build、test、lint 命令
编码标准	命名约定、模式、风格规则
安全规则	“永远不要硬编码 API 密钥”、“不要编辑 /config”

6.2. 层级关系

项目根目录的 CLAUDE.md (项目特定规则)
    ↓ 覆盖
全局 Claude Code 插件 (通用准则)
    ↓ 覆盖
Claude 的默认行为

经验法则： 如果你在聊天中重复某个指令超过两次，就把它提升到 CLAUDE.md 里。

7. 最后

这个仓库火，不是因为它技术多牛逼。

而是因为它解决了一个所有人都在经历，但没人系统化表达的问题。

AI 编程助手确实改变了游戏规则。但它们也带来了新的问题：

• 代码写得快了，但质量参差不齐

• 实现速度快了，但理解成本高了

• 生产力提升了，但维护负担也增加了

Karpathy 的洞察 + Forrest Chang 的执行，给了我们一个实用的解决方案。

不是限制 AI，而是引导它。

这就是 2026 年的 AI 工程：不是让 AI 做所有事，而是让 AI 在正确的护栏内做正确的事。

工具就摆在那里。用不用，是你的事。

我是冴羽，10 年笔耕不辍，专注前端领域，更新了 10+ 系列、300+ 篇原创技术文章，翻译过 Svelte、Solid.js、TypeScript 文档，著有小册《Next.js 开发指南》、《Svelte 开发指南》、《Astro 实战指南》。

欢迎围观我的“网页版朋友圈“，关注我的公众号：冴羽（或搜索 yayujs），每天分享前端知识、AI 干货。