CLAUDE.md After Opus 5: Why Long Instructions Now Get in Claude’s Way

Information about working with Ailoot is available in the documentation.

What changed in Claude after the release of Opus 5?#

Opus 5 came out on July 24, 2026, and immediately became the default model in Claude Code. The model itself—its price, benchmarks, and effort modes—is covered in detail in a separate guide, “Should You Switch to Claude Opus 5?”. This article is about something else: the model’s release also changed how to talk to it effectively.

Anthropic published an analysis on the Claude blog. Its main point goes like this:

The key phrase is “constraining too much.” When models were weaker, they needed scaffolding: do this, don’t do that, here’s an example, repeat it once more. Opus 5 no longer needs that scaffolding, and worse, it can start getting in the way. Anthropic states the new principle simply: let Claude use its own judgment.

What does that mean for you in practice?

• Your CLAUDE.md is the same kind of system prompt, but for your project. If Anthropic cut its own by 80 percent, yours is probably bloated too.
• Long lists of rules no longer guarantee compliance. On the contrary, the more lines there are, the less closely the model follows them (more on this below, with figures from the documentation).
• New mechanisms have appeared—automatic memory and skills—that take over some of the work you used to have to spell out manually in CLAUDE.md.

The main point: the most important work happens before the prompt—in what you put into the model’s context before the first request. The Opus 5 update is essentially Anthropic’s official confirmation of the same idea. This time, though, it comes with concrete figures and new tools. I’ll go through each in turn.

Why does a long CLAUDE.md get in the way now?#

Here’s how it works. CLAUDE.md is a file of rules that Claude reads at the start of every session. A separate guide, “How to Set Up CLAUDE.md”, explains how to build one from scratch; this article is about the reverse: what to remove from it now. Everything you write there enters the context before your first request and stays there throughout the conversation. Context isn’t infinite—and every extra line of rules takes up space that could have gone to your task.

The Claude Code documentation puts it bluntly:

The second point matters more than the first: long files reduce instruction-following. The model starts listening less closely. This is a trap almost every beginner falls into. The logic seems ironclad: I want Claude to listen to me, so I’ll write more rules. In practice, the opposite happens. The longer the list, the more scattered the model’s attention, and the more often it skips a rule.

Here’s how the approach has changed:

There’s a second problem too: contradictions. As a file grows, it almost inevitably accumulates rules that conflict with one another. One place says “always write tests,” another says “don’t touch the tests folder.” The documentation warns that if two rules contradict each other, Claude may pick either one at random. In other words, an overgrown file makes the model’s behavior less predictable.

A simple rule: CLAUDE.md is a short note about what Claude can’t infer on its own. Anything beyond that only takes up its attention.

What should you keep in CLAUDE.md, and what should you remove?#

The documentation gives a clear criterion for deciding whether a rule deserves a place in CLAUDE.md. Add it if:

1. Claude made the same mistake for the second time.
2. A code check caught something the model should have known about this project.
3. You’re typing the same correction into chat for the second time.
4. A new person on the team would need the same context to avoid breaking the project.

The general principle is to keep project-specific pitfalls and remove the obvious. Claude Code even has a built-in claude doctor check that suggests cleaning up an overgrown CLAUDE.md. It cuts details the model can infer from the codebase—folder structure, dependency list, architecture overview—and keeps pitfalls, rationale, and conventions that differ from the defaults.

The second important rule is specificity. Vague wording doesn’t work. Compare:

The difference is simple. The model can interpret “format it properly” any way it likes. “Use a 2-space indent” can be checked unambiguously. Every rule in CLAUDE.md should be something you can verify and see—whether it was followed or not.

And third, remove the obvious. If you write “write clean code” or “follow best practices” in CLAUDE.md, that’s noise. The model already knows that, and the line takes up space and scatters its attention. Anthropic explicitly advises against spending context on obvious things.

Where should you move rules that don’t fit in CLAUDE.md?#

This is where the most underrated tool comes in. If all instructions used to have to stay in CLAUDE.md, long procedures now have a home of their own: skills. A separate guide, “How to Choose Claude Code Skills”, explains how to choose the right ones without adding too many.

The difference is fundamental. CLAUDE.md is loaded in full at the start of every session. A skill isn’t. The documentation puts it this way:

This is called progressive disclosure—loading information as needed. The idea is to give the model context in portions, at the right moment. Anthropic moved its detailed instructions—for example, instructions for code review—into skills and removed them from the system prompt.

The criterion for moving something into a skill is simple: a section of CLAUDE.md has grown from a fact into a procedure. A one-line note, “Builds run through npm run build,” is a fact and belongs in CLAUDE.md. Ten steps for “how we publish the project” are a procedure and belong in a skill.

A practical principle: hand off anything you do more than a couple of times. Explain once how you put together, say, a weekly client report, turn that explanation into a skill, and you won’t have to explain it again. The skill sits there without taking up context and can be called by name using a command like /otchet.

Things that are useful to move into skills:

• Multi-step procedures (publishing, compiling a report, pre-release checks).
• Long instructions that are needed rarely but in full.
• Anything you copy from one chat into another for the second or third time.

There’s also an intermediate option: folder-specific rules. If an instruction matters only for one part of a project, you can put it in .claude/rules/ and link it to the relevant files. Then it loads only when Claude is working with those files, instead of staying in context all the time.

What is automatic memory, and why use it in 2026?#

The second new mechanism that eases the load on CLAUDE.md is automatic memory. The idea is that Claude now remembers not only what you wrote, but also what it noticed on its own. A separate guide, “Claude Memory vs. CLAUDE.md”, explains how its mechanics differ from CLAUDE.md.

The difference between the two kinds of memory:

Here’s how it works: while Claude works on your task, it notices useful details—which command runs the build, where debugging hit a snag, what you asked it to do differently—and saves them in its notes. It brings them back in the next session. Important: it saves selectively, keeping only what it considers useful for the future.

The notes live in a separate folder for each project, with an index file called MEMORY.md. You can view and edit them with the /memory command. They’re ordinary text files, so you can read, edit, or delete them at any time.

What this changes for you in practice: Claude now records some of what you used to add to CLAUDE.md yourself after every mistake. That makes your rules file even shorter—and that’s good.

Why does Opus 5 argue with your instructions?#

There’s a flip side to this.

A model given the right to exercise judgment will, by definition, sometimes disagree with a rigid command if it sees a better option in context.

What this means for you if you’ve upgraded to Opus 5 and something goes wrong:

1. Recheck your old skills and plugins. Setups built for previous models may conflict with the new logic. Something that used to work like clockwork is now worth testing again.
2. Remove the most rigid wording. Fifth-generation models handle commands like “never do X, always do only Y” worse than flexible wording that explains why.
3. Watch for places where the model stops too early. Sometimes this signals that an instruction contradicts itself or runs up against a rule in an overgrown CLAUDE.md.

How to rewrite CLAUDE.md for Opus 5: step by step#

Here’s the process for working with a CLAUDE.md inherited from earlier models.

1. Run the built-in check

   Type claude doctor in the project. It will suggest what to remove from the bloated file and what to keep.

2. Remove the obvious

   Delete every line Claude can infer from the code itself: folder structure, list of libraries, and general phrases like “write clean code.”

3. Remove contradictions

   Go through the file from top to bottom and find rules that conflict. Keep one and delete the conflicting one.

4. Move procedures into skills

   Move anything that has turned from a fact into a step-by-step instruction to a separate skill. Leave a one-line link in CLAUDE.md.

5. Make the remaining rules specific

   Rephrase each rule so it can be checked: “format it properly” becomes “use a 2-space indent.”

6. Turn on automatic memory and check the length

   Make sure automatic memory is working (/memory) and that the file is under 200 lines. If not, there’s something else to move.

To avoid doing the first pass by hand, have Claude do the work. Here’s a prompt you can use as a starting point—copy it, paste it into a session opened in your project:

Read my CLAUDE.md and my code. Your task is to make CLAUDE.md shorter and more useful for a fifth-generation model.

Go through the file and divide all the rules into three groups:

KEEP - project-specific pitfalls and conventions you cannot infer from the code yourself.

DELETE - obvious things you already know, and anything that can be inferred from the code.

MOVE TO A SKILL - multi-step procedures that currently live as text in CLAUDE.md.

For group 1, rephrase vague rules so they are concrete and verifiable.
Find rules that contradict each other and show them separately.
Return a new version of CLAUDE.md under 200 lines, plus a list of what you propose moving to skills.
Do not change any files until I confirm.

Note the last line: “Do not change anything until I confirm.” With a model that now uses its judgment, this is important: have it show you a plan first, and leave the decision to you.

Why is context more important than the prompt?#

If you set aside the specifics about Opus 5 and look at the bigger picture, this whole analysis is about one idea: context is more important than the prompt. The most important work happens before the request—when you assemble the environment in which the model will work.

CLAUDE.md, skills, and automatic memory are all parts of one thing: what Claude sees before your first message. You can endlessly tweak the wording of your request, but if the context is put together poorly—an overgrown CLAUDE.md, contradictory rules, no structure—the results will still be inconsistent.

Here’s a simple check: without a first brain, a second brain won’t help. By “second brain,” this article means the structure of knowledge about a project that the model reads with every request. But it works only when it’s backed by your clear understanding of the task. A tool amplifies your thinking, and that’s where its role ends.

The Opus 5 update sharpened this logic. Anthropic showed with its own work that when the model is smart enough, extra rules only hurt, and the advantage goes to whoever assembled the context carefully. This is a skill that will stay with you through every next model, whether Opus 6 or any other.

Where should you start right now?#

Don’t put it off until “someday.” The simplest first step is to open CLAUDE.md right now and honestly ask yourself about every line: is this a pitfall Claude can’t infer, or an obvious thing I added just in case? Everything in the second group is a candidate for deletion.

Next, run the file through the prompt in the section above, move long procedures into skills, and check that automatic memory is enabled. One evening’s work, and your context will become a concise, precise foundation for the model.

You can apply this on a real project of your own: CLAUDE.md, a second brain, and skills for your tasks.

Get to know Ailoot.