Blog
The Karpathy CLAUDE.md: what is in it and does it help?
Published: September 23, 2026
The “Karpathy CLAUDE.md” is a 65-line file of four coding principles for Claude Code: think before coding, simplicity first, surgical changes, goal-driven execution. Andrej Karpathy did not write it. A developer turned his January 2026 post about LLM coding mistakes into a file, published as the andrej-karpathy-skills repository.
Checked on 2026-09-23 against the repository (now under the multica-ai organisation, about 215,000 stars) and its CLAUDE.md. It is one of the most copied instruction files in the ecosystem, which makes it worth reading closely: what it gets right is a good lesson in writing these files, and what it cannot do is a better one.
Did Andrej Karpathy write this CLAUDE.md?
No. On 26 January 2026 Karpathy posted a list of the ways coding models go wrong, including that they make wrong assumptions on your behalf and run with them. The repository was created about seven hours later by the GitHub user forrestchang, who distilled the post into four principles. The name borrows Karpathy's; the file is a community interpretation. That is not a knock on it, but it is worth knowing before you quote it as his. What Karpathy did publish himself, as a gist, is his LLM wiki, a different thing.
What is in the Karpathy CLAUDE.md?
| Principle | What it asks of the model |
|---|---|
| Think before coding | State assumptions, present competing interpretations instead of choosing silently, push back when a simpler approach exists, stop and ask when something is unclear. |
| Simplicity first | The minimum code that solves the problem. No speculative features, no abstractions for single-use code, no error handling for cases that cannot happen. |
| Surgical changes | Touch only what the request needs. Do not reformat or refactor adjacent code; mention dead code rather than deleting it. |
| Goal-driven execution | Turn a task into a check ("write a test that reproduces it, then make it pass") and loop until it passes. |
It closes with its own success test: fewer unnecessary changes in diffs, fewer rewrites, and clarifying questions before the mistake rather than after.
How do you install it?
As a Claude Code plugin, from the README:
/plugin marketplace add forrestchang/andrej-karpathy-skills /plugin install andrej-karpathy-skills@karpathy-skills
Or copy the file into a project with curl and merge it with your own CLAUDE.md. The repository also ships a Cursor project rule with the same content. If your team uses more than one agent, put it in AGENTS.md instead; see AGENTS.md vs CLAUDE.md.
Why does it work as well as it seems to?
Three reasons, and they are the reasons to copy its style even if you never install it.
It is short. Sixty-five lines is cheap to carry on every turn, which matters because an instruction file is in the prompt every time. The ETH Zurich study of context files measured about 20 percent more inference cost for carrying one (arXiv:2602.11988).
It states judgment, not rules. Anthropic's July 2026 guidance for Claude 5 models argues for principles over rigid constraints, and this file is almost entirely principles. There is nothing in it to go stale when the code changes. More in context engineering for Claude 5.
It targets the model's habits, not your codebase. Over-building, drive-by refactors and silent assumptions happen in every repository, so one file can help everyone who copies it.
Does the Karpathy CLAUDE.md actually help?
The repository offers a self-check, not a benchmark, and there is no published evaluation of this file that we could find. The wider research suggests keeping expectations modest. In the revised ETH study, developer-written context files moved task success 2.4 points, a difference the authors could not separate from noise. A factorial study of 1,650 Claude Code sessions found that how an instruction file is structured made no detectable difference to adherence, while compliance fell as sessions grew longer (arXiv:2605.10039). The fair reading: a short behavioural file is cheap and can help, and the best way to know is to watch your own diffs for a week with and without it. The full research summary is in is AGENTS.md useful.
What can a generic CLAUDE.md not do?
Everything that is specific to your team. It can tell the model to make surgical changes. It cannot tell it that webhook retries stop at five because of an incident in March, that the orders table is never migrated during business hours, or that the team moved off the old queue last quarter. Those decisions are the ones that cost the most when an agent gets them wrong, and no file on GitHub contains them.
The pattern that holds up: a short, stable behavioural file like this one on every turn, and the team's decisions served only when the task touches them.
Where Harbor fits
Harbor handles the second half. It reads where your team decides: Slack threads, pull request reviews, ADRs and docs. A person approves what becomes a fact, or a policy you set approves the routine ones. Claude Code, Codex and Cursor are then each served only the approved facts that apply to the task, so the webhook rule arrives when someone touches webhooks and stays out of the prompt otherwise.
Because every served fact is numbered and answers cite the ones they used, Harbor can count, per fact, how often it was served against how often it was cited. That gives you a way to prune the team's rules with evidence. A cite is evidence, not proof. See served vs cited.
Questions
Did Andrej Karpathy write the CLAUDE.md file?
No. The andrej-karpathy-skills repository was created by a developer hours after a January 2026 post in which Karpathy described common LLM coding mistakes. The file distils that post into four principles.
What are the four principles in the Karpathy CLAUDE.md?
Think before coding, simplicity first, surgical changes, and goal-driven execution. Together they ask the model to surface assumptions, write the minimum code, touch only what the task needs, and verify against a check.
How do I install the Karpathy CLAUDE.md?
Install it as a Claude Code plugin with /plugin marketplace add forrestchang/andrej-karpathy-skills and /plugin install andrej-karpathy-skills@karpathy-skills, or copy the file into your project and merge it with your own CLAUDE.md.
Does the Karpathy CLAUDE.md improve results?
There is no published evaluation of this file. It is short and states principles rather than rules, which keeps its cost low, but research on context files shows modest effects, so compare your own diffs with and without it.