Karpathy's CLAUDE.md Skills File, reviewed

For the past several months I have been writing code mostly by directing an agent. Not autocomplete, not chat assistance, but a Claude Code session running in the terminal that reads my repo, makes changes, runs tests, and commits. The productivity shift is real. The failure-mode shift is also real.

The most-cited summary of those failure modes came from a Karpathy tweet in late January. He had been doing the same thing, most of his coding through an agent, and he listed the patterns he kept hitting. The agent makes wrong assumptions and runs with them. It overcomplicates code. It changes things you did not ask it to change. The list is short, and uncomfortably accurate.

A few days after that tweet, Forrest Chang published a short repo on GitHub that translated those observations into a CLAUDE.md file. Roughly seventy lines. Four sections. The repo went on a tear, picking up more stars in three weeks than most actual libraries gather in three years, because the file solves a problem every serious user of these tools has felt.

I have been running a version of it in production for a few weeks. Here is what is actually in it, why it works, and where I think the framing is incomplete.

The four rules

Strip the praise away and the file is four sections.

Think before coding. Do not assume. Ask. If two readings of the request are equally plausible, name both and pick one out loud. If something is unclear, stop and say what is unclear. The goal is to turn a default-confident agent into one that surfaces its uncertainty before it costs you a rewrite.

Simplicity first. No features beyond what was asked. No abstractions for code that is called once. No “configurability” nobody requested. No try/except around failures that cannot happen. If two hundred lines would do the job in fifty, do it in fifty.

Surgical changes. When editing existing code, touch only what the task requires. Do not reformat. Do not add docstrings nobody asked for. Do not refactor adjacent code that “looks weird.” Match the existing style, even if you would write it differently from scratch. If you notice dead code, mention it. Do not delete it.

Goal-driven execution. Convert the instruction into a verifiable outcome. “Add validation” becomes “write the failing test for invalid input, then make it pass.” “Fix the bug” becomes “write a test that reproduces it, then make it pass.” Karpathy’s framing, which the file leans on hard, is that these models are remarkably good at looping until a defined goal is met. They are remarkably bad at deciding what the goal is.

That is it. The whole file fits in a screenshot.

Why something this short matters

I had a friend push back on this a few weeks ago. He pointed out, fairly, that every one of these rules has been in some senior engineer’s head since the eighties. Do not over-engineer. Read the existing code. Ask before you build. Test-driven everything. None of it is new.

He is right that the rules are not new. He is wrong about why the file matters.

The reason it works is not that it teaches the agent to think like a senior engineer. The agent already knows what a senior engineer would say, because the training data is full of senior engineers complaining about over-engineering. The reason it works is that the file lives at the top of every session and gets read before the agent starts forming opinions about your codebase. It is not new information. It is reinforcement at the right moment.

Most CLAUDE.md files I had seen before this one were filled with project-specific facts. “We use Postgres.” “Run pnpm test before committing.” “Do not touch /legacy.” Useful, but they do not change behaviour. The Karpathy file changes behaviour because it intervenes at the level of how the agent decides what to do, not just where to find things.

Where it gets it wrong

A few honest critiques, since the repo’s own README does not have many.

First, the file biases toward caution at the cost of speed, and it says so. For a fintech codebase or a payments integration where one bad migration means real money, that tradeoff is correct. For a Tuesday-afternoon prototype, it is the wrong tone. The agent ends up asking three clarifying questions for a one-line change. The file is not sized for both contexts and there is no graceful way to ask for one mode versus the other from inside a session.

Second, “surgical changes” is the most violated rule in practice. The agent will still reformat a line three rows below your edit. Still rewrite a comment because the new wording reads better. Still add a type hint to a parameter that did not have one. The file tells it not to. The model agrees. The pattern persists. My guess is that this is one of those places where training pressure (write clean code, add types, match best practices) overpowers an instruction-following signal. The rule belongs in the file, but you cannot trust it without reading every diff.

Third, the file is silent about what to do when you are wrong. Karpathy’s original list has a line the file does not quote: “push back when they should.” Even with this file installed, the agent will still nod along when you suggest a bad approach. Telling it to surface tradeoffs at the requirements stage helps. But the model has no instinct for telling you “no, that is the wrong design” once you have already started executing it. That is a real gap.

What I would add for a regulated codebase

If I were writing the equivalent file for a fintech team, I would add three sections on top of these four.

A rule about audit trails. Every code change should be traceable to a specific written request: a ticket, an instruction, a documented decision. The agent should resist changes that do not have a paper trail, even if they “obviously improve the code.” For RBI or DPDP work, the diff itself becomes evidence.

A rule about boundaries. The agent should refuse, by default, to touch anything in /migrations, /secrets, or files that match .env*. The Karpathy file assumes the human will catch bad behaviour in review. For regulated work, prevention matters more than detection.

A rule about idempotency. For anything that mutates external state, running a script, calling an API, hitting a database, the agent should default to a dry run first and ask for confirmation. The “loop until verified” instinct in the goal-driven section is the right call for pure code. For side effects, it is how you accidentally email your customer list twice.

How to install it

For all your projects, install it as a Claude Code plugin once and forget about it:

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

For one project, drop the file into the repo root:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Either way, layer your project-specific rules on top. The four-rule file is the floor, not the ceiling.

The file itself, for reference

The complete contents of the file at the time of writing. Lifted verbatim from forrestchang/andrej-karpathy-skills so you can see what the seventy lines actually look like before you install it.

1# CLAUDE.md2 3Behavioral guidelines to reduce common LLM coding4mistakes. Merge with project-specific instructions5as needed.6 7Tradeoff: These guidelines bias toward caution8over speed. For trivial tasks, use judgment.9 10## 1. Think Before Coding11Don't assume. Don't hide confusion. Surface tradeoffs.12 13Before implementing:14- State your assumptions explicitly. If uncertain, ask.15- If multiple interpretations exist, present them.16- If a simpler approach exists, say so.17- If something is unclear, stop. Name what's confusing.18 19## 2. Simplicity First20Minimum code that solves the problem. Nothing speculative.21 22- No features beyond what was asked.23- No abstractions for single-use code.24- No "flexibility" that wasn't requested.25- No error handling for impossible scenarios.26- If 200 lines could be 50, rewrite it.27 28## 3. Surgical Changes29Touch only what you must. Clean up only your own mess.30 31- Don't "improve" adjacent code or formatting.32- Don't refactor things that aren't broken.33- Match existing style, even if you'd do it differently.34- If you notice dead code, mention it — don't delete it.35 36## 4. Goal-Driven Execution37Define success criteria. Loop until verified.38 39Transform tasks into verifiable goals:40- "Add validation" → "Write tests, then make them pass"41- "Fix the bug" → "Reproduce it in a test, then fix"42- "Refactor X" → "Ensure tests pass before and after"

A last note on the broader shift

The most uncomfortable thing Karpathy said in that tweet was not about LLM mistakes. It was the production claim. He had gone from 80% manual and 20% agent in November to 80% agent and 20% manual a few months later, and he did not sound thrilled about it. The productivity is real, the dependence is real, and there is no obvious off-ramp.

A file like this one is not a fix for that. It is a guardrail for a system you have already decided to use. The harder question, whether eighty percent of your code being written by something you have to babysit is actually progress, is one I do not have a clean answer to. I notice I get more done. I also notice that the thing I am getting done is more often “babysitting an agent” than “writing the next thing I need.” That is a real cost.

The Karpathy file makes the babysitting less painful. It does not change that it is babysitting.