Opus 5 and Sonnet 5 Need Opposite CLAUDE.md Best Practices

Say "fix the heading" to Opus 5 and it will often change other things nearby. Say the same words to Sonnet 5 and you get exactly one heading. Both are behaving correctly. If you run a heavier model for the main work and a cheaper one for the small stuff, then both of those behaviors are live against one file, and the CLAUDE.md best practices that steer one of them point the wrong way for the other.

Key Takeaways

Opus 5 widens scope and Sonnet 5 narrows it. The first needs a boundary written down, the second needs the job spelled out item by item.

Instructions expire. A rule that fixed a real model weakness a year ago is often a tax today, and nothing errors when that happens.

Anthropic's Opus 5 guide says to remove "check your work before you finish" instructions. The model already does it, so the line buys a second pass you pay for.

Telling a code review step to be conservative or to only report high severity issues now gets followed literally, and real problems go missing.

Audit when your hooks run, not just what they check. A rule pointed at an event you never trigger has never run at all.

Short on time? Jump to the four step audit, which is the part to act on today.

How Opus 5 and Sonnet 5 Fail in Opposite Directions

The two models fail scope in opposite directions, and no CLAUDE.md template I have seen accounts for it.

You type	Opus 5 does	Sonnet 5 does
"Fix the heading"	Changes other things nearby too	Fixes exactly one heading
"Tidy these files"	Finishes each one, no half done pieces, which is the same widening working for you	Does the first one and stops
Same job, effort turned down	Holds up fine	Risks under thinking it
No instructions at all	Writes long	Writes to fit the job

Rows three and four come straight from the guides. The first two are what the guides' scope warnings look like on an ordinary Tuesday, from running both models daily.

Anthropic's Opus 5 guide says the model can expand the scope of a task, adding steps that were not requested, and that narrow tasks need their scope constrained explicitly. Its Sonnet 5 guide says the opposite thing about the opposite model: Sonnet 5 interprets prompts literally and does not silently generalize an instruction from one item to another, so the scope has to be stated.

One fills in the gaps you left. The other leaves them exactly where you left them. Both behaviors are correct, and a single file is being asked to serve both.

The shape that resolves it: the orchestrator needs a fence, the worker needs a checklist.

For the model running your session, write the boundary. Say where the job ends, say when not to hand work off to helper agents, and ask it to keep files short. For anything you dispatch to the cheaper model, write the scope out in full. Say "every file in the list, not just the first" and "all six sections", because it will not extend one instruction to the next item on its own.

Effort splits the same way, and it is the dial to reach for before switching models. Anthropic's guide says low and medium effort on Opus 5 produce strong quality at a fraction of the tokens. The Sonnet 5 guide warns the other way: that model respects effort levels strictly, and at low effort on moderately complex work there is some risk of under-thinking. So step Opus down freely on mechanical stretches, and leave dispatched Sonnet work high. In Claude Code, run /effort and pick a level. It applies to the session you are in.

If you want more on the heavier model on its own, I wrote up the Opus 5 prompting changes separately.

Why CLAUDE.md Best Practices Changed

CLAUDE.md is the file Claude Code reads at the start of every session, so every line in it sits in the context on every turn. That much has always been true. What changed is that the models got good at things your file was written to compensate for.

Boris Cherny, who created Claude Code, said as much in his Startup School talk at Y Combinator in 2026: every six months, delete your CLAUDE.md, delete your skills, delete your hooks, and see what happens. His reasoning, as reported from that talk, was that those files were written to compensate for weaknesses in older models that no longer exist.

Anthropic put a number behind the same idea. In its context engineering post it says it removed over 80% of Claude Code's own system prompt for models like Opus 5, with no measurable loss on its coding evaluations. That is Anthropic's own scaffolding rather than yours, and the same pressure applies to your file for the same reason: the instructions were doing work the model now does without them.

I have more than twenty projects and I was not going to delete all of that on a Tuesday. So I did the smaller version: I read Anthropic's guide for Opus 5 and its guide for Sonnet 5 side by side with my own files, and looked for lines that were no longer true.

Four Rules Worth Removing From Your CLAUDE.md

Three of these come straight from Anthropic's guides. One is my read of them, and the last column says which is which. Which model each rule applies to is in the middle column, because that is the part most likely to differ from what you assumed.

Rule in your file	Why it is now a cost	Sourced to
"Verify your work before saying it is done"	Opus 5 verifies its own work unprompted, so the line buys a second pass that eats your usage window.	Opus 5 guide
"Summarize your progress every few steps"	Sonnet 5 calibrates its own reporting. Opus 5 is the reverse case: it runs long, so it wants a keep-it-short line instead.	Both guides
"Switch the whole session to a cheaper model for simple work"	Effort is the cheaper dial and it keeps your context. Handing one job to a cheaper model is a different move and still a good one.	My read of both effort sections
"Only report high severity issues" in a code review step	Followed literally, so findings that would have been reported get dropped before you see them. Precision rises, recall can fall.	Both guides

That last row is scoped to code review harnesses in both guides, and it is exactly the shape of what I found in my own setup.

My code review step is a hook that runs a model over the diff before code reaches main. The model scores each finding out of 100 for severity, and anything at 80 or above blocks the push. The prompt told it to score conservatively and to drop anything it was not sure about. Fifty five lines later in the same file, my script dropped everything under 80 anyway.

Two filters, stacked. Anything borderline died twice, and a borderline finding is exactly what a subtle bug looks like from the outside. A gate like this reports clean either way, which is what makes it hard to catch. Nothing errors, because nothing is broken in the sense that produces an error.

The fix was to move the filtering out of the model entirely. The model's job is coverage, the script's job is the bar. The rewritten prompt says to report every issue inside the review scope including ones it is unsure about, because a separate step already drops everything below 80, so a finding surfaced at 45 costs nothing. Fed a test diff with three planted problems afterwards, it returned all three: an off by one at 95, a swallowed error at 85, and an unused constant at 40 that the script correctly filtered out.

The general rule: a quality gate that silently degrades is worse than no gate, because you stop checking the thing you believe is already checked.

Audit When a Rule Runs, Not Just What It Says

Once the review prompt was fixed, the better question was not what it checks. It was when it runs.

It was wired to gh pr create. That is the only event that triggered it.

Checking it against merge history, the step was live on four projects and dead on four others, including this website. The dead half is where I work most, because those repos ship straight to main and never open a pull request. So on those four, neither the secret scan nor the code review had ever run. Not once. The logic was correct, well built, and pointed at a door nobody walks through.

The fix was to add git push as a second trigger, but only when the push lands on the repo's default branch. That is the equivalent moment on a direct-to-main workflow. Feature branch pushes stay quiet, because pushing work in progress is not the same as releasing it.

A rule is only as good as the event it hooks. The instruction is the easy thing to read. The trigger is the thing that decides whether the instruction ever runs, and it is the half that is easy to skip. The logic problem narrowed what the review would report. The trigger problem cost me every finding on the four repos I touch most.

So when you audit, open your hooks and read the event, not the instruction. This applies to Claude Code settings generally: a setting you never reach the condition for is the same as one you never wrote.

What `/doctor` and `/insights` Do Not Ask

Two built in commands cover neighboring ground, and both are worth running before the audit below. It is worth being precise about where each one stops.

/doctor is no longer only an install health check. It looks for skills, plugins and connected tools you never use, for a local CLAUDE.md that repeats what a checked-in one already says, and for lines Claude could work out by reading the codebase itself.

Run on this machine, it reported 13,900 tokens of memory files loading every session, 7,500 of that in a single file, my global CLAUDE.md, before I had typed anything.

Every one of those checks is about size. Is this duplicated, is this unused, is this big. All good questions. None of them is: is this line still true. Your CLAUDE.md can be perfectly lean, nothing wasted, nothing duplicated, and every rule in it written for a model you stopped running eight months ago. /doctor will tell you the file is the right size. It will not tell you the rules are out of date.

/insights asks a different question again. It reads how you have actually been working and where you kept hitting friction, and it gave me four things worth adding. But notice what it needs: you have to have hit the friction. It finds what you already noticed.

The problem this post is about never shows up as friction. Nothing breaks, nothing errors, there is nothing to notice.

How to Audit Your CLAUDE.md in Four Steps

Open your CLAUDE.md and look for four things. This takes about twenty minutes and does not need any tooling.

Find self-verification instructions and, if you run Opus 5, delete them. Any line telling the model to double check, verify again, or confirm before finishing. Opus 5 does this unprompted, so the line buys a second pass out of your allowance.
Find progress narration rules and delete them. Anything asking for a summary every few steps. Then, if you run the heavier model, add a line going the other way asking it to keep responses and files short. Same subject, opposite direction.
Find rules written for an older model. Ask what each line is compensating for. If the answer is a model weakness, check whether that weakness still exists. If the answer is a fact about this project, why a workaround is there, which command actually runs the tests, it stays no matter how old it is.
Read your hooks for when they fire. They live in your Claude Code settings file, listed by the event that triggers them. Read that event, not what the hook checks, and ask whether you ever trigger it on the projects you care about.

A tidy file with one stale rule in it beats any tool run against a file nobody has read.

Everything in this post came out of doing exactly that on my own machine. If you want to work through the same audit on your own setup with help, that is the kind of thing my AI workshop covers.

Frequently Asked Questions

How long should a CLAUDE.md file be?

Short enough that you can read the whole thing. Every line sits in the context on every turn, so length is a standing cost against the window, not a one time one. Length is the wrong first question though: a file can be lean and still be full of rules that no longer apply. Cut for staleness before you cut for size.

Should I delete my CLAUDE.md entirely?

Only as an experiment, and only if you can restore it. The value in deleting it is finding out which rules the model no longer needs, which is information you cannot get any other way. Running without a file permanently gives up the genuinely project-specific things Claude cannot work out on its own, like why a workaround exists or which command actually runs your tests.

How do I write one file that serves both models?

Keep them apart on the page rather than blending them. One short section holds the rules for the model running your session, which is where the boundary goes. A second section holds the rules for work you hand off, which is where the spelled out scope goes. A single merged instruction ends up too loose for one model and too tight for the other, and you cannot tell which from reading it.

What about skills and hooks, do those go stale too?

They go stale faster, because they are longer and get read less often. A skill written around a model's old weakness carries that assumption every time it loads, and a hook can be worse still: it can be correct and simply never fire. Audit the trigger before you audit the contents. The skills best practices post covers how to write the skill itself.

Does `/doctor` already do this?

No. Run it first anyway, because it shrinks the file, and a shorter file is faster to read for staleness afterwards. What it cannot tell you is that a rule is out of date, which is the check this post is about.