karpathy-guidelines 入门：Andrej Karpathy 推荐的大模型编程规范

难度：入门级 | 时长：约 15 分钟 | 收获：掌握 4 原则 + 能用karpathy-guidelines 规范AI编程行为

目标读者

• 正在使用 Claude Code、Cursor、Copilot 等 AI 代码助手的开发者
• 有 1-5 年开发经验，希望 AI 写出的代码更精准、少废话、不乱改
• 对 AI 编程有一定实践，正在寻找系统化的协作规范

核心依赖与环境

完整项目结构树

andrej-karpathy-skills/
├── CLAUDE.md                # 核心指南文件（4 原则精炼版，插件/文件两种方式共用）
├── README.md                # 安装与使用说明
├── EXAMPLES.md              # 大量正反实战示例
└── skills/
    └── karpathy-guidelines/  # Claude Code 插件格式（推荐安装方式）

---

1. 先理解问题：LLM 为什么会"自说自话"

Andrej Karpathy 在 2025 年底发了一条推文，直指当前大模型编程的核心问题：

"The models make wrong assumptions on their own behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

翻译过来就是：LLM 喜欢默默做假设、遇到模糊的地方不追问就开始写、代码越写越臃肿、还会顺手改掉它不理解的部分。

这个问题几乎每个深度使用 AI 编程的开发者都遇到过：你让 AI 修一个小 bug，它给你重写了半个模块；你让 AI 加一个简单函数，它引入了三层抽象。

karpathy-guidelines 就是针对这四个毛病设计的：

---

2. 安装 karpathy-guidelines

有两种安装方式，推荐第一种。

方式一：插件方式（推荐）

# 第一步：添加插件市场
/plugin marketplace add forrestchang/andrej-karpathy-skills

# 第二步：安装插件
/plugin install andrej-karpathy-skills@karpathy-skills

安装完成后，Claude Code 在任何项目中都会自动加载这 4 个原则。

方式二：直接下载 CLAUDE.md（适用于任意项目）

新项目：

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

已有项目（追加到现有 CLAUDE.md）：

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

---

3. 四原则逐条解析

原则一：Think Before Coding

核心： 不要假设，不要隐藏困惑，主动呈现权衡。

这是最违反 AI 本能的一条。AI 的训练目标是"给出一个答案"，遇到模糊的指令，它倾向于猜一个最合理的解释然后继续执行——而不是停下来问"你说的到底是哪个意思"。

正确的打开方式是这样：

# 用户说："让搜索更快一点"

# ❌ AI 的常见做法：默默加了缓存、索引、异步处理，一口气写了 200 行
@lru_cache(maxsize=1000)
async def search(query: str) -> List[Result]:
    # ... 一堆优化代码
    pass

# ✅ karpathy-guidelines 要求的做法：
"""
"让搜索更快"可以有几种理解：
1. 响应时间更快（< 100ms）：加数据库索引 + 缓存，估算 2 小时
2. 并发吞吐量更高：异步改造 + 连接池，估算 4 小时
3. 感知速度更快（UX）：渐进式加载，估算 3 小时

你指的是哪一种？
"""

遇到模糊指令，停下来问清楚，比做完之后返工要高效得多。

在代码层面，这条原则要求你：

• 明确陈述你的假设，不确定的要问
• 存在多种合理解读时，全部列出来让用户选择
• 发现更简单的方案时，主动提出来
• 遇到不清楚的地方，立刻停下来问

---

原则二：Simplicity First

核心： 只写解决当前问题所需的最少代码，不做预测性设计。

AI 有个倾向：它会把"最佳实践"一股脑塞进去，哪怕当前完全不需要。你让 AI 写一个折扣计算，它可能给你搞出一个策略模式 + 工厂模式 + 配置类的完整体系。

看一个真实对比：

用户请求："加一个折扣计算函数"

# ❌ AI 常做的：引入不必要的抽象
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Union

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        # ... 一堆代码

# 使用需要 30+ 行准备代码

# ✅ Simplicity First 的做法：
def calculate_discount(amount: float, percent: float) -> float:
    """计算折扣金额。percent 为百分比，如 10 表示 10%"""
    return amount * (percent / 100)

# 使用
discount = calculate_discount(100.0, 10.0)  # 9折

这条原则的判断标准：

• 没有人要求的功能不加
• 单次使用的代码不抽象
• 不需要"灵活性"就不预留配置
• 不可能出现错误的场景不写错误处理
• 写完代码后问自己："一个高级工程师会说这过度设计了吗？"如果会，重写

---

原则三：Surgical Changes

核心： 只改必须改的，清理自己造成的垃圾，但不碰原本就有的东西。**

AI 修 bug 的时候特别容易"顺手优化"：改了 3 行 bug，顺便把变量名改了、格式调了、注释换了。karpathy-guidelines 要求手术刀级别的精准。

一个典型场景：用户说"修复邮件为空时验证器崩溃的问题"

  def validate_user(user_data):
-     # Check email format
-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     # Basic email validation
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")
-     # Check username
-     if not user_data.get('username'):
+     # Check username  ← 原来怎么写现在就怎么写
+     if not user_data.get('username'):
          raise ValueError("Username required")
      return True

❌ AI 常见的做法（超过用户请求范围）：

# 还顺便加了：
# - 更严格的邮箱格式校验（正则表达式）
# - 用户名长度验证
# - 用户名字符验证
# - docstring
# - 改了引号风格（'' → ""）

✅ Surgical Changes 要求（只改空邮件相关的两行）：

-     if not user_data.get('email'):
+     email = user_data.get('email', '')
+     if not email or not email.strip():
          raise ValueError("Email required")
-     if '@' not in user_data['email']:
+     if '@' not in email:
          raise ValueError("Invalid email")

判断标准： 每一行改动的代码，都能追溯到用户的具体请求。

---

原则四：Goal-Driven Execution

核心： 把"做什么"翻译成"怎么验证成功了"。用成功标准替代模糊指令。

这是 Andrej Karpathy 最强调的一点："LLM 非常擅长循环执行直到达到特定目标。与其告诉它要做什么，不如给它成功标准，然后看它自己跑。"

对比一下两种指令方式：

❌ 模糊指令（AI 无所适从）：

修复登录系统的问题

✅ Goal-Driven 指令（AI 有明确方向）：

登录系统的具体问题：用户改密码后旧 session 没有失效。

计划：
1. 写测试：改密码 → 验证旧 session 被拒绝
   验证：测试失败（重现 bug）

2. 实现：改密码时清除对应用户的 session
   验证：测试通过

3. 边界情况：多设备登录、并发改密码
   验证：新增测试全部通过

4. 回归检查：现有登录相关测试全部通过
   验证：pnpm test

当前登录模块测试覆盖率：[数据]
请告诉我具体遇到的是哪个登录问题？

多步骤任务的标准格式：

1. [步骤描述] → 验证：[验证方式]
2. [步骤描述] → 验证：[验证方式]
3. [步骤描述] → 验证：[验证方式]

这样做的好处是：AI 在每个步骤完成后有明确的核对清单，不需要反复确认"这样对不对"。

---

4. 如何验证指南是否生效

安装了 karpathy-guidelines 之后，你可以通过以下几个维度来判断它是否在起作用：

看 diff 质量：

• 改动是否都是用户要求的？
• 有没有多余的"顺便优化"？
• 引号风格、注释、docstring 有没有被擅自改动？

看提问时机：

• AI 遇到模糊指令是否主动停下来问了？
• 还是直接猜了一个就开始写？

看代码复杂度：

• 新写的代码是否刚好够用？
• 有没有过度抽象或过度设计？

如果这三个维度都在改善，说明指南生效了。

---

5. 与项目既有 CLAUDE.md 合并

大多数项目已经有自己的 CLAUDE.md 了，直接覆盖会丢失原有配置。正确做法是追加而不是替换：

# 先确认现有 CLAUDE.md 内容
cat CLAUDE.md

# 然后用编辑器手动合并，或者：
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

合并后的文件结构建议：

# 项目说明（原有内容保留）

---

# karpathy-guidelines（新增内容，PS：Andrej Karpathy 推荐）

[这里粘贴 CLAUDE.md 的内容]

---

## 项目特定规范

- 使用 TypeScript strict 模式
- 所有 API 端点必须有测试
- 遵循 src/utils/errors.ts 中的错误处理模式

---

常见问题排查

Q1：插件安装后没有生效？

# 确认插件已加载
/plugin list

# 如果没有，重启 Claude Code
# 在 Claude Code 中输入 /exit 退出，然后重新进入

Q2：项目 CLAUDE.md 和插件冲突怎么办？

以项目 CLAUDE.md 为准。插件提供的是全局兜底行为，项目文件覆盖插件设置。

Q3：简单任务也被卡住，要求确认怎么办？

这是正常现象——karpathy-guidelines 对所有任务都一视同仁地要求澄清模糊指令。对于明显的简单任务（如"把变量 a 改成 b"），你可以在指令中明确加上"这是简单替换，直接做"，AI 就会跳过确认环节。

Q4：AI 不遵守 Surgical Changes，还是乱改格式怎么办？

在指令中明确限制改动范围：

把 validateEmail 函数中的空值检查改一下，只改这一处，不要动其他代码和格式。

Q5：合并 CLAUDE.md 后出现冲突，怎么解决？

手动编辑 CLAUDE.md，保留原有内容和新加入的原则，避免重复段落。如果两个地方定义了相同原则，以项目原有的具体规范为准。

Q6：对已有项目是否需要回溯应用这些原则？

不需要。karpathy-guidelines 约束的是之后的改动行为，不是让你回头重构现有代码。用它来指导新的编程交互即可。

---

扩展阅读与进阶方向

• Andrej Karpathy 原始推文 —— LLM 编程陷阱的源头观察
• forrestchang/andrej-karpathy-skills —— 本项目的 GitHub 仓库，包含完整的 EXAMPLES.md（大量正反示例值得细读）
• Claude Code 官方文档 —— 了解 CLI 的完整能力和配置选项
• OpenClaw 接入教程 —— 如果你想进一步探索 AI Agent 的本地化实践，OpenClaw 提供了更深度的工具调用能力

---

进阶方向

掌握四原则之后，你可以往以下方向继续探索：

自定义扩展： 在 CLAUDE.md 中加入项目特定的编码规范，让 AI 既有 karpathy-guidelines 的通用约束，又有项目自己的风格要求。

团队共享： 将 karpathy-guidelines 纳入团队的编码规范文档，新成员克隆项目后自动获得 AI 编程行为准则。

效果量化： 记录引入指南前后 AI 代码的返工次数、改动范围、PR 中的无关变更数，用数据验证这套方法论的实际价值。