Opus 5: Delete your CLAUDE.md?

Last week Y Combinator posted an interview with Boris Cherny, the engineer who built Claude Code, about the new Opus 5 release (the full talk). It was running in the background, and I was only half-listening right up until he told the room:

...delete your CLAUDE.md, delete your skills, delete your hooks...

Whoa! What?! Let's rewind ... maybe I heard it wrong:

...for people that aren't building agentic products but you're using Claude code, every 6 months delete your CLAUDE.md, delete your skills, delete your hooks. See what the model does and it might surprise you. And actually for Opus 5, this is something we really do recommend is just try deleting all of these things because the model might really just not need all those instructions that you needed for past models. (6:57)

All righty then, time to re-watch the whole thing.

What was in the video

Earlier in the same conversation the host puts a number on what Anthropic did to its own house: "You actually deleted over 80% of the system prompt from Claude code" (3:31). Boris gives the reason in the same breath. Opus 5 is "just really intelligent," he says, and "a lot of the stuff in the system prompt was correcting for these behaviors that the model should have known," but "it didn't." Then: "Now, Opus 5 just does it" (4:18). Most of what got cut was scaffolding propping up a weaker model, and the propping stopped being load-bearing once the model could stand on its own.

So how did Anthropic make that cut? Internally it was an ablation: "you delete the entire system prompt and then you bring it back line by line to figure out what is the impact of each individual line" (6:03). One line at a time, each with a measured before and after. By the time it reaches the developer in the room it has compressed down to "just delete and see."

So why does the model that shipped this summer make the instruction file you tuned against 4.x behave so differently?

What Opus 5 changed about your instructions

I work on deterministic instruction evals, no LLM-as-a-judge, so I took a deeper look at what is happening and why, and at how to review your own instructions so you get the upgrade instead of a regression. Three mechanisms in this model generation change how a file you wrote a year ago lands, and they compound.

Instruction retrieval strength

It reaches for instructions over a wider range now, so even the vague and abstract rules that used to sit dormant fire on tasks they were never written for. And a vague rule names nothing concrete to bind to, so when it fires the model fills the gap with its own judgment instead of the outcome you intended.

LLM-as-a-judge, baked in

An LLM-as-a-judge pass is baked in, generally a bad idea in my view. It evaluates and re-checks its own output by default. Your old "verify / double-check" lines stack on that and it over-verifies, and over-verification pulls more instructions onto the turn, sharpening the same competition wider retrieval already set off.

Long-horizon tasks

Opus 5 runs long-horizon tasks now, what Boris calls auto mode. Connect that to the two mechanisms above and the same problem returns: the longer the trace, the more the model's own generated steps and assumptions crowd out your instructions, and the weakest go first.

Put the three together and a CLAUDE.md that behaved on 4.x can feel like it quit working on 5 without you touching a line of it. Remove the file and the noise goes at once, which is exactly why "just delete" feels like it works.

Boris is 73% right

Delete-the-bloat is sound advice, because most of your instruction file was never instruction. We pointed a deterministic analyzer at roughly 30,000 public repositories carrying agent instruction files and read every one the same way, no model in the loop, same file same result every time. The headline from that report: "Only 27% of your instruction file is doing what you think it does. The other 73% is scaffolding" (The State of AI Instruction Quality). Headings, restated context, examples, prose that arranges the file without ever telling the model to do anything. An independent ETH Zürich study of repository context files draws the same line: the instructions get followed, while the descriptive overviews, exactly the scaffolding we are talking about, do not improve results and add over 20% to inference cost (Evaluating AGENTS.md). Boris cut 80% of Claude Code's own system prompt, scaffolding his model had outgrown. Our data says roughly three-quarters of the average developer's CLAUDE.md is dead weight too, and it was dead well before Opus 5 shipped.

The 27% that is left is in worse shape than the ratio suggests. In the same corpus, 89.9% of agent configs carry at least one instruction that never names what it means (The Undiagnosed Input Problem), a rule like "keep the code clean" that reads fine to a person and binds nothing in the model. It is nearly everyone. Those figures are the Q2 2026 read; the Q3 report is in the making.

Delete is a blunt tool

Boris's method is ablation, the same move Anthropic used on its own prompt: delete the file, then add a line back only when a failure keeps recurring, never speculatively. When you are not time and token constrained, it is a sound method. What makes it the wrong answer for you is what it cannot see and what it costs to run.

What it cannot see

Start with what the add-back loop is buying: which rules were load-bearing. That is already a readable property of the file. An instruction that names the exact construct it is about gets followed with roughly a 10.9x odds ratio over the same rule stated as a category; when two rules contradict, the model lands hard on one and drops the other; and whether a rule loads where it applies is a fact about the text. Delete-and-observe ships a production failure to learn what a static read hands you for free.

It also learns only part of it. The loop restores a rule when a failure recurs and you can trace it, but two of the three defects never fail that cleanly. A low-specificity rule does not break, it underperforms silently, followed some of the time and not others. A conflict resolves silently too: Opus 5 follows the latest instruction in the set, and the losing rule reads as "ignored," which looks like flakiness rather than a diagnosable stumble. So the rebuild quietly puts the vague and conflicting rules back, because nothing in the delete-observe-add loop measured their quality. Deletion only ever touched the third defect, bloat.

There is also a category error sitting inside the delete list, because it runs past the CLAUDE.md to the skills and the hooks. A hook is a deterministic gate: it refuses an action outright rather than asking the model to weigh a sentence, and a deny-rule, a destructive-command block, or a compliance check does not get less necessary because the model got more capable. Enforcement never rode on the model's judgment in the first place, so a model upgrade does not retire it, and its absence does not surface as a gentle stumble the add-back loop catches. It surfaces as the destructive command that goes through. Cut the prose the model has outgrown, and keep the gate. I made the fuller case for that split in a separate piece: prompts steer, hooks enforce.

What it costs

Relearning which rules mattered by removing them and letting the model break is a fair trade when you are not time or token constrained, and for an Anthropic power user on a near-unlimited budget a rediscover-by-failure loop is background noise. For a developer on a normal budget it is not, and the cost is never one file. Picture running the ablation on every memory.md reference, every CLAUDE.md, every rule, skill, and agent, one by one, across every project you work on. Deleting a rule and waiting for the stumble means learning what your instructions were for by watching your own work break, one failure at a time, and you end up relearning the file you already had, minus whatever did not happen to break during the window. A static read tells you which rules bind without shipping a single failure to find out.

How to approach it

So read the file, do not shrink it. Opus 5 is more punishing when it meets faulty instructions, so the job is diagnostic: fix the rules that misfire, write the rest so a literal reader cannot misread them, and repeat.

Fix what you are seeing

Each of these is a failure you can watch for, with the remedy beside it:

• Long answers, paragraphs for trivial steps. Instruct for brevity per surface: one line for chat replies, one for step-by-step narration, one for files it writes to disk, which run long on their own. effort changes thinking depth, not output length, so lowering it will not shorten any of them.
• Scope creep, does more than you asked. State the scope in one line and let it make routine calls itself, checking in only when two readings would lead to materially different work. Scope is a judgment, so it steers rather than gates; the one enforceable slice is a write-path allowlist that refuses edits outside the files the task named.
• Over-obeying a limiter. A hedge carried from a 4.x file now gets followed literally and under-reports. Anthropic flags it for Opus 5: a review prompt that hedges with only report high-severity issues or be conservative gets followed literally and reports less. Ask for everything and filter in a second pass.
• Compulsive self-checking, corrections you did not ask for. Delete lines like double-check your answer or use a subagent to verify. Anthropic says the same: Opus 5 verifies its own work without being told to, and those instructions only cause over-verification. Do not read that as self-verification you can trust, though, its check is narration (see the last item).
• Old 4.x instructions misfiring. Do not wipe them by vintage, you cannot see a rule's age, and blind deletion is the reflex this whole piece argues against. Target the classes Opus 5 inverted instead: verification prompts, be conservative hedges, do not think rules, effort defaults. Test each and keep what still binds.
• Thrashes on conflicting rules. In a contradiction Opus 5 follows the latest rule and drops the other, and position decides which, so you cannot fix it by reordering. Find the contradiction and remove it; the pass that finds it checks same-subject rule pairs for "can both hold at once," not the file top to bottom.
• A vague rule misfiring on unrelated tasks. Wider retrieval now fires a rule that used to sit dormant. Name its construct or scope it to a path so it stops loading on every turn.
• Over-eager subagents. Cap it, this is a cost problem, not a quality one. Delegate only large, genuinely independent tracks, and never spin up a subagent to verify your own work.
• Confident wrong assumptions, "done" when it is not. Steer it to state assumptions and flag gaps, then do not take its "done" on faith. Re-run the goal at the finish against a held-out check it never saw and cannot edit, and let it refuse and escalate when it cannot confirm.
• Effort carried over from a 4.8 habit. Opus 5 defaults to high and adds an xhigh tier above it. If you had set effort explicitly for 4.8, Opus 5 leaves that setting unchanged rather than swapping in its own default, so a value you tuned for 4.8 is still live until you change it. Re-run an effort sweep: low and medium hold quality for most work, and xhigh earns its cost only on demanding agentic runs.

Write rules it can follow

The more interpretation you leave, the more Opus 5 fills the gap with its own judgment, which it does confidently and with the quality that got you here. So be specific, be imperative, and put one instruction per line. In a controlled experiment, naming the exact construct a rule is about is what separates Format with ruff format before committing from keep the code clean: the same rule to a human, wildly different compliance from the model.

When you write a constraint, order it. Lead with the directive and name the exact construct to use. Add one line of reasoning that reinforces it, and keep that line from re-naming the thing you are banning. Put any prohibition last and phrase it at the category level: under a crowded instruction file, naming the forbidden API anchors the model on it and the ban backfires, and on Opus 5 that bites harder. One imperative, one line of context, one restriction, in that order:

• Lead every reply with the outcome: put the answer or the finding in the first sentence.
• A reader who gets the result first can act on it right away and reads the rest as support.
• Do not open with preamble, a recap of the request, or status narration.

The rules worth keeping share properties you can check without running the model even once:

• They name a construct. Format with ruff format before committing, not keep the code clean.
• They do not contradict each other. Two rules that disagree do not average out; the model follows one and drops the other, and you do not pick which.
• They load where they apply. A rule about src/payments/ belongs in a file scoped to src/payments/, not on the always-on surface that taxes every unrelated turn.
• They are behavior you want enforced, not documentation the model can read off the codebase.

Notice that "how many rules" is not on the list. A file of forty rules that all name constructs, none of which conflict, each scoped to where it applies, beats a file of eight vague ones every time. Count is downstream of quality.

Review it, don't let it grade itself

Anthropic makes the same case and ships a tool for it. Their context-engineering guidance for the Claude 5 generation says they found they were overconstraining Claude Code through the system prompt, the CLAUDE.md files, and the skills, and could delete many of those instructions and let the model use its judgment. They put the resulting best practices into a command: /doctor in Claude Code, to rightsize your skills and CLAUDE.md. Run it. It cuts what Claude can derive from the codebase, directory layouts, dependency lists, architecture overviews, keeps the pitfalls and the conventions that differ from tool defaults, and moves the rest into files that load on demand.

What /doctor rightsizes is bloat and placement. What it does not do is score the rules it keeps. Whether a rule names its construct, contradicts another, or loads where it applies is a property of the text with a definite answer you can compute by reading, and none of the three is what a bloat-trim measures. The trap is reaching for the model to close that gap. Asking Claude to grade its own rules runs straight into the LLM-as-a-judge and self-verify loop Opus 5 already applies to its own output, a stochastic guess on a question that has a deterministic answer. On a 200-line file that judge makes 200 of these calls, and its chance of getting the whole file right falls with every rule added, exactly where you reached for it.

So run /doctor first, then measure what it kept. Run a deterministic checker over your CLAUDE.md and rules, score them, and fix the vague and conflicting ones. I built one; any AST or deterministic instruction checker finds these defects.

Read the file, don't guess

Delete the bloat, genuinely. Then, before you add anything back on a feeling, measure what is left: whether each rule names what it means, whether it fights another rule, whether it loads where it belongs. Those three are readable off the file, and they are exactly what blind deletion cannot see. You keep what binds, cut the text that was never doing anything, and can say which is which instead of guessing.

I work on Reporails, deterministic diagnostics and governance for the instruction files, rules, and prompts that steer coding agents. It reads the steering surface you wrote down and tells you, with measured evidence, which instructions couple to behavior and which are text the model can ignore. It does not run your model, and it does not vote; it measures the file.