andrej-karpathy-skills

Karpathy 启发的 Claude Code 指南

看看我的新项目 Multica —— 一个用于运行和管理拥有可复用技能的编程 agent（智能体）的开源平台。

在 X 上关注我： https://x.com/jiayuan_jy

一份单一的 CLAUDE.md 文件，用于改进 Claude Code 的行为，源自 Andrej Karpathy 的观察 关于 LLM（大语言模型）编程陷阱。

English | 简体中文

问题

摘自 Andrej 的帖子：

“模型会替你做出错误的假设，并且不加验证地直接执行。它们不会管理自己的困惑，不会寻求澄清，不会揭示矛盾，不会呈现权衡，在应该提出异议时也不会反驳。”

“它们非常喜欢过度复杂化代码和 API，膨胀抽象层，不清除死代码…… 明明 100 行就能搞定，却要搞出 1000 行的臃肿结构。”

“它们有时还会修改/删除它们并未充分理解的注释和代码（作为附带影响），即使这些修改与当前任务正交无关。”

解决方案

一个文件中的四条原则，直接解决这些问题：

原则	解决的问题
先思考再编码	错误假设、隐藏的困惑、缺失的权衡
简洁优先	过度复杂化、膨胀的抽象层
外科手术式修改	正交无关的编辑、修改了不该碰的代码
目标驱动执行	通过测试优先、可验证的成功标准来施加杠杆

四个原则详解

1. 先思考再编码

不要假设。不要隐藏困惑。呈现权衡。

LLM 常常默默选择一种解释并径直执行。这条原则强制进行显式推理：

• 显式陈述假设 —— 如果不确定，就提问而不是猜测
• 呈现多种解释 —— 存在歧义时不要默默选定
• 在适当的时候提出异议 —— 如果存在更简单的方法，就说出来
• 困惑时停下来 —— 指出不清晰的地方，并请求澄清

2. 简洁优先

解决问题所需的最小代码。不做投机性工作。

对抗过度工程的倾向：

• 不添加未被要求的特性
• 不为一次性的代码设计抽象层
• 不引入未被要求的“灵活性”或“可配置性”
• 不为不可能的场景添加错误处理
• 如果 200 行能写成 50 行，就重写

检验标准： 资深工程师会不会说这太复杂了？如果是，请简化。

3. 外科手术式修改

只改动必须改的地方。只清理自己造成的混乱。

编辑现有代码时：

• 不要“改进”相邻的代码、注释或格式
• 不要重构没有坏的东西
• 匹配现有风格，即使你个人会采用不同的写法
• 如果你注意到无关的死代码，可以提出来——但不要删除

当你的改动产生了孤立的代码：

• 移除由于你的改动而不再使用的导入/变量/函数
• 不要移除之前就存在的死代码，除非被要求

检验标准： 每行被修改的代码都应该能直接追溯到用户的请求。

4. 目标驱动执行

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

将命令式任务转化为可验证的目标：

不要这样...	应该这样...
“添加验证”	“为无效输入编写测试，然后让它们通过”
“修复这个 bug”	“编写一个能复现它的测试，然后让它通过”
“重构 X”	“确保测试在重构前后都通过”

对于多步骤任务，陈述一个简短的计划：

1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]

强有力的成功标准能让 LLM 独立循环。弱标准（“让它工作”）需要持续的澄清。

安装

选项 A：Claude Code 插件（推荐）

在 Claude Code 内部，先添加市场：

/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 项目规则（.cursor/rules/karpathy-guidelines.mdc），因此当你在 Cursor 中打开该项目时，同样的指南也适用。请参阅 CURSOR.md 了解设置方法、如何将该规则用于其他项目，以及这与 Claude Code 的关系。

关键见解

来自 Andrej：

“LLM 非常擅长循环直到达成特定目标…… 不要告诉它该做什么，给它成功标准，然后看它行动。”

“目标驱动执行”原则捕捉了这一要点：将命令式指令转化为带有验证循环的声明式目标。

如何判断它是否有效

如果你看到以下迹象，说明这些指南正在起作用：

• diff 中不必要的改动更少 —— 只出现被请求的改动
• 因过度复杂化导致的重写更少 —— 代码首次提交时就简洁
• 澄清性问题出现在实现之前 —— 而不是在出错之后
• 整洁、最小的 PR —— 没有顺手重构或“改进”

自定义

这些指南设计为可以与项目特定的指令合并。将它们添加到已有的 CLAUDE.md 中，或者创建一份新的。

对于项目特定规则，可以添加类似这样的段落：

## 项目特定指南

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

权衡说明

这些指南倾向于谨慎优先于速度。对于琐碎任务（简单的拼写修正、显而易见的单行修改），请自行判断——并非每次改动都需要完整的严谨流程。

目标是在非简单工作上减少代价高昂的错误，而不是拖慢简单任务。

许可协议

MIT