What should actually go in your CLAUDE.md? | Zander Martineau

If you go looking for advice on how to write a CLAUDE.md file, you’ll find plenty of it. You’ll also find that a lot of it disagrees. One post tells you to use a ten-section template covering your project overview, tech stack, commands and coding standards. Another tells you to keep it under sixty lines. The official docs tell you to ruthlessly prune. And the person who created Claude Code has, in the space of about seven months, publicly recommended both “add a rule every time Claude gets something wrong” and “delete your CLAUDE.md every six months”.

None of these people are wrong, exactly. They’re mostly right about different moments in time. Context files are one of the fastest-moving bits of practice in this whole space, and almost nothing you read is dated clearly enough for you to work out which era it belongs to.

So I did the research, and this is the map. Every claim here is pinned to a date and a source, because the date is the important part.

TL;DR

The current consensus is minimalism. CLAUDE.md is loaded into every single conversation, so it should contain only rules that apply universally. Everything conditional belongs in a skill.

The biggest live conflict is accretion vs ablation — growing the file by adding a rule every time the model slips, versus periodically deleting the lot and adding back only what you demonstrably need. It’s the same team contradicting itself across model generations: accretion was the practice through mid-2026, ablation is the advice post-Opus 5.

Much of the newest advice is calibrated to Opus 5 specifically. The portable version: the scaffolding you need is inversely proportional to how capable your model is. Weaker model, more rules — but a tighter budget to fit them in.

Anything you want guaranteed doesn’t belong in prose at all. CLAUDE.md is advisory; hooks are deterministic.

The research is thinner and less flattering than the blog posts suggest. Developer-written context files help a little. LLM-generated ones (hello, /init) measurably hurt. Most of what /init writes — the overview, the architecture summary, the file map — should go. The commands and the genuine gotchas should stay.

There’s no way to make CLAUDE.md conditional on the model — subagents on cheap models load the identical file. You can make it conditional on file path (.claude/rules/ with a paths glob), on task (skills), and on person (CLAUDE.local.md). Per-model instructions go in the subagent definition that pins the model.

AGENTS.md is the cross-tool standard that nearly everything except Claude Code reads natively. The fix is one line: put @AGENTS.md at the top of your CLAUDE.md.

Two words I’m going to keep using

These aren’t my coinages — they’re the vocabulary Anthropic and the Claude Code team use themselves, which is why I’ve stuck with them rather than reaching for “adding stuff” and “deleting stuff”:

Accretion<br>Growth by gradual accumulation. Applied to a CLAUDE.md: every time the model does something you didn't want, you add a line telling it not to. The file only ever gets longer, and each rule is a scar from a specific past mistake.<br>Ablation<br>Removal — deliberately cutting material away to see what happens without it. Applied to a CLAUDE.md: you delete the file (or all of it bar a line or two), work normally, watch where the model actually struggles, and add back only the rules that earn their place.

Ablation in particular is a deliberate borrowing. It’s the standard term in machine learning research for removing a component of a system to measure its contribution, and it’s the word Anthropic uses for what it did to Claude Code’s own system prompt — delete a part, measure, keep the deletion if nothing gets worse. Applying a research technique to your own project file is exactly the point.

On the accretion side, the team’s own name for the practice is compounding engineering (a term they credit to Dan Shipper): every correction compounds into a permanent rule, so the system supposedly gets better with every mistake it makes. Accretion is the plainer description of what that does to the file.

Hold onto both — they’re the whole story of the last seven months.

The one big inversion

Start with the conflict that explains most of the others.

Boris Cherny created Claude Code at Anthropic in September 2024 and still runs it. His public advice is the closest thing this space has to primary source material, and it inverted itself in about seven months.

January 2026 — accretion. Describing the Claude Code team’s own shared CLAUDE.md, checked into git and edited multiple times a week:

Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.

Later the same month, a companion tip: after every correction, end your message with “update your CLAUDE.md so you don’t make that mistake again”. The team even tagged @.claude on pull requests to fold review learnings back...