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.