Every Claude Code session in this repo loads three instruction files: a global CLAUDE.md, one for the folder that holds all my projects, and one for sparkone.nl itself. Together that’s 9715 words. Most of it was written because something went wrong, and many rules still carry the date it happened.
I had already started pruning. On September 24, the git history of this site shows two commits described as “history out, symptoms stay”. The idea was that a rule doesn’t get stronger because you remember the day it was born. This week it turned out Anthropic had built a tool for exactly that.
Back in June I wrote about the advice to tell the model less. Now there’s a yardstick to go with it.
What’s new
Claude Code 2.1.283 adds /doctor prompt-audit, also available as /checkup prompt-audit. The changelog describes it as an audit of your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models. That’s all the changelog says. On September 26 the /doctor documentation didn’t mention the new option yet, and a standalone docs page for the audit returned a 404.
It does have an older sibling. /claude-api already offers a prompt-audit subcommand for people building apps on the Claude API. That one runs on a detailed guide that ships with Claude Code, and the guide spells out which patterns count as dated. My working assumption is that the new /doctor version uses the same yardstick. I couldn’t confirm that.
What the audit treats as dated
The guide starts from one observation: current models follow instructions more closely and more literally than the models a lot of prompt text was written for. Old text then does more than waste tokens. It pushes behaviour in the wrong direction. The guide is explicit that the goal is finding specific dated instructions, and that shortening a prompt is not a goal in itself.
| Pattern | Example | What the guide suggests |
|---|---|---|
| Pressure language | CRITICAL: You MUST use this tool when... | Just say when to use the tool |
| Motivational nudges | “Be thorough. Do not be lazy.” | Delete, current models do this by default |
| Prohibition lists | “never X, avoid Y, don’t Z” | Keep the ones with a real reason, rephrase the rest positively |
| Step-by-step scripts | STEP 1: ... STEP 2: ... for judgement calls | Describe the goal, not the route |
| History narratives | Incident dates, PR numbers, pinned model names | State the current rule, drop the archaeology |
| The recency trap | One session’s stumble turned into a permanent rule | Keep only what helps most sessions |
According to the guide, a ban on a mistake the model wasn’t going to make can pull it toward that very mistake. So a list of prohibitions isn’t free, even when every item on it is correct.
There’s also a list of what the audit should leave alone. Context is never cruft: who the audience is, what the environment is, and the reasons behind a rule. A ban on a mistake the current model still makes stays too. And the guide says, in so many words, that an audit which finds nothing should change nothing.
Holding my own files up to it
I haven’t been able to run the audit yet. My install is on version 2.1.273, and the audit only arrived in 2.1.283. What I did do was have a few of the guide’s signals counted in the files that load with every session here. That’s a count, not an audit.
| Signal | What the count found |
|---|---|
| IMPORTANT, CRITICAL, MUST, NEVER, ALWAYS | 0 lines, across all four CLAUDE.md files |
| Lines with “nooit” (never), “verboden” (forbidden) or a ❌ | 20 in the global CLAUDE.md, 18 in the one for sparkone.nl |
| Lines with a 2026 date | 48, spread over three CLAUDE.md files and two commands |
So the classic all-caps shouting wasn’t there. The pattern that keeps coming back is history. Many rules still record the day something broke, and that’s what the guide calls archaeology.
That line is hard to draw. The guide wants a reason to stay, because a reason is context. The incident that led to the reason can go. In practice the two blur. “Blotato refuses a post once 200 are scheduled” is a reason. “On August 13 the alt text went missing” is an incident. But that incident also tells you which field disappeared, and that’s precisely what the next session needs to know.
The caveat
The vendor decides what counts as dated. The yardstick comes from the same company that builds the models, and it moves with every new one. The guide says so itself: run the audit again at every model release. That turns your instructions into something tied to one model from one provider. Tune them for Claude, and you tune them away from everything that isn’t Claude.
The audit proposes, you decide. Whether a prohibition blocks a real failure or an old fear is something the audit can’t see. Only the person who was there knows. The guide is honest about this: asking the model whether it needs an instruction is not a measurement. You have to test behaviour before and after. Accept the proposals blindly, and you also delete the rules that were there for a good reason.
Checking costs usage. The audit reads all your instructions, and the verification the guide recommends means test runs before and after each change. That comes out of your limit, and with a large pile of skills and commands it adds up.
What I’m doing
I’ll update Claude Code and run the audit read-only first, without letting it change anything. Then I go through the proposals rule by rule. Incident dates can go wherever the rule reads just as clearly without them. The rules that stay are the ones whose reason the next session needs, even if the audit flags them as history.
The same release also gives admins two settings for model choice. They can use availableModelsMatch to keep new model versions blocked until they’re explicitly allowed, and deniedModels to block specific models. If instructions are written per model, it makes sense to choose per model when you switch.
Frequently asked questions
What does /doctor prompt-audit do?
It checks your CLAUDE.md files, skills, agents and commands for prompting written for older models. Think all-caps pressure language, long prohibition lists, step-by-step scripts and rules that still point back at an old incident.
Does the audit edit my files by itself?
The guide behind the /claude-api version says the audit proposes changes as a diff and applies nothing without consent. Whether the /doctor version behaves the same isn’t documented yet.
Should I make my CLAUDE.md shorter?
Not necessarily. The guide itself warns against cutting something just because it’s long. Context about your project, your audience and the reasons behind rules stays. What can go is instruction for behaviour the current model already shows.
Sources
- Claude Code changelog, version 2.1.283, accessed September 26, 2026 — github.com/anthropics/claude-code
- Claude Code Docs, “Commands” page, accessed September 26, 2026 — code.claude.com
- Audit guide
shared/prompt-audit.mdfrom the claude-api skill that ships with Claude Code (bundle 2.1.281), read September 26, 2026 - My own count across this site’s CLAUDE.md files and commands, September 26, 2026
- My own piece, June 23, 2026 — Tell the model less. It often knows a better way.
Checked on September 26, 2026 against the changelog, the docs and the bundled audit guide. Two things I couldn’t verify. I haven’t run the audit myself, because my install is still on 2.1.273. And nothing states whether /doctor prompt-audit uses the same guide as /claude-api prompt-audit; the changelog and the guide describe it in the same terms, but that isn’t proof. The counts are simple searches for a few of the guide’s signals, not a judgement of every rule.