The 3-line CLAUDE.md

Anthropic deleted over 80% of the instructions they wrote for Claude Code. Their coding scores came back the same.

That result should change how you look at your own instructions file. Most of what we write in CLAUDE.md isn't helping — it's weight the model carries into every single request. This is the shape Anthropic moved to, and how to find what to cut in your own setup.

The one rule

If Claude can work it out by reading your repo, delete the line.

That covers most of what people put in these files. Your folder structure. What the project does. Which framework you use. Where the components live. Claude opens the files and sees all of it — writing it down again just adds words that can contradict something else later.

What survives is the stuff Claude genuinely cannot see: your gotchas, and your taste.

The three buckets

Go through your instructions file line by line and sort every rule into one of these.

Delete. Anything your file tree, package.json, or a quick read of the code already says. Descriptions of your architecture. Restatements of your framework's defaults. Lists of what folders exist.

Keep, but move. Long, situational guidance that only matters for one kind of task. Verification steps. Review checklists. Deployment procedures. These belong in their own file that gets pulled in when the task calls for it — not in the file that loads every single time.

Keep in place. Short, surprising gotchas. The trap someone hits once a month. "Types live in one monolithic file and nowhere else." "The staging database is not a copy of production." These are cheap to state and expensive to discover.

The shape

A small entry file that points at a tree, instead of one long file that carries everything:

CLAUDE.md              3 lines. What this repo is. Where to look next.
AGENTS.md              the gotchas. Short. Only what the code cannot tell you.
.claude/skills/
  verify/SKILL.md      loads when it is time to verify
  deploy/SKILL.md      loads when it is time to deploy
  review/reference/    the long detail, split into separate files

The entry file stays tiny on purpose. Everything underneath it costs nothing until the moment it's relevant.

What mine looks like now

This site's repo runs on exactly this shape. CLAUDE.md is a single line pointing at AGENTS.md. AGENTS.md is three lines with one gotcha: the Next.js version here has breaking changes, so read the docs bundled in node_modules before writing code. No file-tree description, no framework summary, no style guide. Claude can see all of that by looking.

Let it find the deletions for you

Claude Code has a built-in check for exactly this. Run /doctor in an interactive session and it proposes trimming your checked-in CLAUDE.md by cutting content Claude could work out from the codebase itself.

Run it the right way, because two different things are called doctor:

• /doctor — typed inside a Claude Code session. This is the one that proposes trims.
• claude doctor — run in your shell. This is the install health check, which will just tell you your install is fine.

It also needs version 2.1.206 or newer, so run claude update first. And it's a terminal command — it won't appear in the desktop app.

The check handles the obvious deletions. The contradictions below are the part you still have to find yourself.

Find your own contradictions

This is the part that actually bites, and it's easy to miss because each rule looks reasonable on its own.

1. Print every instruction file you load. Your CLAUDE.md, your AGENTS.md, every skill file, every saved memory.
2. Group the rules by subject. All the ones about comments together. All the ones about tests together. All the ones about how much detail to write.
3. Read each group as if you had to satisfy all of it at once. Where two rules pull in opposite directions, you've found one. Delete the weaker rule, or write the actual condition that decides between them.

Anthropic found this in their own setup: one instruction saying "leave documentation as appropriate" sitting alongside another saying "DO NOT add comments" — both arriving in the same request. When that happens, the model spends its effort deciding which rule wins instead of doing the work.

What changed, in plain terms

Rules became judgement. Blanket bans written to prevent worst cases block the reasonable exceptions too. Their old prompt said write no comments, ever. The new one says match the comment density of the surrounding code.

Examples became interfaces. Giving Claude examples of how to use a tool narrows it to that one path. Make the tool self-explanatory instead — a status field that only accepts pending, in progress, or completed teaches its own usage.

Front-loading became progressive disclosure. Load context when the task needs it, rather than stuffing everything into one file up front.

Repetition became one clear place. Say it once, in the description of the thing it applies to.

Manual memory became automatic. Claude now saves what's worth remembering on its own.

Plain specs became rich references. A test suite, a working function in another codebase, or an HTML mockup gives Claude far more to work from than a paragraph describing what you want.

Two things worth knowing

This is not an argument for a shorter setup. It's an argument for a different shape. A tiny entry file pointing at a deep, well-split tree is exactly right — and the tree can be large.

And hard rules still belong in your setup where they encode taste you learned the hard way. A constraint that came from a real failure is not clutter. Just make sure it lives in a file that loads when it's relevant, and that nothing else in your setup argues with it.

Sources

• Anthropic, The new rules of context engineering for Claude 5 generation models (July 24, 2026) — full post
• The /doctor trimming check landed in Claude Code 2.1.206. If yours does nothing useful, you're on an older version — run claude update.