I audited my CLAUDE.md against Anthropic's new context engineering rules

Anthropic removed more than 80 percent of Claude Code's system prompt for its Claude 5 generation models and reports no measurable loss on its coding evals. The write-up frames the reasoning as six shifts in how you should write system prompts, skills and CLAUDE.md files. My reaction was not excitement. It was discomfort. My own setup is a 482-line CLAUDE.md, a separate rules file with 17 NEVER rules, and 55 skills, all feeding one agent. If the guidance is right, a chunk of that is dead weight that costs tokens and attention every single session. So I did the only honest thing: measured the config and sorted every shouted rule against the six shifts.

• The source. Anthropic's own write-up, by a member of their technical staff who also posted the announcement thread. Not a third-party hot take.
• The subject. A real working config: 43 KB of CLAUDE.md, 214 lines of global rules, 55 skills on disk, built up over five months of daily agent work.
• The method. All 26 rules written as NEVER or ALWAYS, sorted into three buckets: environment facts, access gates, and opinions about model behavior.
• The surprise. Sixteen of the 26 turned out to be opinions about model behavior. Only two of them shout about the environment itself.
• The line I will not cross. Production access rules stay, all of them, and I explain why that is not a contradiction.

The agent this config feeds runs inside Claude Code, and the config grew the way scar tissue grows: one incident, one rule. That growth pattern is exactly what Anthropic now says stops paying off.

What are the six context engineering shifts?

The core claim: guidance written for an older model's weaknesses becomes dead weight for a newer one. Anthropic read transcripts of internal Claude Code usage and found conflicting instructions stacked inside single requests, one layer saying to leave documentation as appropriate while another shouted DO NOT add comments. Their wording is that the model has to think more carefully before deciding what to do. My read: the attention it spends untangling your contradictions is attention you paid for.

The six shifts, in the order they publish them:

Two of these carry most of the weight for anyone with a config like mine. The rules shift replaces explicit constraints like "never write multi-paragraph docstrings" with outcome statements like "write code that reads like the surrounding code". And progressive disclosure means context loads when the task needs it, not at session start. The other four are consequences of taking those two seriously.

The examples shift deserves one concrete note because it is the least intuitive: instead of showing the model three sample tool calls, you design the tool parameters so the right usage is obvious. A status enum of pending, in_progress and completed teaches the model more than a paragraph of examples, at a fraction of the tokens. I saw the same effect from the other side when designing my own MCP tool surface: the parameter names did more steering than the descriptions.

How big is my CLAUDE.md really?

Numbers first, because "my config is probably too big" is not a finding.

• Workspace-level CLAUDE.md: 482 lines, about 5,900 words, 43 KB. Loaded into every session before the first user message.
• Global rules file: 214 lines, containing 17 NEVER rules for coding style, testing and safety.
• The CLAUDE.md itself carries 9 more lines written as NEVER or ALWAYS.
• Skills: 55 of them on disk, each contributing its description to the session context so the model knows it exists.
• Auto-memory index: 85 lines the model maintains itself.

Rough math on the big file alone: 43 KB of markdown is on the order of ten thousand tokens, paid on every session start, whether the session is a two-minute question or a two-hour build. That is the "put it all upfront" pattern the third shift retires. The honest question the audit has to answer is not whether that is a lot. It is how many of those tokens are gotchas, because gotchas are the one category Anthropic says should stay: keep the file light, describe what the repo is for, and spend most of the tokens on the traps a fresh model cannot see coming.

Which rules survive the judgement shift?

First, what the 26 is and is not: it is every line in the two files written as a shouted NEVER or ALWAYS. Both files also carry softer rules in prose that I did not count, so this is a sample of the loudest rules, not a census of the whole config. I sorted those 26 and three buckets came out, not the two I expected.

Environment facts: 2 of 26. Rules where the model cannot reason its way to the answer because the answer lives outside the code. The multiline commit style that the old PowerShell on this machine silently mangles. The fact that in a repo shared by parallel agent sessions, a scoped commit takes the working tree state, not the staged index; I learned that one from a commit that carried 33 files when I staged 32. Two. That is the whole list. The config holds more environment facts than that, CRLF endings for batch files, a database write style that silently wipes fields owned by another job, but they live in prose sections. Among the shouted rules, almost nothing is actually about the environment.

Access and consent gates: 8 of 26. Credentials never leave their vault files, no secrets in commits or logs, never delete data from the shared spreadsheets, never install a dependency without telling me, never invent a financial number. These are not about model skill at all, and they do not get relaxed. More on that below.

Behavior opinions: 16 of 26. The embarrassing bucket. "Check that a library exists in the project manifest before using it." "Never use any, never use non-null assertions." I wrote these against real failures of the models I ran at the time. Rereading them now, most describe things current models do by default. I also assumed three of the TypeScript rules were enforced by the toolchain anyway, and checking that produced its own small finding: strict mode plus my linter preset only catch any. The bans on as and non-null assertions live in stricter presets I never turned on, so for two of the three rules the prompt was the only enforcement all along. And some rules now conflict, exactly the pattern from Anthropic's transcripts: my style section says match the surrounding code, my rules file says never do X regardless.

Two carve-outs inside that bucket, because "the model probably knows this" is not one standard. The five rules about test integrity, never weaken an assertion to make a test pass, never delete a failing test, stay for now: gaming the test suite is not a knowledge gap that better models outgrow, it is a temptation that comes with the reward of a green build, and I have not seen enough evidence to trust judgement there. And the three code security rules, no SQL from concatenated input, no dynamic execution of user input, no deserializing untrusted data, do not get cut either. By my own test below they are gates without a gate: the cost of a wrong call is an incident, not a review comment, and nothing outside the prompt enforces them yet. They stay until something does. So the cut list is 8 of the 16, the test rules go on probation, and the security three wait for real enforcement.

What does not get relaxed: production access

Here is where I refuse to follow the judgement shift, and I think the refusal is the correct reading of it. The eight gate rules from the sort are not about code quality. They gate what the agent may touch: no deploys without a spoken yes, no writes to the production database, no sending anything to a human, secrets never leave their vault files. Those rules stay word for word.

The judgement shift is about style and craft, where a wrong call costs a code review comment. Access rules live in a different category, where a wrong call costs money or trust, and I already keep those as hard production gates rather than persuasion in a config file. The distinction the audit sharpened for me: a rule the model should internalize is a candidate for deletion. A rule the setup should enforce belongs outside the prompt, as a flag or a paused-by-default object. If deleting a sentence from CLAUDE.md would make an action possible that must never be possible, the sentence was the wrong enforcement mechanism all along. The cleanest switch of that kind I have found since is one line of skill frontmatter, disable-model-invocation, which I audited two days after this post.

So why do the eight sentences stay in the prompt at all, if the enforcement lives elsewhere? Because the sentence and the gate do different jobs. The gate stops the action; the sentence tells the agent the gate exists, so it asks instead of trying and bouncing off a hook mid-task. A sign on the fence is not the fence, but you still want both.

Progressive disclosure was already here: skills

The third shift asks you to load context at the right time instead of at session start. Reading it, I realized my setup is further along than my CLAUDE.md suggests, because skills already work this way: 55 of them sit on disk, only their one-line descriptions ride in the context, and the body loads when invoked. The same pattern covers tools now. Deferred tools keep their schemas out of the window until the agent searches for them, which is how a session with dozens of connected MCP servers stays usable at all.

What I got wrong is the split between CLAUDE.md and skills. My big file contains whole procedures: how to run the monthly audit, how the deploy pipeline works, what to check before touching a live campaign object. Those are skill bodies living in the always-loaded file. The guidance is blunt about this: the file should say what the repo is and point to where knowledge lives, not carry the knowledge. Every procedure I move out is a few hundred tokens that stop taxing the sessions that never needed them.

Worth admitting about those 55 skills: most are installed from marketplaces, not written by hand, and many go weeks without an invocation. Which strengthens the point rather than weakening it. An idle skill costs its one-line description and nothing more. The 482-line CLAUDE.md costs everything, always.

Auto-memory retired my hand-written notes

The fifth shift, memory moving from hand-edited CLAUDE.md sections to auto-memory, is the one I can confirm from the receiving end rather than argue about. The model now maintains its own memory index, 85 lines of it, and writes new entries when something non-obvious happens. The quality is uneven in an interesting way: it is much better than my hand-written notes at recording precise failure conditions with dates, and worse at knowing which of two similar lessons should win when they collide. I still prune it by hand every few weeks. But the ritual of typing a hotkey to save a lesson is gone from my workflow, and I did not notice it leaving.

The practical consequence for the audit: the sections of my CLAUDE.md that duplicate what memory already tracks are pure archaeology. Old incident write-ups. Quirks resolved months ago and still explained at length. They read like a changelog nobody asked for.

How to run this audit on your own setup

The order matters, because the failure mode is deleting a gotcha you mistook for an opinion and rediscovering it in production three weeks later.

1. Measure before judging. Line count, word count, number of hard rules, number of skills. Ten minutes, and it turns the vague guilt into a list.
2. Run /doctor before cutting. Claude Code ships the command to rightsize skills and CLAUDE.md files for the newer models. Full disclosure: I have not run it on this config yet. It is step one of my first cut round, and if its opinion disagrees with my sort, that goes in the follow-up. The live version of the same number sits in my status line, which reads context_window.used_percentage after every message.
3. Sort every hard rule into environment fact, access gate, or behavior opinion. The test I used: could a strong model with full repo access deduce this? If yes, it is an opinion. If deducing it is not the point because the rule is about permission, it is a gate.
4. Move procedures to skills instead of deleting them. The knowledge stays one invocation away, it just stops being a tax on unrelated sessions.
5. Cut in stages and watch. I am cutting my 8 confirmed behavior opinions in two rounds, a week apart, watching whether any of the old failures come back. Deleting that much steering from a config that runs real work is not a thing I do in one commit.
6. Leave access rules alone, and if this audit tempts you to soften one, take that as a sign it should become an enforced gate instead of a sentence.

The verdict

The guidance holds up against a real config, and it cost me something to admit that. Sixteen of my 26 shouted rules are opinions about model behavior, and 8 of those are, on my reading, monuments to bugs that no longer exist. That reading is the hypothesis, not the result: the two-round cut is the experiment, and I will publish what comes back, including the rules that earn their way back in. The 43 KB file I was quietly proud of, the distilled experience of five months, is mostly in the wrong place. Procedures belong in skills. Incidents are already tracked by memory, better than I tracked them. What actually earns its always-loaded seat should come in under 100 lines: what this workspace is, who works in it, the eight access gates, and the short list of environment facts that will burn any fresh model that does not know them.

The part I keep having to say out loud: none of this loosens what the agent is allowed to do. Style rules got weaker because the models got stronger. Access rules do not care how strong the model is.

Source: Anthropic's write-up, The new rules of context engineering for Claude 5 generation models, written by a member of Anthropic's technical staff, who also posted the announcement thread.