andrej-karpathy-skills Documentation

1. Project Overview & Quickstart (forrestchang/andrej-karpathy-skills) Copy Chapter

File: README.md Copy Chapter

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 | 简体中文

The Problems Copy Chapter

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

The Solution Copy Chapter

Four principles in one file that directly address these issues:

The Four Principles in Detail Copy Chapter

1. Think Before Coding Copy Section

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

2. Simplicity First Copy Section

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.

3. Surgical Changes Copy Section

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 Copy Section

Define success criteria. Loop until verified.

Transform imperative tasks into verifiable goals:

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.

Install Copy Chapter

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

Using with Cursor Copy Chapter

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.

Key Insight Copy Chapter

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.

How to Know It's Working Copy Chapter

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"

Customization Copy Chapter

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`

Tradeoff Note Copy Chapter

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 Copy Chapter

MIT

File: README.zh.md Copy Chapter

受 Karpathy 启发的 Claude Code 指南

查看我的新项目 Multica —— 一个用于运行和管理编码智能体的开源平台，支持可复用的技能。

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

一个单一的 CLAUDE.md 文件，用于改善 Claude Code 的行为，源自 Andrej Karpathy 的观察 关于 LLM 编码陷阱的总结。

English | 简体中文

问题所在 Copy Chapter

来自 Andrej 的推文：

"模型会代你做错误假设，然后不假思索地执行。它们不管理自身的困惑，不寻求澄清，不呈现矛盾，不展示权衡，在应该提出异议时也不反驳。"

"它们真的很喜欢把代码和 API 搞复杂，堆砌抽象概念，不清理死代码……明明 100 行能搞定的事情，非要实现成 1000 行的臃肿架构。"

"它们有时仍会改动或删除自己理解不足的代码和注释，即使这些内容与任务本身无关。"

解决方案 Copy Chapter

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

四个原则详解 Copy Chapter

1. 编码前思考 Copy Section

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

LLM 经常默默选择一种解释然后执行。这个原则强制明确推理：

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

2. 简洁优先 Copy Section

用最少的代码解决问题。不要过度推测。

对抗过度工程的倾向：

• 不要添加要求之外的功能
• 不要为一次性代码创建抽象
• 不要添加未要求的"灵活性"或"可配置性"
• 不要为不可能发生的场景做错误处理
• 如果 200 行代码可以写成 50 行，重写它

检验标准： 资深工程师会觉得这过于复杂吗？如果是，简化。

3. 精准修改 Copy Section

只碰必须碰的。只清理自己造成的混乱。

编辑现有代码时：

• 不要"改进"相邻的代码、注释或格式
• 不要重构没坏的东西
• 匹配现有风格，即使你更倾向于不同的写法
• 如果注意到无关的死代码，提一下 —— 不要删除它

当你的改动产生孤儿代码时：

• 删除因你的改动而变得无用的导入/变量/函数
• 不要删除预先存在的死代码，除非被要求

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

4. 目标驱动执行 Copy Section

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

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

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

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

强有力的成功标准让 LLM 能够独立循环执行。弱标准（"让它工作"）需要不断澄清。

安装 Copy Chapter

选项 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 中使用 Copy Chapter

本仓库包含一个已提交的 Cursor 项目规则 (.cursor/rules/karpathy-guidelines.mdc)，因此在 Cursor 中打开项目时同样适用这些指南。详情请参见 CURSOR.md，包括如何在其他项目中使用该规则，以及它与 Claude Code 的关系。

核心洞察 Copy Chapter

来自 Andrej：

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

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

如何判断它在起作用 Copy Chapter

如果你看到以下情况，说明这些指南正在发挥作用：

• diff 中不必要的改动更少 —— 只有请求的改动出现
• 因过度复杂而导致的重写更少 —— 代码第一次就写得简洁
• 澄清问题在实现之前提出 —— 而不是在犯错之后
• 干净、精简的 PR —— 没有顺带的重构或"改进"

定制 Copy Chapter

这些指南设计用于与项目特定指令合并。将它们添加到你现有的 CLAUDE.md 或创建一个新的。

对于项目特定规则，添加如下章节：

## 项目特定指南

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

权衡说明 Copy Chapter

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

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

许可 Copy Chapter

MIT

2. Official Technical Reference & Guides (forrestchang/docs) Copy Chapter

Mintlify Starter Kit

Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including

• Guide pages
• Navigation
• Customizations
• API Reference pages
• Use of popular components

Development Copy Section

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i mintlify

Run the following command at the root of your documentation (where mint.json is)

mintlify dev

Publishing Changes Copy Section

Install our Github App to autopropagate changes from youre repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with mint.json