When a new AI model ships, the most valuable thing you can do is not add better prompts — it is delete the ones you already have. Anthropic removed over 80% of Claude Code's own system prompt when Claude Opus 5 launched in July 2026, and coding evaluation scores did not drop. The lesson is not that prompts are useless; it is that prompts written for older models become dead weight that actively holds newer, more capable models back. Your CLAUDE.md, skills, hooks, and custom instructions are almost certainly tuned for a model that is now two generations behind.
Last verified: 2026-08-01
- Core claim: Anthropic cut 80%+ of Claude Code's system prompt for Opus 5 / Fable 5 with no measurable eval loss (source)
- Tool: Run
/doctorto audit your setup; use--safe-modeto test bare- Framework: The 4-tier gap method (prompt, CLAUDE.md, skill, MCP)
- Bottom line: Audit after every model release. Delete first, add last.
What Is AI Agent Setup Decay?
AI agent setup decay is the gradual accumulation of instructions, rules, and guardrails in your agent's context that were written to compensate for limitations the model no longer has. Every time you wrote "use npm run dev to start the project" or "never write multi-paragraph comments" or added a slash command to prevent the agent from wandering — you were patching a gap in a specific model's understanding. When the model gets smarter, those patches stop helping and start interfering.
Anthropic calls this "unhobbling" — the act of removing constraints that once prevented worst-case behavior but now create conflicting instructions that a capable model must waste attention resolving (Anthropic, "The new rules of context engineering for Claude 5 generation models," July 24, 2026). In their own internal usage, they found a single request could contain both "leave documentation as appropriate" from one context layer and "DO NOT add comments" from another. The older model needed the hard rule. The newer model could handle judgement — but only if you got the conflicting rails out of its way.
Why Does Old Scaffolding Hurt New Models?
More capable models follow instructions more diligently. That is the problem. When you give a smart model conflicting rules, it does not pick the right one and move on — it burns attention reconciling them, which degrades performance and wastes tokens. Anthropic's own example: the old system prompt said "Default to writing no comments. Never write multi-paragraph docstrings." The new one says "Write code that reads like the surrounding code: match its comment density, naming, and idiom." The first instruction is a global veto that is wrong for a real subset of tasks. The second is adaptive, local, and correct for every task (Anthropic, July 2026).
This is not hypothetical. Claude Code's old system prompt was roughly 800 tokens. After the cut, it was 164 tokens. That 636-token difference compounds across every single interaction — lower cost, faster responses, and more room in the context window for actual user content (Crypto Briefing, July 25, 2026).
How Do You Audit Your AI Agent Setup?
Audit in seven steps, ideally after every major model release.
Step 1: Test Bare with Safe Mode
Before cutting anything, establish a baseline. Claude Code v2.1.169 (June 8, 2026) introduced --safe-mode, which disables all five customization layers: CLAUDE.md, plugins, skills, hooks, and MCP servers (Claude Code v2.1.169 release notes). Run your normal tasks in safe mode and watch how the model performs without your setup.
claude --safe-mode
If the model handles your tasks fine without your scaffolding, that is your signal to start cutting. If a specific task breaks, that piece earns its keep — for now.
Step 2: Run /doctor
Claude Code ships /doctor (also runnable as claude doctor), which scans your project's CLAUDE.md, skills, and configuration, then returns a health report with a verdict on each piece and suggested changes. Nothing happens until you approve, so you can work through recommendations one by one (Anthropic, July 2026).
The /doctor command checks for oversized CLAUDE.md files (warns at 40,000 characters), excessive custom agent descriptions, too many MCP tool definitions (threshold: 25,000 tokens), and permission rule conflicts (vincentqiao.com, April 2026).
Step 3: Apply the One-Question Rule
For every line in your setup, ask: "Could the model have figured this out on its own?" If yes, delete it.
The most common dead weight is the startup command. You wrote "use npm run dev to start it" because the previous model did not know how your project starts and would not run it unless told. A capable model now reads your package.json, finds the dev script, and runs it with no CLAUDE.md at all. That line is dead weight.
What stays? Anything where your setup differs from what the model already knows. Your testing setup through a specific browser agent, the test runner you installed, the service that must be running before anything else — those are gotchas the model cannot guess.
Step 4: Resolve Conflicting Rules
Grep your CLAUDE.md and skills for absolute terms: NEVER, ALWAYS, DO NOT. Keep the ones that encode hard product or legal constraints. Delete the ones that restate taste the model already has — or that contradict each other. Anthropic found their own setup had "leave documentation as appropriate" and "DO NOT add comments" existing in the same context stack (Anthropic, July 2026).
Step 5: Move Procedural Content to Skills
CLAUDE.md loads on every session start. Skills load only when the model needs them. If your CLAUDE.md has a 200-line "how we verify PRs" section, extract it into a verification skill and leave a one-line pointer. The same instruction costs you real tokens every turn in CLAUDE.md — and zero until used when it lives in a skill (Anthropic, July 2026).
This is called progressive disclosure: keep the always-true, lightweight stuff in CLAUDE.md, and push anything long or occasional into a skill that CLAUDE.md tells the model to go read when needed.
Step 6: Write Evals (the Single Most Important Thing)
Once you strip scaffolding, something else has to tell the agent when it is done. An eval is a fixed check that decides whether the work is complete, and it must be strict enough to fail. "Run it and see if it looks better" is guessing with extra steps. A check you cannot fail is not a check.
Evals do not have to be tests. They can be:
- A screenshot comparison (does the page fit on a phone screen?)
- An auth check (does a wrong password get rejected?)
- A content check (does the text have no em-dashes?)
- A parity check (run every command through both old and new versions, compare outputs)
The key insight: checks expire too. They last roughly two to three model generations before everything starts passing and you need to throw the set out and write new ones from wherever the model is struggling now. Without something that tells the agent it is not finished, the agent stalls out within an hour and you are back to watching it.
Step 7: Re-run After Every Model Release
This is not a one-time exercise. Every lab ships a new model every few months. If your project is not brand new, its setup is tuned for a model that is two generations old. Make the audit a scheduled routine.
What Is the 4-Tier Framework for Fixing Gaps?
When the model keeps getting something wrong after you have cleaned up, there are four ways to fix the gap — ordered from cheapest to most expensive:
| Tier | When to use | Where it lives | Cost |
|---|---|---|---|
| 1. Fix the prompt | The instruction was unclear | In your conversation | Free — just rephrase |
| 2. CLAUDE.md | The model needs to know this every single time | Project root, loads on every session | Every-turn tokens |
| 3. Skill | You are explaining the same thing for the fifth time | ~/.claude/skills/ or project .claude/skills/ |
Zero until accessed |
| 4. MCP server | The information is somewhere the model cannot reach at all | External service connector | Setup + maintenance |
Tier 1 handles most gaps. If the model did not understand, change the words. This costs nothing.
Tier 2 is for the short, always-true facts: what the project is for, the things that trip an agent up, the build command if it is non-standard. Keep it lightweight. Anything the model can see by reading the file tree is dead weight here.
Tier 3 is for the thing you keep repeating. Skills work best as lightweight guides that let the model find information when it needs it — not locked-down rulebooks. Write them when they hold something particular to your team, because the model already knows generic best practices. If a skill gets long, split it across files so only the needed part loads.
Tier 4 — an MCP (Model Context Protocol) server — is the most expensive fix and the most overused. It is for when there is genuinely no way for the model to know something: a database it cannot query, an API behind auth, a service running on another machine. It is not for when the model misunderstood you (fix the prompt) or when you are repeating yourself (make a skill).
Should You Use Dynamic Multi-Agent Workflows or Routines?
Dynamic workflows — where a model plans and dispatches hundreds of parallel agents — sound impressive. The largest example is the Bun rewrite, where Claude Fable 5 rewrote approximately one million lines of code from Zig to Rust in 11 days using about 50 parallel workflows. The API cost was roughly $165,000 (The Register, July 14, 2026; Bun blog).
But the Bun rewrite also introduced 19 known regressions that existing checks did not catch (BigGo Finance, July 2026). When one agent goes wrong, you lose an hour. When hundreds have been running for two weeks, you can lose the whole two weeks and cannot tell which one started the problem.
Routines — recurring single-sentence jobs that run on a schedule — are what you will actually use day-to-day. Claude Code Routines launched as a research preview on April 14, 2026 (TechTalk News, April 15, 2026). They run on Anthropic's cloud infrastructure, so they keep going after you close your laptop. Practical examples:
- "Clean up all the stuff you don't need, including leftovers from features you already removed"
- "Write tests for the parts that don't have any"
- "Find the places where the same thing got built twice and merge them"
Pro plan users ($20/month) get 5 routines; Max ($100/month) gets 15; Team/Enterprise gets 25 (ByteIota, April 2026).
How Do You Prevent Scaffolding Rot?
| Practice | What it does | When |
|---|---|---|
Run /doctor |
Scans CLAUDE.md + skills, suggests cuts | After every model release |
Use --safe-mode |
Tests the model with zero customization | Diagnosing weird behavior |
| Schedule a routine audit | Re-runs the full 7-step framework | Every 3 months or new model |
| Keep CLAUDE.md lightweight | Repo purpose + gotchas only, not a diary | Always |
| Use progressive disclosure | Long instructions in skills, not system prompt | Always |
| Write evals that can fail | Strict pass/fail checks for "done" | Before building, not after |
What This Means for You
If you are building with AI agents — whether in Claude Code, another coding agent, or your own harness — the single highest-leverage habit is a model-release audit. When a new model ships, strip your setup to the base system prompt, test what breaks, then add back only what the model genuinely cannot figure out on its own. This costs you an afternoon and saves you from months of degraded performance.
For small businesses using AI agents for development or automation, the practical takeaway is this: your agent's CLAUDE.md and skills are not assets that compound — they are technical debt that rots. Treat them like a codebase that needs regular refactoring, not a knowledge base that only grows.
If you want to go deeper on agent setup and context engineering, our framework for building AI agent skills instead of collecting them covers how to write skills that earn their place, and our guide on cutting Claude Code tokens with free tools shows concrete cost savings from trimming the context stack.
For managing persistent memory across agent sessions without bloating CLAUDE.md, see our guide on giving Claude a persistent memory system with Obsidian. And if you are scaling beyond one agent, our AI agent operating system decision framework helps you pick the right orchestration layer — without over-engineering with dynamic workflows when routines will do.
FAQ
Q: How often should I audit my AI agent setup?
A: Every time a new model generation ships from your AI provider — typically every 3 to 6 months. Also run /doctor after any major change to your project structure. Scaffolding that was correct for last year's model is actively harmful for this year's.
Q: What is the difference between CLAUDE.md and a skill in Claude Code? A: CLAUDE.md loads into context on every session start and costs tokens every turn. A skill loads only when the model decides it needs that information. Keep CLAUDE.md short — repo purpose and gotchas only. Move anything long or occasional into a skill.
Q: Does deleting my agent's instructions really improve performance? A: Yes, if the instructions were written for an older model. Anthropic deleted 80%+ of their own system prompt and saw no measurable loss on coding evaluations. Conflicting and over-constraining rules waste the model's attention on reconciliation rather than the actual task.
Q: What is Claude Code safe mode and when should I use it?
A: Safe mode (--safe-mode or CLAUDE_CODE_SAFE_MODE=1) disables all customizations — CLAUDE.md, plugins, skills, hooks, and MCP servers. Use it when your agent behaves strangely and you need to determine whether the problem is your config or the model itself. If the problem disappears in safe mode, it is in your customizations.
Q: Should I use dynamic multi-agent workflows for large tasks? A: Probably not for production work you need to ship. The Bun rewrite used hundreds of parallel agents, cost $165,000 in API fees, and still produced 19 known regressions that checks did not catch. Routines — single-sentence scheduled jobs — cover most real-world maintenance and automation needs at a fraction of the cost and risk.
Q: What makes a good eval for an AI agent? A: A good eval is a strict, automated check that can actually fail. Screenshots compared pixel-by-pixel, auth rejection tests, content pattern checks, or parity tests that run old and new versions side by side. If your check cannot return "no," it is not a check — it is a wish. Evals also expire: plan to rewrite them every two to three model generations.
Discussion
0 comments