Karpathy CLAUDE.md 规则集

来源

Andrej Karpathy（OpenAI 联合创始人、前特斯拉 AI 总监）总结了 AI 编程助手最常见的 四种系统性失败模式，Forrest Chang 将其提炼为一个 70 行的 CLAUDE.md 文件。

• GitHub 仓库: forrestchang/andrej-karpathy-skills
• Star 数: ~150,000+（GitHub 历史上最火的单文件仓库之一）
• 原始文件: CLAUDE.md（仓库根目录）

核心思想

框架式规则（“怎么做决策”）远优于禁止列表（“不要做 X”）。规则超过 ~80 行会导致上下文稀释 — Claude 对每条规则的注意力会崩溃。

完整源码

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- 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.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "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"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

安装方式

方式一：作为独立 Skill 安装

将仓库克隆到 Claude Code 的 skills 目录：

# 创建 skills 目录（如果不存在）
mkdir -p ~/.claude/skills/karpathy

# 下载 CLAUDE.md
curl -o ~/.claude/skills/karpathy/SKILL.md \
  "https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md"

# 在文件顶部添加 frontmatter 使其成为可被识别的 skill

更简单的方式是直接克隆仓库：

cd ~/.claude/skills
git clone https://github.com/forrestchang/andrej-karpathy-skills.git karpathy

注意： 仓库中的 CLAUDE.md 可能需要添加 frontmatter 头才能被 Claude Code 识别为 skill：

---
name: karpathy-rules
description: Behavioral guidelines from Karpathy to reduce common LLM coding mistakes - think before coding, simplicity first, surgical changes, goal-driven execution.
---

方式二：合并到项目的 CLAUDE.md（推荐）

将规则直接合并到项目根目录的 CLAUDE.md 中（本项目已采用此方式）：

# 手动编辑 CLAUDE.md，在文件开头加入行为准则部分

优点：

• 无需额外安装，和项目绑定
• 每次对话自动加载
• 可以根据项目特点调整（例如 Scrapy 项目已有项目架构说明在后面）

方式三：使用 Karpathy Skill 包

社区维护的 NPM 包：

# 安装到 Claude Code
npx @anthropic-ai/claude-code skills add forrestchang/andrej-karpathy-skills

或者用 Claude Code 的 plugin marketplace（如果可用）：

/claude skills install github.com/forrestchang/andrej-karpathy-skills

四条规则详解

规则	解决的问题	核心指令	效果
1. Think Before Coding	沉默假设（AI 自己猜测需求）	先陈述假设，不确定就提问	减少基于错误理解实现的功能
2. Simplicity First	代码膨胀（过度设计）	最小代码量，200 行能写 50 行就重写	减少不必要代码，降低维护成本
3. Surgical Changes	连带改动（顺手改了不该改的）	只动要动的，不顺手"优化"	减少 diff 噪音，降低引入 bug 风险
4. Goal-Driven Execution	未验证完成（以为做完了）	定义验证标准，循环直到验证通过	减少遗漏，提高交付质量

社区测试数据

指标	无 CLAUDE.md	有 Karpathy 规则
任务错误率	~41%	~11%
无关改动数	高	显著降低
需要重写的次数	频繁	大幅减少
澄清问题时机	实现出问题之后	实现开始之前

如何验证规则生效

当你看到以下现象时，说明规则在工作：

1. diff 中无关改动减少 — 改动只集中在需求相关的行
2. 重写次数变少 — 第一次提交就接近正确
3. 提问时机前移 — 在编码之前就提出问题，而不是错误之后
4. 代码更简洁 — 不会出现 “万一以后需要” 的代码