How to Audit Your Claude Code Instructions After a Model Upgrade

Much of the guidance in my personal projects had been tuned for Opus 4.8. When I moved to Opus 5.5 in late September 2026, I went through it in three stages: an automated audit, a file-by-file review with Claude, and testing on real development tasks.

The guidance covered CLAUDE.md, about ten agents, around twenty skills in my personal agent marketplace, hooks and the checks in two of my own repositories. Together it was roughly 22,000 tokens. After the cleanup it was about 13,000.

That number is the less interesting part. Each stage found something the previous one had missed, and the last one showed that some of what we removed was still needed.

Instructions written for the old model can hold the new one back

Instructions accumulate. A model ignores something, so you add a line. It skips a step, so you spell the step out. Over months those lines turn into workarounds for one model's habits.

When the model changes, the workarounds stay. Some still help, some do nothing, and some push the new model into extra work. Anthropic reported the same effect (opens in a new tab) in its own Opus 4.8 → 5.5 experiment: auditing the prompt after the switch lowered the cost further and slightly improved accuracy.

An upgrade doesn't break your instructions. It is a good moment to find out which of them are still doing anything.

What I audited

I focused on three sets of instructions:

1. Agent instructions: CLAUDE.md, agent definitions, skills and plugins.
2. Claude's own project memory: what Claude Code saves about the project by itself, under ~/.claude/projects/<project>/memory/.
3. My long-term memory files: the memory files I maintain for my agents myself.

The second one is the easiest to forget. You didn't write it, so you don't think of it as instructions. Claude still reads it.

The audit also reviews your application's prompts

One thing I didn't expect: when the project calls a model, the audit reviews those prompts too. That wasn't what I was after, but it is worth knowing before you run it.

In that project the real prompts live in Langfuse, a prompt management tool, so the audit only saw the fallback prompts in the code. The prompt in the repository isn't necessarily the one in production. If you want the audit to cover your application prompts, give it the version that actually runs.

Step 1: Run /claude-api prompt-audit

In Claude Code:

The audit checks your instructions for outdated information, contradictions and guidance that no longer fits the target model. I ran it with Claude Code v2.1.285 on Opus 5.5.

In one repository it reported 17 findings:

Group	Findings
Dated prompt text	5
Config files	11
Descriptions	1
Request config	0
Total	17

One example was a Firebase description in CLAUDE.md. The audit flagged that it conflicted with another line in the same file and with how the repository actually implemented it. That kind of finding is hard to spot yourself, because each line looks reasonable on its own.

What my run didn't do was tell me what to remove. It found contradictions and dated information well, but not enough of the accumulated guidance the new model no longer needed.

Step 2: Review the instructions file by file with Claude

So I went through the files one at a time with Claude and asked, for each instruction, whether Opus 5.5 still needed it. Depending on the file, 20–50% of the text went.

Anthropic's prompt-audit guide (opens in a new tab) has a good list of what to keep:

• facts specific to the project that the model cannot infer
• contracts for tools and scripts
• exact order where a sensitive operation needs it
• instructions that prevent mistakes the current model still makes

Include the memory in this review. Claude's own project memory had useful observations in it, but also duplicates and entries that conflicted with the skills and CLAUDE.md. The audit had not surfaced those conflicts. If you change an instruction and leave the old behavior in memory, the agent can still find the old version.

Step 3: Test on real tasks, and expect to restore some instructions

Claude had been quite willing to remove text during the review. A model saying an instruction is unnecessary is a hypothesis. Only running the agent tells you whether it was right.

After the cleanup I ran five real development tasks, normal work rather than synthetic tests. They exposed several gaps where we had removed instructions that were still needed.

One example. In my development workflow, the orchestrator is supposed to use the review-code skill from my aw-review plugin for review. After the cleanup, it started doing the testing itself instead. The instruction that kept that responsibility with the plugin had looked redundant. It wasn't.

I restored the instructions that turned out to matter and corrected the guidance based on what happened in the runs.

The 22k → 13k tokens is the size of the whole instruction set, not what gets loaded into every request. I haven't compared token use per task, so I can't claim a cost or quality gain from it. What I know is that the instructions are shorter and the contradictions are fixed.

Checklist for the next model upgrade

1. Run /claude-api prompt-audit and fix the contradictions and dated information it finds.
2. Include Claude's project memory and your own memory files. If the audit covers application prompts, check that it saw the version that runs in production.
3. Review the files one by one with Claude. Keep project facts, tool contracts, order for sensitive operations and protection against mistakes the model still makes.
4. Run real development tasks with the revised instructions, and restore what turns out to be needed.

When you upgrade the model, review the instructions around it too. Workarounds for the old model can hold the new one back.