CLAUDE.md In Practice: What Actually Earns A Place In The File

Check the file before you copy it

The instruction file has become the standard way to make a coding agent behave, and the standard way to write one is to paste in a template. The most-copied template comes with two claims attached, and both are worth checking before you build a habit on them.

multica-ai/andrej-karpathy-skills is the file everyone means. It was created on 27 January 2026, derived from Andrej Karpathy's observations about where LLM coding goes wrong, and it now carries 201,882 stars and 20,711 forks, which makes it one of the most-starred single-purpose files on GitHub. Those figures come from the GitHub API on 13 August 2026, not from the coverage, because the coverage does not agree with itself: reports of the same repository in the last three months have put it at 97.8k, 101K, 120,000 and "220,000 combined".

Here is the part that matters. That repository contains four rules. Think before coding. Simplicity first. Surgical changes. Goal-driven execution. The widely circulated "twelve-rule CLAUDE.md" is a third-party extension of it, not the canonical file, and the two are constantly reported as though they were the same document.

The number everyone quotes is not a measurement

You will see this everywhere: a 41% mistake rate with no CLAUDE.md, 11% with the four rules, 3% with the extended twelve. It is on aggregator sites, in newsletters, and in at least one exchange's news feed.

It does not appear in the repository. There is no study, no dataset and no published methodology. Tracing it back, it originates in a single social post describing an informal personal test: roughly 50 tasks across 30 codebases over six weeks, self-reported, with no control group and no definition of how a "mistake" was counted. Even sympathetic write-ups of it note that the figures inside the original article contradict each other.

That does not make the direction wrong. An agent given repository context almost certainly does make fewer wrong assumptions than one given none, and every experienced user reports as much. But "fewer mistakes, in my experience" and "38 percentage points" are different claims, and only one of them is doing any work. If you are choosing what to put in a file that loads on every single turn, you should know which one you are acting on.

What the person who built Claude Code actually does

Boris Cherny created Claude Code at Anthropic, so his setup is worth more than most opinions about it. It is not a rules arms race.

He has described moving past prompting altogether: "Now it's actually leveled up, I think, again, to the next wave of abstraction where I don't prompt Claude anymore. I have loops that are running." In December 2025 he reported not opening an IDE once, with Claude Code producing 259 pull requests that month. He runs several instances in parallel, starts most sessions in plan mode so the approach is agreed before any code is written, and uses a second instance to review the first one's output.

The consistent detail across every account of his setup is that it is close to vanilla. Plan mode, parallel sessions, hooks that format code after an edit, and a habit of writing each mistake into the instruction file so it does not recur. Not a twelve-point behavioural constitution.

These reports are secondhand. The quote above is carried by several outlets, none of which names the original interview, so treat the exact wording as reported rather than transcribed.

The test a rule has to pass

Here is the useful reframing. A coding model already knows how to write clean code, avoid speculative abstractions and keep diffs small. Telling it so costs tokens on every turn and tells it nothing it did not already know. The rules that earn their place are the ones encoding what the model cannot infer from your repository.

The test: could a competent engineer work this out in ten minutes by reading the code? If yes, delete the rule. If it took someone a painful afternoon and a broken deploy to discover, write it down.

This site's own CLAUDE.md is a worked example, and it is short. Its two hard rules are "never hand-edit generated data" and "never hand-type a number or a date". Neither is a general principle about good engineering. Both exist because of specific failures on this repository: a directory page that claimed fourteen categories when there were fifteen, an author page reporting 212 briefings across 148 days when it was 214 across 149, and category tiles naming three top models that the ranking underneath them disagreed with. The rule is followed by a table of where each number is injected from, because the rule alone would not have prevented the next one.

That file is 151 lines and roughly 1,600 tokens. It survives because everything in it was paid for.

What it costs, which nobody mentions

The instruction file is prepended to context. It is not free, and it is not paid once.

A 1,600-token file across a 40-turn session is 64,000 tokens of instruction before a single line of your actual code is read. At Claude Opus 5's published input price of $5 per million tokens that is about 32 cents a session, which is trivial. The cost that is not trivial is attention: every rule competes with your actual task for the model's focus, and a file long enough to state twelve behavioural principles is long enough to bury the one line that says which directory is generated output.

This is the argument against the maximal template, and it is the same argument as the one for it. More context helps, until the signal you needed is sitting in the middle of forty lines that the model already knew.

Which file do you actually need

The last two are the ones the four-rule template genuinely does not cover, and they are real gaps rather than invented ones. An instruction to "loop until verified" assumes the session reaches the end. It says nothing about what should happen at step four of eight when context has degraded and the model is now verifying against a fuzzy memory of the original task.

Write it the way you would write a postmortem

The habit that produces a good file is not choosing a template. It is writing down each failure the first time it costs you something, in the smallest form that would have prevented it, and deleting anything that has not earned its place.

Every rule in a file built that way has a story behind it, which is also the test for whether it should still be there. If nobody can remember why a line is in your CLAUDE.md, that line is costing you attention on every turn and buying nothing.

If you are running models locally rather than through an API, the same discipline applies to the harness around them: see how to run AI models locally. For what the current coding tools actually score, the hand-ranked coding tools list carries SWE-bench Verified figures with the date each one was published.