multica-ai / andrej-karpathy-skills
multica-ai / andrej-karpathy-skills
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.
受 Karpathy 启发的 Claude Code 指南 欢迎查看我的新项目 Multica——一个用于运行和管理具有可复用技能的编码智能体的开源平台。欢迎在 X 上关注我：https://x.com/jiayuan_jy 这是一个旨在改善 Claude Code 行为的单一 CLAUDE.md 文件，源自 Andrej Karpathy 对大模型（LLM）编码陷阱的观察。
The Problems
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.”
问题所在
引用自 Andrej 的文章： “模型会替你做出错误的假设，并且在不经核实的情况下直接执行。它们不会管理自己的困惑，不会寻求澄清，不会指出不一致之处，不会提出权衡方案，也不会在必要时提出反对意见。” “它们非常喜欢过度复杂化代码和 API，增加臃肿的抽象，不清理死代码……当 100 行代码就能解决问题时，它们却实现了 1000 行臃肿的结构。” “它们有时仍会因为副作用而修改或删除那些它们并未充分理解的注释和代码，即使这些内容与任务完全无关。”
The Solution
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
1. Think Before Coding 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
四项原则详解
1. 编码前先思考 不要假设。不要隐藏困惑。提出权衡方案。 大模型通常会默默选择一种解读方式并直接执行。此原则强制要求进行显式推理：
- 明确陈述假设 —— 如果不确定，请询问而不是猜测
- 提供多种解读 —— 存在歧义时，不要默默做出选择
- 必要时提出反对 —— 如果有更简单的方案，请指出来
- 困惑时停止 —— 指出不清楚的地方并寻求澄清
2. Simplicity First 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.
2. 简洁至上 用最少的代码解决问题。不做任何推测性的工作。 对抗过度工程的倾向：
- 不添加超出需求的功能
- 不为一次性代码编写抽象
- 不添加未被要求的“灵活性”或“可配置性”
- 不为不可能发生的场景编写错误处理
- 如果 200 行代码可以缩减为 50 行，请重写
- 测试标准：资深工程师会认为这太复杂了吗？如果是，请简化。
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.
3. 外科手术式修改 只触碰必须触碰的部分。只清理你自己造成的混乱。 编辑现有代码时：
- 不要“顺便改进”相邻的代码、注释或格式
- 不要重构没有问题的代码
- 遵循现有风格，即使你会有不同的做法
- 如果发现无关的死代码，提出来即可 —— 不要删除它
- 当你的修改产生孤儿代码时：删除那些因你的修改而变得未被使用的导入/变量/函数
- 除非被要求，否则不要删除预先存在的死代码
- 测试标准：每一行被修改的代码都应直接对应用户的请求。
4. Goal-Driven Execution Define success criteria. Loop until verified. Transform imperative tasks into verifiable goals:
- Instead of “Add validation” → Transform to “Write tests for invalid inputs, then make them pass”
- Instead of “Fix the bug” → Transform to “Write a test that reproduces it, then make it pass”
- Instead of “Refactor X” → Transform to “Ensure tests pass before and after”
- For multi-step tasks, state a brief plan: 1. [Step] → verify: [check] …
- Strong success criteria let the LLM loop independently. Weak criteria (“make it work”) require constant clarification.
4. 目标驱动执行 定义成功标准。循环直至验证通过。 将指令式任务转化为可验证的目标：
- 将“添加验证”转化为“为无效输入编写测试，然后使其通过”
- 将“修复 Bug”转化为“编写一个重现该 Bug 的测试，然后使其通过”
- 将“重构 X”转化为“确保重构前后测试均通过”
- 对于多步骤任务，制定简要计划：1. [步骤] → 验证：[检查] …
- 强大的成功标准能让大模型独立循环执行。薄弱的标准（如“让它能跑就行”）则需要不断的澄清。
Install
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.
安装
选项 A：Claude Code 插件（推荐）
在 Claude Code 中，首先添加市场：
/plugin marketplace add forrestchang/andrej-karpathy-skills
然后安装插件：
/plugin install andrej-karpathy-skills@karpathy-skills
这将把指南安装为 Claude Code 插件，使该技能在你的所有项目中均可用。
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
选项 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
Using with Cursor
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.
在 Cursor 中使用
本仓库包含一个已提交的 Cursor 项目规则文件 (.cursor/rules/karpathy-guidelines.mdc)，因此当你用 Cursor 打开项目时，同样的指南也会生效。请参阅 CURSOR.md 以了解设置、如何在其他项目中使用该规则，以及它与 Claude Code 的关系。
Key Insight 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.
来自 Andrej 的核心见解
“大模型非常擅长循环执行直到达成特定目标……不要告诉它怎么做，给它成功标准，然后看着它执行即可。” “目标驱动执行”原则正是捕捉到了这一点：将指令式任务转化为带有验证循环的声明式目标。
How to Know It’s Working
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”
如何判断是否生效
如果出现以下情况，说明这些指南正在发挥作用：
- Diff 中不必要的更改减少了 —— 只出现请求的更改
- 因过度复杂化导致的重写减少了 —— 代码一次性写得简洁
- 在实现之前就会提出澄清问题 —— 而不是在犯错之后
- PR 干净且精简 —— 没有顺带的重构或“改进”
Customization
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
自定义
这些指南旨在与项目特定的说明合并使用。你可以将它们添加到现有的 CLAUDE.md 中或创建一个新的。对于项目特定的规则，可以添加如下部分：
## 项目特定指南
- 使用 TypeScript 严格模式
- 所有 API 端点必须包含测试
- 遵循 src/utils/errors.ts 中现有的错误处理模式
Tradeoff Note
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.
权衡说明
这些指南倾向于谨慎而非速度。对于琐碎的任务（简单的拼写错误修复、显而易见的一行代码），请自行判断 —— 并非每一次更改都需要完全遵循这些严格流程。其目标是减少在复杂工作中的昂贵错误，而不是拖慢简单任务的进度。
License MIT
许可证 MIT