Claude Code Doctor: The Checkup I Run After Every Model Release (Plus the New Prompt Audit)

Claude Code doctor is a built-in checkup you start by typing /doctor in a session (the alias is /checkup). It looks at your whole setup and tells you what is wrong or wasteful: duplicate or leftover installs, PATH problems, settings files that do not parse, skills and MCP servers and plugins that cost context without being used, hooks that are slow, and whether a newer version is out on your release channel. It also trims a checked-in CLAUDE.md by cutting content Claude could work out from the code itself. It reports its findings first and asks before it changes anything. Since Claude Code v2.1.283 there is a second mode, /doctor prompt-audit, that reads your instructions for rules written for older models and files that contradict each other.

I treat it the way I treat a service on a car. Nothing is broken today, but a Claude Code setup collects weight quietly. A skill you installed to try once. An MCP server for a client you finished in the spring. A CLAUDE.md that grew a paragraph every time something went wrong. None of it throws an error. It just makes every session a little slower and a little less focused, and you do not notice until the agent starts ignoring a rule you know is in there.

In the desktop app, open a local session on the project you want checked, type / in the prompt box, and pick doctor from the list, or just type /doctor and send. /doctor is a bundled skill, which means it is a prompt handed to Claude rather than a terminal-only panel, so it runs in a desktop session the same way it runs anywhere else. Claude reads your setup, writes up what it found, and then asks which fixes you want applied.

If you also live in the terminal, there is a separate command, claude doctor, typed at the shell rather than inside a session. It prints read-only installation and settings diagnostics without starting a session. That is the one to reach for when Claude Code will not start at all. Everything else in this post is the in-session /doctor.

The report groups into five kinds of finding. Each one points at a different problem, and each one has a clear right answer most of the time.

The unused-extension check is the one that pays back fastest. Every skill in the skill listing adds to your context on every turn, whether Claude uses it or not. If you want the per-skill numbers on their own, /skill-doctor shows what each skill costs and how often it gets used. What actually eats your limit explains why this adds up over a long day.

/doctor prompt-audit is a different job from the checkup. Instead of looking at your install, Claude reads your instructions: your CLAUDE.md, CLAUDE.local.md and AGENTS.md files, plus the rules, skills, commands, subagents and output styles under .claude in the project and in your home folder. It looks for three things: instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. You get a report and a set of proposed edits, and nothing in your files changes until you ask Claude to apply them.

The timing is the point. Claude Sonnet 5.5 landed in Claude Code this week, a week after Opus 5.5, and a lot of the instructions people carry around were written to push an older model into behaving. Shouting in capitals, repeating the same rule three times, warning it not to be lazy. An instruction written to push an older model can land differently on a newer one, and instructions written for older models are exactly what the audit is built to flag. It is the fastest way I know to find those lines, because it reads every file at once and I do not have to remember where I put them. The Sonnet 5.5 post covers what changed in the model itself.

The CCC Checkup Cadence is four triggers. Any one of them means run /doctor, and the first one also means run /doctor prompt-audit.

The trim is the one finding I read line by line, because it deletes words I wrote. The rule it follows is sound: cut what Claude can derive from the codebase, like directory layouts, dependency lists and architecture overviews, and keep pitfalls, reasons, and conventions that differ from tool defaults. The official guidance is to keep each CLAUDE.md under 200 lines, because longer files use more context and get followed less reliably. Claude Code also warns at startup, and in /status, when a file is over that length.

Where I push back is on anything that records why. "We use a queue here because the payment webhook times out" looks like architecture, but it is a pitfall, and it stays. If the trim proposes cutting a line like that, say no and keep going. Instructions that only matter in one part of the code are better moved than cut: path-scoped rules in .claude/rules load only when Claude works on matching files, and the checkup will offer to move always-loaded guidance into skills and nested CLAUDE.md files for exactly this reason.

Open your busiest project in the desktop app, run /doctor prompt-audit, then /doctor, and commit whatever you accept. It takes a few minutes, it asks before it touches anything, and it is the cheapest way I know to get a setup back to the size it was when it worked best. If you want the finished shape of a clean setup to compare against, CLAUDE.md templates by project type and context engineering are where I would look next.