Claude Code's /doctor prompt-audit is a command that has Claude read your instruction files (CLAUDE.md, AGENTS.md, skills, commands, and so on), look for instructions that have gone stale or contradict each other, and propose fixes. All you get back is a report and proposed diffs: not a single character of your files changes until you ask Claude to apply something. Typing /checkup prompt-audit runs exactly the same audit.
This article explains what the prompt audit checks, how to run it, and what to do with the results, based on the original text of the official Claude Code docs (the "Audit your instruction files" section of How Claude remembers your project, plus Commands and Skills), the CHANGELOG, and the audit guide that ships inside Claude Code. Everything about the spec was checked against those originals as of October 3, 2026. Sections 7 and 8 also cover what happened when we ran it on this site's own instruction files (9 findings, 7 applied) and the caveats we ran into.
The short answer: /doctor prompt-audit at a glance
Source: Claude Code docs, "How Claude remembers your project" and "Commands" (checked October 3, 2026)
WHAT IT DOES
Audits your instruction files
Looks for wording written for older models, references to files or commands that no longer exist, and conflicting instructions.
OUTPUT
A report and proposed diffs
Nothing changes until you ask. You decide finding by finding what to apply.
SCOPE
CLAUDE.md, skills, and more
Also AGENTS.md, rules, commands, and subagents. Pass a path to audit just one place.
VERSION
v2.1.283 or later
Run it inside a session. It is not the same thing as claude doctor in your terminal.
Contents
- 1. What is /doctor prompt-audit? An audit for stale and conflicting instructions
- 2. How to use it: just type it, and narrow the scope with a path
- 3. What the audit counts as "stale"
- 4. What it won't delete: this is not a "make it shorter" audit
- 5. Reading the results: the report and the proposed diffs
- 6. How it differs from /doctor, /claude-api prompt-audit, and claude doctor
- 7. We tried it: auditing this site's CLAUDE.md and AGENTS.md
- 8. Drawbacks and caveats
- 9. When to run a prompt audit
- FAQ
1. What is /doctor prompt-audit? An audit for stale and conflicting instructions
Claude Code loads CLAUDE.md and your other instruction files every time it starts. Those files grow as you use them, and they accumulate heavy-handed wording written for older models, names of files and commands that no longer exist, and rules that contradict another file. /doctor prompt-audit is the command that has Claude go looking for exactly that.
Summarizing the official docs:
- What it looks for: instructions written for older models, references to files or commands that don't exist, and files that contradict each other.
- What it returns: a report of the problems it found and proposed fixes as diffs. Nothing in your files changes until you ask Claude to apply them.
- How it runs: through the
/claude-apiskill bundled with Claude Code. If you have turned that skill off in your settings (disabled it withskillOverrides, or enableddisableBundledSkills), the audit isn't available. - Version: Claude Code v2.1.283 or later.
/checkup prompt-auditis the same command.
The v2.1.283 entry in the CHANGELOG adds /doctor prompt-audit (and /checkup prompt-audit) to audit CLAUDE.md, skills, agents, and commands for prompting patterns written for older models. The same release also changed the audit to put stale paths, stale commands, and conflicting instruction files at the top of the report, and to keep thinking-depth keywords such as "think" that Claude Code officially supports.
Why do stale instructions matter? The bundled audit guide explains it this way: current models follow instructions more closely and more literally than older ones did. The stacked "CRITICAL" and "MUST" emphasis that was added so older models wouldn't overlook a rule now lands too hard, so the rule gets applied where it isn't needed and the model becomes rigid. The guide is explicit that the goal is not to make instructions shorter, but to find instructions that no longer fit the current model, the current project, or your other instructions.
2. How to use it: just type it, and narrow the scope with a path
Inside a Claude Code session, just type:
/doctor prompt-auditWith no argument, the official docs say it audits these files:
| Type | What's included |
|---|---|
| Instruction files | CLAUDE.md, CLAUDE.local.md, AGENTS.md |
Under .claude/ and ~/.claude/ | Rules, skills, commands, subagents, output styles |
To audit just one file or folder, pass a path. The example in the official docs:
/doctor prompt-audit .claude/skills/deployAccording to the bundled guide, the audit is designed to run to the end without stopping to ask questions. It works out the scope and which model to audit against from your request and the files themselves, and states those assumptions at the top of the report. If an assumption is wrong, run it again with a narrower path. For instruction files, the baseline is usually the model running the audit (or, if a skill or subagent pins its own model, that model).
The guide also says the audit does not read Claude Code settings files (.claude/settings*.json) or MCP configuration (.mcp.json), because they can contain secrets. Problems with permissions or hooks are outside this audit; that's the job of plain /doctor (see section 6).
3. What the audit counts as "stale"
What the audit checks is written down in the guide bundled with Claude Code (the prompt-audit instructions inside the /claude-api skill). When we read the files bundled with v2.1.286, the checks fell into four groups. For instruction files, the first two do most of the work.
| Group | Main checks | Examples |
|---|---|---|
| 1. Outdated prompting style | Over-strong wording, thinking instructions that are no longer needed, over-specified steps, leftover workarounds for old model bugs | "CRITICAL: you MUST..." over and over, "Think step by step", "STEP 1... STEP 2..." scripting work that needs judgment |
| 2. Fragile config files | Paths and commands that don't exist, files that contradict each other, incident histories written into the file, one-off stumbles turned into permanent rules, date-bound conditions | The name of a deleted script, opposite rules in two files, "Because this failed on [date]..." |
| 3. Tool descriptions | Descriptions you write when defining tools in the API (descriptions that are too short get flagged for more detail) | One-line descriptions, "always use this tool" inside a description |
| 4. API call settings | Parameters that now error out or are deprecated on current models, orderings that break caching, and so on | Only when there is application code (not relevant to a project that only has instruction files) |
Within group 2, "paths and commands that don't exist" gets particularly firm treatment in the guide. It checks whether each path in your instruction files actually exists in the project, and whether commands and flags are defined in your scripts or config, by reading files rather than running any commands. Anything that contradicts what's actually in the project becomes a high-confidence finding.
When two files conflict, the audit uses git blame (the record of who wrote each line and when) to decide which one is newer, and proposes bringing the older one in line. But if one side is a prohibition or safety rule that the fix would loosen, or if history can't tell which is newer, the guide says to propose no fix and simply report it as a decision for the user.
4. What it won't delete: this is not a "make it shorter" audit
What we liked most about this audit is that the guide spells out what must not be deleted. It warns that an audit that cuts everything penalizes exactly the people who wrote careful instructions, and it says the following should stay even if their wording matches a pattern:
- Context only the author knows: facts about the audience, product, and environment, quality bars, constraints, and the reasons behind them. The guide states plainly that context is never wasted.
- Length itself: nothing gets cut just for being long. What does damage is stale instructions, not volume.
- Exact steps for fragile operations: work with only one safe procedure, such as delete commands or authentication flows, can stay fully specified.
- Prohibitions against failures that still happen: if the failure still reproduces with current models, the rule stays.
- Duplication that works: the same content in two places is a matter of organizational taste, not something to audit, as long as the copies don't conflict.
It works in the other direction too. If current models would benefit from an added instruction, it proposes that. And it says that when nothing turns up, changing nothing is the correct result.
5. Reading the results: the report and the proposed diffs
You get two things back: an audit report and proposed fixes as diffs. Each finding in the report has six fields:
| Field | Contents |
|---|---|
| Location | File name and line number |
| Evidence | The problematic text, quoted verbatim |
| Pattern | Which pattern from section 3 it matches |
| Why it's stale | What it conflicts with: current model behavior, or something actually in the project |
| Confidence | High (contradicts official docs or the project itself), medium (widely observed behavior), low (inferred from wording) |
| Action | Delete, rewrite (with the new text), move (with the destination), add, or flag only |
Only high- and medium-confidence findings go into the proposed diffs. Low-confidence findings appear in the report only. The diffs are split into one hunk per finding, so you can pick just the ones you want.
To apply them, ask Claude something like "apply 1, 3, and 4." The guide also says that conflicts between files and rewrites of text that doesn't match the project are not applied on a blanket request such as "clean everything up." Anyone with write access to the repository could have changed either the newer text or the project itself, so the design assumes a human checks each one.
6. How it differs from /doctor, /claude-api prompt-audit, and claude doctor
There are four similarly named things. Comparing what the official docs (Commands and Skills) and the CHANGELOG say:
| Command | What it does | Changes files? | Version |
|---|---|---|---|
/doctor prompt-audit | Audits instruction files (CLAUDE.md, skills, etc.) for stale and conflicting instructions | Report and proposals only (applies on request) | v2.1.283 or later |
/doctor (alias /checkup) | A health check of your setup (duplicate installs, PATH, broken settings, unused skills and MCP servers, slow hooks, available updates), plus proposals to trim CLAUDE.md content that the code already makes clear and to move always-loaded instructions into skills or nested CLAUDE.md files | Reports first, fixes after you confirm | (CLAUDE.md trimming proposals: v2.1.206 or later) |
/claude-api prompt-audit | Audits the prompts and tool descriptions of apps built on the Claude API for patterns written for older models | Proposes diffs | v2.1.221 or later |
claude doctor (terminal) | Shows the state of your installation without starting a session | No (read-only) | — |
The confusing part is that /doctor itself also deals with CLAUDE.md. The difference is the goal. /doctor aims to reduce what's always loaded (removing duplicates, cutting what the code already tells Claude, moving things to places that load only when needed). /doctor prompt-audit checks whether the content has gone stale or contradicts itself. The terminal claude doctor doesn't run a prompt audit.
If Claude isn't following your instructions because they aren't being loaded at all, this audit won't fix it. We cover how to check what gets loaded in "Why AI Ignores Rules: Checking CLAUDE.md, Cursor Rules, and AGENTS.md," and how to measure how much of your context the instruction files take up in "Claude Code: What Is Actually Eating Your Context?"
7. We tried it: auditing this site's CLAUDE.md and AGENTS.md
On October 3, 2026, we ran /doctor prompt-audit on the instruction files we use to develop this site. We ran it in the Claude Code desktop app (bundled Claude Code 2.1.286, with Opus 5.5 as the model). Our instruction files are AGENTS.md (the main rules, shared between Claude Code and Codex) and CLAUDE.md (which imports it and adds Claude Code-specific notes), about 10,700 characters combined. We don't keep any rules, skills, or commands under .claude/.
Results from one run
Source: our own test (October 3, 2026, /doctor prompt-audit on CLAUDE.md and AGENTS.md)
Findings
9
Checked and applied
7
Skipped (low confidence)
2
The first surprise was that it found almost no prompting written for older models. There wasn't a single "think step by step" or step-by-step script. Most of the findings were in group 2 from section 3 (fragile config files).
| Confidence | Count | What it found | What we did |
|---|---|---|---|
| High | 1 | We had added two audit tools that day, but a parenthetical note still said "both" and no longer matched the descriptions of the two new tools | Applied (rewrote the note to cover the added tools separately) |
| Medium | 5 | Incident records with dates and counts left in the instruction files (contradicting a rule in the same file: don't pile incident records into the entry files) | Applied (but moved them to a separate records file instead of deleting them) |
| Medium | 1 | A "(CRITICAL)" in a heading with no reason given | Applied (removed it) |
| Low | 2 | A list of commands that don't run locally, and a heading with a date in it | Skipped (both are there for a reason, and the guide also treats low as "flag only") |
The single high-confidence finding was a real drift. When we added the audit tools, we added their names to the list but forgot to rewrite the explanation next to it. Every time the file loaded, Claude could have misread what "both" referred to, and we had missed it by eye.
The report also recorded that it had confirmed every path, tool name, and referenced memo in the instruction files actually exists. It even cross-checked the PHP version (matching the Docker config) and the number of steps in a procedure (matching a list in another file).
We didn't accept Claude's proposed diffs as-is; we applied them only after checking each one against the original files. The five medium findings needed the most judgment. The proposal was to delete the incident records, but those records are the evidence that keeps the same mistakes from happening again, so we moved them instead of deleting them. Where the dates and counts already existed in another file, we just removed them from the instruction files; the two that weren't recorded anywhere else we copied into the records file. In the end, the instruction files went from about 10,700 characters to only about 40 characters shorter. The size barely changed; only the contradictions went away.
Keep in mind that this is one run on one project. The model writes the audit, so running it again on the same files can produce a different number of findings or different wording. A project with lots of skills and commands under .claude/ will likely get quite different findings.
8. Drawbacks and caveats
From using it and reading the official docs and the guide, here are five things to keep in mind:
- It uses your usage allowance: Claude reads and audits your instruction files inside the session, so it counts against your usage like any other work. The official docs don't mention any separate pricing.
- Don't apply findings blindly: Claude may not know why a rule was written. In our case, accepting the "delete the incident records" proposal as-is would have thrown away the evidence that prevents repeat mistakes.
- Results vary from run to run: a model writes the audit, so the count and wording can change each time. Don't treat one clean run as proof that a file has no problems.
- It doesn't look at settings files: it doesn't read
settings.jsonor.mcp.json, so permission, hook, and MCP problems won't show up. Use/doctorfor those. - It doesn't guarantee your content is right: it catches missing paths and contradictions, but it doesn't judge whether your policy is the right one. That decision is yours.
The guide itself treats deletions as hypotheses, not conclusions. Once you remove an instruction, you're expected to check in real work that the behavior it was enforcing hasn't broken.
9. When to run a prompt audit
The guide describes prompts as artifacts of a particular model, where lines that one generation needed become dead weight in the next, and it recommends re-auditing whenever a new model comes out. In our judgment, these three situations are a good fit:
- When you switch to a newer model generation: check for strong wording and workarounds left over from older models
- After a major rewrite of your instruction files: as in our run, new rules and old explanations tend to drift apart
- When you share instruction files across tools such as Claude Code and Codex: it makes contradictions between AGENTS.md and CLAUDE.md easier to spot
On the other hand, if your instruction files are short and rarely change, there's no rush. The guide also says that finding nothing is a correct result.
Summary
/doctor prompt-audit is a command that searches your instruction files (CLAUDE.md, AGENTS.md, skills, and more) for wording written for older models, paths and commands that don't exist, and conflicting rules, then returns a report and proposed diffs. It's available in Claude Code v2.1.283 and later, and nothing changes until you ask.
The audit guide protects context, reasons, and prohibitions against failures that still happen as things not to delete, so that it doesn't turn into a "make it shorter" audit. When we ran it on this site's instruction files, there was almost no outdated prompting, but it did find an explanation we forgot to rewrite after adding a rule, a genuine drift.
The safe approach is to check each finding against the original file and move, rather than delete, text that exists for a reason. Running it once after switching models or rewriting your instruction files can catch contradictions you missed by eye.
FAQ
Q. Will /doctor prompt-audit rewrite my CLAUDE.md on its own?
A. No. The official docs say it returns a report and proposed fixes, and nothing in your files changes until you ask Claude to apply them. Even then, you can choose proposal by proposal.
Q. What's the difference between /doctor prompt-audit and /checkup prompt-audit?
A. There is none. /checkup is an alias for /doctor, and the v2.1.283 entry in the CHANGELOG lists /doctor prompt-audit together with /checkup prompt-audit.
Q. Does it audit AGENTS.md for Codex too?
A. Yes. The official docs list AGENTS.md alongside CLAUDE.md and CLAUDE.local.md among the files audited when you pass no argument. If you share the two files, it's also good at finding contradictions between them.
Q. I typed it, but the audit doesn't start.
A. First check your version: /doctor prompt-audit needs v2.1.283 or later. If your version is new enough and it still doesn't run, check whether you've turned off the bundled /claude-api skill in your settings (skillOverrides or disableBundledSkills). Also note that claude doctor typed in the terminal only diagnoses your installation and doesn't run this audit.
Q. Can it audit the system prompt of an app I built on the API?
A. Yes, but use /claude-api prompt-audit for that (v2.1.221 or later). It audits your prompts, tool descriptions, and API-calling code for patterns written for older models and proposes diffs.
Sources
- Claude Code docs: How Claude remembers your project ("Audit your instruction files" section)
- Claude Code docs: Commands (the
/doctorand/claude-apirows) - Claude Code docs: Skills (subcommands of the bundled
/claude-apiskill and required versions) - Claude Code: CHANGELOG (v2.1.283)
- The prompt-audit guide in the
/claude-apiskill bundled with Claude Code v2.1.286 (checked on our own machine)
All sources were checked in the original on October 3, 2026. The bundled guide is updated with each Claude Code release, so what the audit checks may change between versions.
