Karpathy CLAUDE.md: The 4 Rules and How to Install It
By Neo Zino - builder of ClockedCode6 min readKarpathy's CLAUDE.md turns four LLM coding failures into four rules. See what each rule does, how to install it, and when to skip it.
On this page
TL;DR: The Karpathy CLAUDE.md is a short file of four behavioral rules (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) that targets recurring LLM coding mistakes. Use the plugin for a global setup, curl for a new project, and append for a project that already has a CLAUDE.md. Skip the caution for trivial one-liners.
| Rule | Failure it targets | Sign it is working |
|---|---|---|
| Think Before Coding | Silent assumptions on ambiguous requests (lucaberton.com) | Claude asks clarifying questions before starting (lobehub.com) |
| Simplicity First | Overcomplicated code and unrequested abstractions | No class wrapped around a 3-line function (lobehub.com) |
| Surgical Changes | Edits to neighboring code you never mentioned | Every changed line traces to your request (lucaberton.com) |
| Goal-Driven Execution | Coding before "done" is defined | Plans pair each step with a verify command (lobehub.com) |
| Install | Plugin: global. curl: new project. Append: existing CLAUDE.md | Project rules go after the appended text |
What is the Karpathy CLAUDE.md and what problem does it solve?
A write-up on lucaberton.com says the file encodes Andrej Karpathy's observations about LLM coding failures into four behavioral constraints (lucaberton.com). The same piece names the failures: silent assumptions, overcomplexity, scope creep and vague execution. Models pick one reading of an ambiguous request and run with it, write far more code than needed, "improve" files they were never asked to touch, and start before defining what done looks like.
The author's argument is that these are behavioral defaults a well-structured prompt can override, not model intelligence problems. That is the test for whether the file is worth adding. If you keep reviewing diffs and finding code you did not ask for, or answers built on a guess you never saw, the file targets your problem. If your complaints are about wrong facts or missing context, it will not help.
Think Before Coding: how do you stop silent assumptions?
The rule's wording is plain. State assumptions explicitly, and if uncertain, ask. When multiple interpretations exist, present them instead of picking silently. If something is unclear, stop, name what is confusing, and ask (github.com).
You can tell it is working when Claude asks clarifying questions before starting, not after producing wrong output (lobehub.com). If a vague prompt like "make search better" still produces a large change with no questions, the rule is not being applied.
Simplicity First: how do you stop 200 lines where 50 would do?
The rule is a short list of things not to do:
- No features beyond what was asked.
- No abstractions for single-use code.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
The review question is whether a senior engineer would call the code overcomplicated. If yes, simplify (github.com). Two concrete tells from the Claude Code skill page: wrapping a 3-line function in a class with 5 methods, and adding configurable options when one hardcoded value was needed (lobehub.com). Both are quick to spot in a diff, which makes this the easiest rule to check yourself.
Surgical Changes: how do you keep diffs limited to what you asked for?
Do not "improve" adjacent code, comments, or formatting (github.com). Match existing style, even if the model would do it differently (lucaberton.com). A separate working guide puts the same idea as: don't touch unrelated code or comments (gist.github.com).
The test is the one worth memorizing: every changed line should trace directly to your request (lucaberton.com). Apply it during review. Walk the diff, and for each hunk ask which sentence of your prompt required it. Any hunk without an answer is scope creep, and you can reject it.
Goal-Driven Execution: how do you turn vague tasks into checkable ones?
The article on lucaberton.com argues that strong success criteria let the model loop independently, while weak ones like "make it work" require constant clarification (lucaberton.com). The rule rewrites tasks into verifiable form:
| Vague request | Checkable version |
|---|---|
| Add validation | Write tests for invalid inputs, then make them pass (lucaberton.com) |
| Fix the bug | Write a test that reproduces it, then make it pass (lucaberton.com) |
| Refactor X | Ensure tests pass before and after (lucaberton.com) |
For multi-step work, the skill page shows a plan format that attaches a command to each step, for example "Update schema.py with new field → verify: python -m pytest tests/test_schema.py" (lobehub.com). Copy that shape into your own prompts. If a step has no verify command, the step is not finished being planned.
Which install path fits your project: plugin, new file, or append?
Pick by what you already have:
- You want it everywhere: run
/plugin install andrej-karpathy-skills@karpathy-skillsfor the global setup (lobehub.com). - New project, no CLAUDE.md yet: download the file with `curl -o CLAUDE.md (lobehub.com). Dropped in the project root, Claude Code follows it from the first task (lucaberton.com).
- Existing CLAUDE.md: append instead of overwriting, with
curl >> CLAUDE.md.
Our pick: append for any repo with rules you have already tuned, because the -o download in step 2 replaces your file. After appending, put your project-specific rules below the Karpathy block. The guidelines are additive, and later rules take precedence in most agents when they conflict.
If you are assembling a fuller setup rather than a single file, the tips library at clockedcode.com/free covers more CLAUDE.md patterns you can layer in the same way.
When should you skip it, and what if Claude ignores it?
The source is upfront about the cost: the guidelines bias toward caution over speed, and for trivial tasks you should use judgment (github.com). The skill page agrees that full rigor is unnecessary for trivial one-liners (lobehub.com). A related guide suggests plan mode for non-trivial work and a lightweight inline plan for smaller tasks (gist.github.com). Our recommendation: keep the file on, and tell Claude to skip the ceremony in your prompt for renames, typo fixes and one-line config changes.
It is the wrong choice if most of your work is throwaway scripts or quick edits, where questions before every change will cost more time than they save.
If Claude seems to ignore the rules, run this check first:
- Is CLAUDE.md in the project root, where Claude Code is launched? (lobehub.com)
- Do your own rules sit after the appended block, not before it? (lobehub.com)
- Does a prompt of yours contradict a rule, such as asking for "a few extra improvements" while Surgical Changes is active?
Next action: append the file to one active repo today, give Claude a deliberately vague task, and see whether it asks a question before writing code.