Gustave Caillebotte painting: three shirtless men on their knees scraping the old finish off a wooden floor in an empty Paris apartment, with wood shavings around them and light coming in through a balcony window

·7 min read

Getting your projects ready for Opus 5.5

One Claude Code command reads your prompts, CLAUDE.md files and skills, and points out what was written for older models.

Gustave Caillebotte, The Floor Scrapers, 1875 · Musée d'Orsay

Opus 5.5 is out. Per token it's 20% cheaper than Opus 5: $4 per million input tokens instead of $5, and $20 instead of $25 for output. Anthropic says it's also better at long coding sessions in a real repository and at analysis work, and that it often gets there with fewer tokens.

The obvious move is to swap the model name and get on with your day. If you call the API directly, a few things in the code do need changing, and /claude-api migrate in Claude Code takes care of most of them. I want to write about the other half: the text you send to the model.

Prompts age faster than code

Any project that's been talking to Claude for a while picks up instructions written for models that no longer exist. A CRITICAL: you MUST use this tool from back when some older model kept forgetting to use it. A "think step by step" from before thinking was built in. A ten-step procedure for a task the model now plans better on its own.

Nobody removes these lines, because nobody remembers why they're there. They still have an effect, though. Newer models follow instructions more closely and more literally, so a rule that had to be shouted to get through to an old model now gets applied everywhere, including places it was never meant for. It works like "URGENT" in an email subject line: by the third one, nobody can tell what's actually urgent.

Opus 5.5 adds a few reasons of its own to look:

  • Thinking is always on. You control it only through effort, and the default effort dropped from high to medium. A "don't think, just answer" rule is now one the model can't follow.
  • Forcing a specific tool with tool_choice returns an error. You ask for the tool in the prompt instead.
  • Lines like "hold all findings until the end" or "don't narrate" were written for chatty models. With them in place, Opus 5.5 tends to go quiet for the whole of a long task.
  • Instructions for reading charts and screenshots (crop here, zoom there, read the axes first) may not be needed anymore. It reads visual material much more precisely on its own.
  • For frontend work, "avoid a generic AI look" doesn't do much. It works better when you name the specific defaults you don't want: a cream background, italic accent words in headlines, "01/02/03" section numbers, monospace labels, pill-shaped buttons. This blog has monospace labels all over it, so I'm in no position to judge.

The command

Claude Code has a command for this: /claude-api prompt-audit. It ships with Claude Code as part of the built-in claude-api skill, so you don't have to install anything.

It goes through the whole project folder and collects everything that reaches the model as text: system prompts and the code that builds them, tool descriptions, CLAUDE.md files, skills, rule files, few-shot examples, and the code that assembles API requests. It lists what it found first, so you can check it's looking at the right files.

If the project has git history, it runs blame on the prompt files. For every emphatic or forbidding line it asks which failure, on which model, the line was meant to prevent, and whether that failure still happens on the new model. A line nobody can justify gets flagged.

Then it compares everything against a list of dated patterns, including:

  • shouting in caps, and hedges like "try to" attached to things that are actually required
  • workarounds for things the API now does itself, like thinking and structured outputs
  • step-by-step scripts for tasks that need judgment
  • long runs of "never do X" with no reason next to them
  • fixes for bugs in models nobody uses anymore
  • the same rule written in three files, in three slightly different versions

What it leaves alone

This is the part that convinced me. The audit isn't trying to make your prompts shorter. For each line it asks one question: could the model already know this?

If the answer is yes, the line is a candidate for removal. Anything only you know stays: who your users are, what the product does, facts about the environment, how good the output has to be, and the reasons behind your rules. Exact scripts for fragile operations stay too (deploys, logins, anything that deletes things). Tool descriptions often come back with a suggestion to add detail, because a vague tool description is a more common problem than a long one.

If it finds nothing, it proposes nothing. A clean report counts as a result.

What you get

At the end you get a report and a diff. Each finding in the report has its location in the file, the quoted text, the pattern it matches, why that pattern is outdated for the target model, a confidence level and a suggested action. The diff has one finding per hunk, so you can take the ones you agree with and skip the rest.

It won't edit your files unless you ask. It also doesn't stop halfway to ask you questions. It works out the scope and the target model from your request and the repo, and writes those assumptions at the top of the report. If it guessed wrong, run it again with a narrower request.

Ernest's CLAUDE.md

Ernest, a colleague of mine, writes very detailed CLAUDE.md files that spell out how the agent should behave on his projects. The trouble started when some of those rules contradicted the rules in his skills. The agent was getting two sets of instructions, and it wasn't clear which should win.

I sent him a prompt to untangle it. It read the CLAUDE.md files and the skills side by side, found where the rules overlapped or contradicted each other, pointed out where it was unclear which file should take priority, and suggested a few ways to reorganize them so the agent would stop getting conflicting orders.

Most of the fix was deciding what each file is for. CLAUDE.md holds facts about the project and rules that apply everywhere. A skill describes how to do one specific task. Each rule lives in one place, and if the other file needs it, it points there instead of keeping its own copy. The prompt audit works from the same idea. CLAUDE.md and skills are both on its list, and one of its rules is that a piece of information lives in exactly one place. Copies drift apart over time, and that's where Ernest's conflicts came from.

How to run it

Open Claude Code in your project and type:

/claude-api prompt-audit

If you only care about part of the repo, add it after the command, for example /claude-api prompt-audit CLAUDE.md and .claude/skills.

Then read the report, take the hunks you agree with and test them. The audit itself says a removal is only a guess until you check it: compare behavior before and after, and if the stakes are high, change one thing at a time. If something gets worse, put the instruction back in a shorter, plainer form instead of restoring the old version.

Run it again at the next model release too. Some of the lines that help Opus 5.5 today will be the ones getting in the way of whatever comes after it.

About the painting

The painting at the top is Gustave Caillebotte's The Floor Scrapers from 1875. Three men on their knees in an empty Paris apartment are scraping the old finish off the floorboards so a new one can go on. Painters didn't usually bother with that part of a renovation. Caillebotte did, and the Salon jury turned the picture down, reportedly for being vulgar. A prompt audit is the same kind of job. Nobody will see it, and the next model will work better on top of it.