Karpathy 启发的 Claude Code 指南：用一份 CLAUDE.md 改善 AI 编程行为
英文标题：🔥 multica-ai/andrej-karpathy-skills
该项目提供一份可直接使用的 `CLAUDE.md` 指南，依据 Andrej Karpathy 对 LLM 编程常见问题的观察，旨在改善 Claude Code 的工作方式。指南围绕“编码前思考、简单优先、外科手术式修改、目标驱动执行”四项原则，分别应对错误假设、过度设计、无关改动和缺乏可验证目标等问题。开发者可通过 Claude Code 插件全局安装，也可按项目下载或追加至 `CLAUDE.md`；项目同时提供 Cursor 规则支持。其核心价值在于让 AI 在复杂任务中先澄清问题、以测试和成功标准驱动执行，并产出更小、更干净的代码变更。
77.5 KB
中文
Karpathy 启发的 Claude Code 指南
欢迎查看我的新项目 Multica——一个用于运行和管理具备可复用技能的编程 Agent 的开源平台。
在 X 上关注我：https://x.com/jiayuan_jy
一份用于改善 Claude Code 行为的 CLAUDE.md 文件，源自 Andrej Karpathy 的观察：LLM 在编程时容易出现各种问题。
英文 | 简体中文
摘自 Andrej 的帖子：
“模型会替你作出错误假设，然后不加核查地一路执行下去。它们不会管理自身的困惑，不会寻求澄清，不会暴露不一致之处，不会展示权衡，也不会在应当反驳时提出异议。”
“它们非常喜欢把代码和 API 过度复杂化，堆砌抽象，不清理死代码……明明 100 行代码就够，却实现出一个超过 1000 行的臃肿构造。”
“它们有时仍会把自己理解不充分的注释和代码修改或删除，作为副作用——即使这些内容与任务无关。”
一个文件中的四项原则，直接应对这些问题：
| 原则 | 应对的问题 |
|---|---|
| 编码前思考 | 错误假设、隐藏的困惑、缺少权衡 |
| 简单优先 | 过度复杂化、臃肿的抽象 |
| 外科手术式修改 | 无关编辑、触碰不应修改的代码 |
| 目标驱动执行 | 通过测试优先和可验证的成功标准提升执行效率 |
四项原则详解
不要假设。不要隐藏困惑。呈现权衡。
LLM 经常会默默选择一种解释，然后据此执行。这项原则要求显式推理：
- 明确陈述假设——不确定时，应提问而不是猜测
- 呈现多种解释——存在歧义时，不要默默作出选择
- 在必要时提出异议——如果存在更简单的方法，应明确说明
- 感到困惑时停止——说清楚哪些内容不明确，并请求澄清
用最少的代码解决问题。不做任何推测性的工作。
对抗过度工程化的倾向：
- 不实现请求范围之外的功能
- 不为一次性使用的代码创建抽象
- 不添加未经请求的“灵活性”或“可配置性”
- 不为不可能发生的场景编写错误处理
- 如果 200 行代码可以缩减为 50 行，就重写它
**测试标准：**资深工程师会认为这过于复杂吗？如果会，就简化。
只修改必须修改的内容。只清理自己造成的问题。
编辑现有代码时：
- 不要“改进”相邻代码、注释或格式
- 不要重构没有问题的内容
- 遵循现有风格，即使你会采用不同做法
- 如果发现无关的死代码，可以指出它——但不要删除它
当你的修改产生孤立内容时：
- 移除因你的修改而变得未使用的 import、变量和函数
- 除非被要求，否则不要移除预先存在的死代码
**测试标准：**每一处修改的代码行，都应能直接追溯到用户的请求。
定义成功标准。循环执行，直到验证成功。
将命令式任务转换为可验证的目标：
| 不要这样说…… | 转换为…… |
|---|---|
| “添加验证” | “为无效输入编写测试，然后让这些测试通过” |
| “修复这个 bug” | “编写能复现该问题的测试，然后让它通过” |
| “重构 X” | “确保重构前后测试均能通过” |
对于多步骤任务，说明一个简短计划：
1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]
强有力的成功标准能让 LLM 独立循环执行。弱标准（如“让它能用”）则需要持续澄清。
方案 A：Claude Code 插件（推荐）
在 Claude Code 中，先添加 marketplace：
/plugin marketplace add forrestchang/andrej-karpathy-skills
然后安装插件：
/plugin install andrej-karpathy-skills@karpathy-skills
这会将指南安装为 Claude Code 插件，使该技能可用于你的所有项目。
方案 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
此仓库包含一条已提交的 Cursor 项目规则（.cursor/rules/karpathy-guidelines.mdc），因此当你在 Cursor 中打开该项目时，同样的指南也会生效。有关设置、在其他项目中使用此规则，以及它与 Claude Code 的关系，请参阅 CURSOR.md。
摘自 Andrej：
“LLM 极其擅长循环执行，直到达成特定目标……不要告诉它该做什么，而要给它成功标准，然后看着它完成任务。”
“目标驱动执行”原则正是对此的概括：将命令式指令转化为带有验证循环的声明式目标。
如果你观察到以下现象，说明这些指南正在发挥作用：
- Diff 中不必要的改动更少——只出现被请求的修改
- 因过度复杂化导致的重写更少——第一次写出的代码就足够简单
- 澄清问题发生在实现之前——而不是在犯错之后
- 干净、精简的 PR——没有顺手进行的重构或“改进”
这些指南旨在与项目特定指令合并使用。可以将其添加到现有的 CLAUDE.md，或创建一个新的文件。
对于项目特定规则，可以添加如下章节：
## 项目特定指南
- 使用 TypeScript 严格模式
- 所有 API 端点都必须有测试
- 遵循 `src/utils/errors.ts` 中现有的错误处理模式
这些指南倾向于谨慎而非速度。对于简单任务（例如简单的拼写修正、显而易见的单行修改），请自行判断——并非每一项改动都需要完整的严谨流程。
目标是在非简单任务中减少代价高昂的错误，而不是拖慢简单任务。
MIT
English / 原文
Karpathy-Inspired Claude Code Guidelines
Check out my new project Multica — an open-source platform for running and managing coding agents with reusable skills.
Follow me on X: https://x.com/jiayuan_jy
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
English | 简体中文
From Andrej's post:
"The models make wrong assumptions on your 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."
"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."
"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."
Four principles in one file that directly address these issues:
| Principle | Addresses |
|---|---|
| Think Before Coding | Wrong assumptions, hidden confusion, missing tradeoffs |
| Simplicity First | Overcomplication, bloated abstractions |
| Surgical Changes | Orthogonal edits, touching code you shouldn't |
| Goal-Driven Execution | Leverage through tests-first, verifiable success criteria |
The Four Principles in Detail
Don't assume. Don't hide confusion. Surface tradeoffs.
LLMs often pick an interpretation silently and run with it. This principle forces explicit reasoning:
- State assumptions explicitly — If uncertain, ask rather than guess
- Present multiple interpretations — Don't pick silently when ambiguity exists
- Push back when warranted — If a simpler approach exists, say so
- Stop when confused — Name what's unclear and ask for clarification
Minimum code that solves the problem. Nothing speculative.
Combat the tendency toward overengineering:
- 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 200 lines could be 50, rewrite it
The test: Would a senior engineer say this is overcomplicated? If yes, simplify.
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.
Define success criteria. Loop until verified.
Transform imperative tasks into verifiable goals:
| Instead of... | Transform to... |
|---|---|
| "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 the LLM loop independently. Weak criteria ("make it work") require constant clarification.
Option A: Claude Code Plugin (recommended)
From within Claude Code, first add the marketplace:
/plugin marketplace add forrestchang/andrej-karpathy-skills
Then install the plugin:
/plugin install andrej-karpathy-skills@karpathy-skills
This installs the guidelines as a Claude Code plugin, making the skill available across all your projects.
Option B: CLAUDE.md (per-project)
New project:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
Existing project (append):
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
This repository includes a committed Cursor project rule (.cursor/rules/karpathy-guidelines.mdc) so the same guidelines apply when you open the project in Cursor. See CURSOR.md for setup, using the rule in other projects, and how this relates to Claude Code.
From Andrej:
"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."
The "Goal-Driven Execution" principle captures this: transform imperative instructions into declarative goals with verification loops.
These guidelines are working if you see:
- Fewer unnecessary changes in diffs — Only requested changes appear
- Fewer rewrites due to overcomplication — Code is simple the first time
- Clarifying questions come before implementation — Not after mistakes
- Clean, minimal PRs — No drive-by refactoring or "improvements"
These guidelines are designed to be merged with project-specific instructions. Add them to your existing CLAUDE.md or create a new one.
For project-specific rules, add sections like:
## Project-Specific Guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`
These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor.
The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.
MIT