The Karpathy CLAUDE.md is a single 65-line instruction file for AI coding agents, published in the andrej-karpathy-skills repo by the developer behind the GitHub account forrestchang (Jiayuan on X). It turns a post by Andrej Karpathy about the mistakes coding models keep making into four rules: think before coding, keep it simple, make surgical changes, and work toward a checkable goal.
Karpathy did not write the file. He described the problems, and the repo is one developer’s answer to them. That distinction matters when you decide how much to trust it, so this guide covers what each rule says, what it costs in context, how to install it without overwriting your own CLAUDE.md, and where it falls short.
Checked against commit 2c60614 on Oct 23, 2026. The CLAUDE.md file itself has not changed since Jan 27, 2026.
What problem the Karpathy CLAUDE.md is answering
The README quotes three complaints from Karpathy’s post. Models “make wrong assumptions on your behalf and just run along with them without checking.” They “really like to overcomplicate code and APIs, bloat abstractions, don’t clean up dead code.” And they “still sometimes change/remove comments and code they don’t sufficiently understand as side effects.”
Anyone who has used Claude Code, Codex or Cursor for a week will recognise all three. The file does not add tools or change the model. It is text that gets loaded into the agent’s instructions at the start of a session, so its only lever is wording.
The four rules, line by line
1. Think before coding
The headline is “Don’t assume. Don’t hide confusion. Surface tradeoffs.” The agent is told to state its assumptions, list the possible readings of an ambiguous request instead of quietly picking one, say so when a simpler approach exists, and stop and ask when something is unclear. In practice this shows up as more questions at the start of a task, which is the point.
2. Simplicity first
“Minimum code that solves the problem. Nothing speculative.” No features beyond the request, no abstractions for code used once, no configurability nobody asked for, no error handling for situations that cannot happen. The memorable line is “If you write 200 lines and it could be 50, rewrite it,” followed by a self-check: would a senior engineer call this overcomplicated?
3. Surgical changes
“Touch only what you must. Clean up only your own mess.” Do not reformat or “improve” nearby code, match the existing style, and mention unrelated dead code rather than deleting it. The one cleanup it does allow: remove imports or functions that your own change made unused. The test it gives is the best single line in the file: every changed line should trace directly to the user’s request.
4. Goal-driven execution
“Define success criteria. Loop until verified.” Vague tasks get rewritten as checkable ones: “fix the bug” becomes “write a test that reproduces it, then make it pass.” For multi-step work the agent writes a short plan where each step has its own verify check.
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]The file opens with an honest tradeoff note: the rules “bias toward caution over speed,” and for trivial tasks the agent should use judgment. If you mostly ask for one-line fixes, you may find the extra questions slow.
What it costs in context
Because a CLAUDE.md is loaded every session, size matters. I measured the file as published:
| Measure | Value |
|---|---|
| Lines | 65 |
| Bytes | 2,357 |
| Words | 358 |
| Tokens (cl100k_base) | 532 |
| Tokens (o200k_base) | 522 |
Anthropic does not publish its tokenizer, so the two OpenAI encodings are a stand-in; expect a figure in the same range for Claude. Around 530 tokens is small next to a typical system prompt and tool list, and far smaller than the output of a single test run. Cost is not a reason to skip it.
How to install it without losing your own rules
The README gives three routes. Here is what each one actually does.
As a Claude Code plugin
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skillsThis installs the rules as a skill available in every project rather than a file in your repo. The skill version in skills/karpathy-guidelines/SKILL.md has the same four rules but drops the closing “These guidelines are working if” lines and adds a credit line to Karpathy’s post. Skills load when the agent decides they are relevant, so unlike a CLAUDE.md they are not guaranteed to be in context on every turn. If you want to know which other plugins earn their place, see which Claude Code plugins are worth installing.
As a new CLAUDE.md
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.mdThe old raw URL still works after the repo moved to the multica-ai organisation; it returned the same 2,357-byte file. But curl -o replaces whatever CLAUDE.md you already had, with no warning and no backup. In my test it silently replaced a four-line project file with the 65-line download. Only use it in a project that has no CLAUDE.md yet.
Appended to an existing CLAUDE.md
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdThis keeps your rules, but it pastes a second top-level heading into the middle of the file. I started from a four-line CLAUDE.md headed # My app and ended with 70 lines and two H1s:
$ grep -n '^# ' CLAUDE.md
1:# My app
6:# CLAUDE.mdThe agent will still read it, but it is messy and a heading literally called “CLAUDE.md” tells the model nothing. Open the file after appending, delete that heading, and demote the four numbered sections so they sit under your project heading. It is also worth deleting any of your own lines that contradict the new rules, such as an old instruction to “tidy up formatting as you go”, which clashes with the surgical-changes rule.
In Cursor
The repo includes .cursor/rules/karpathy-guidelines.mdc with alwaysApply: true, so the rules load on every request in that project. Copy the file into your own project’s .cursor/rules/ folder to reuse it. If your agent reads AGENTS.md rather than CLAUDE.md, check which file it actually loads first; our tests in Claude Code not reading AGENTS.md show it is easy to get wrong.
Where the four rules fall short
- They are advice, not enforcement. Nothing stops an agent from ignoring a rule mid-task. If you need a hard limit, such as never deleting files, use permissions or a sandbox, not wording.
- Rule 4 assumes you have tests. “Loop until verified” is only as good as the check. In a project with no test runner, the agent will invent a weaker verification or skip it.
- There are no project facts. The file says nothing about your build command, folder layout or naming. Those are usually where agents waste the most time, so add them yourself.
- It has not been updated since January. The repo’s last push was Apr 20, 2026, and the file is unchanged since its first commit. That is not a problem for timeless advice, but do not expect it to track new agent features.
Over-engineering in particular can need more than a prompt. We tested a tool built for exactly that problem in does Ponytail actually stop Claude Code from over-engineering. And if you want to understand why instruction files work at all, our walkthrough of how Claude Code works shows where that text enters the agent loop.
A practical way to roll out the four rules
- Append the file to your existing CLAUDE.md, then remove the duplicate heading.
- Add three or four project facts under it: how to run tests, how to build, which folders are generated.
- Give the agent a small, real task such as fixing one failing test, and read the diff. Count lines that do not trace back to your request.
- Remove any rule you find yourself overriding every session. A short file you agree with beats a long one the agent learns to ignore.
The repo’s own measure of success is sensible: fewer unnecessary changes in diffs, fewer rewrites, and clarifying questions before the code rather than after a mistake.
Common questions about the Karpathy CLAUDE.md
Did Andrej Karpathy write this CLAUDE.md?
No. Karpathy wrote a post describing common coding-model mistakes. The CLAUDE.md file and repo come from the developer behind the forrestchang account, who credits the post as the source of the ideas.
Should I use the plugin or the file?
Use the file if you want the rules applied on every turn in one project and visible to your team in the repo. Use the plugin if you want them available everywhere without touching each project, and accept that a skill loads only when the agent decides it is relevant. Do not use both in the same project, or the agent reads the same rules twice.
Will it overwrite my existing CLAUDE.md?
The curl -o command will. Use the append command instead, then clean up the duplicate heading it creates.
Does it work with Codex or Cursor?
The text works with any agent that reads an instruction file. The repo ships a Cursor rule file, and you can paste the same four sections into AGENTS.md for agents that read that instead.
How many tokens does it add to each session?
About 520 to 530 tokens by OpenAI’s tokenizers. The exact count for Claude may differ slightly, but it is small either way.
12 comments