How to audit your CLAUDE.md with /doctor prompt-audit

Lydia Hallie, from the Claude Code team at Anthropic, posted a reminder on X to run /doctor prompt-audit in your Claude Code repos.

I ran it on the repo of this site. The CLAUDE.md here is 107 lines long, and I thought it was in good shape. The audit found ten problems in it, and five of them are facts that are wrong today.

What it does

/doctor prompt-audit makes Claude read your instruction files. That’s the text that loads into Claude Code sessions: CLAUDE.md, AGENTS.md, rules, skills, custom commands and subagents.

It looks for three kinds of problems:

• facts the repository has outgrown, like a path or a command that no longer exists
• files that rule differently on the same point
• wording written for older models, like CRITICAL: You MUST or “think step by step”

You get a report and a proposed diff. Nothing in your files changes until you ask Claude to apply an edit. The Claude Code docs describe it in a few lines.

It needs Claude Code 2.1.283 or later, and /checkup prompt-audit is an alias. Plain /doctor, without the subcommand, is a different checkup. It looks at your installation, your extensions and your permissions.

Why instruction files need it

CLAUDE.md loads at the start of every session. A wrong line in it misleads the agent every time, and nothing tells you it happened.

Mine was created by /init on July 17, 2025. Since then I kept adding sections at the bottom and never went back to the top. In the meantime pages were renamed, and the posts folder went from 500 files to 2,265.

The other reason is the models. Instructions written a year ago often shout, because older models needed it. Current models follow instructions more literally, so the same emphasis now makes them over-apply a rule.

Run it

Open Claude Code in your project and type the command:

/doctor prompt-audit

This audits everything that loads into sessions in this project. To audit one file or one folder, pass its path:

/doctor prompt-audit CLAUDE.md

I started with this one, on the CLAUDE.md in the root of the repo.

Claude read the file, then checked what it says against the repo. It listed the folders the file names, read package.json and src/content.config.ts, and used git blame to date the lines. It took 1 minute and 6 seconds.

The report opens with what it assumed: the scope, which was ./CLAUDE.md only, and the target model. Mine was Claude Opus 5.5, the model my session runs on. Claude judges the wording against that model, because a workaround that an older model needed is dead weight on a newer one.

If the command answers that the audit isn’t available, the bundled claude-api skill is turned off in your settings, with skillOverrides or disableBundledSkills. The audit runs through that skill.

What it found in my CLAUDE.md

The file had almost no shouting. The problem was the sections /init wrote in 2025, which no longer match the repo.

I checked the five high-confidence ones by hand, and they’re all correct.

The first is the worst. An agent that writes a post from that list leaves out the description, and the build fails.

The TypeScript line is one I would never have caught. Read literally, it tells the agent to write TypeScript in folders where every file is plain JavaScript, or to convert them.

Each finding quotes the text, says where it is and why it’s stale, and ends with a confidence level and an action. The low-confidence ones are only flagged, with no edit proposed.

The report also says what it left alone. My rules about redacting IP addresses in screenshots stayed, because they give their reason and every path in them exists. The audit keeps the context only you can provide, even when it’s long.

The proposed diff

After the findings comes a diff, with one hunk per finding. This is the one for the two pages that don’t exist and the posts count:

@@ CLAUDE.md:44-48 — findings 2 and 5
 │   ├── [slug].astro    # Dynamic blog post pages
-│   ├── blog.astro      # Blog listing page
-│   ├── books.astro     # Technical handbooks page
+│   ├── blog/           # Blog listing pages ([...page].astro)
+│   ├── ebooks/         # Technical handbooks pages
 │   └── rss.xml.ts      # RSS feed generation
-├── posts/              # Markdown blog posts (500+ files)
+├── posts/              # Markdown blog posts (2,000+ files)

And the one for the TypeScript rule:

@@ CLAUDE.md:106 — finding 3
-- Use TypeScript for all code implementations  
+- Use TypeScript in `src/`; `functions/`, `lib/` and `scripts/` are plain JavaScript (`.js`/`.mjs`), so match the file you're editing

Every hunk stands alone. To take some of them, reply in the same session and say which ones to apply.

Be careful with the rewrites. The new text restates a fact from the repo as it is today, so read each hunk before you accept it. One of mine replaced the list of frontmatter fields with “the other fields are optional”, and the report itself noted that this line is vague.

Audit the whole setup

Then I ran it with no path:

/doctor prompt-audit

This one took 6 minutes and 44 seconds, because it also covers ~/.claude. That’s my global CLAUDE.md and about 30 skills. It handed my 19 personal skills to a subagent, then checked three of the subagent’s findings itself.

It counted 23 findings. One was about wording, and 22 were stale facts and contradictions. Some of them:

• AGENTS.md contradicts itself. One paragraph says every new post needs four things, including a diagram. Another paragraph, which git blame dated about an hour later, says the diagram is optional.
• One of my skills has a table of five apps that use a file called AppUpdater.swift. No copy of that file exists anymore.
• A project skill tells the agent to suggest another skill, openspec-continue-change, which isn’t installed.
• The Cloudflare skill’s AI Gateway examples use claude-sonnet-4-5, an old model name.
• I have a skill for HEY twice, once on its own and once from a plugin, with different content.

The finding that surprised me is about AGENTS.md itself. It doesn’t load in my Claude Code sessions at all. When a repo has both files, Claude Code reads only CLAUDE.md. I keep my rules for writing posts in AGENTS.md, so Claude never saw them.

The fix is one line in CLAUDE.md, which imports the other file:

@AGENTS.md

Edits to files under ~/.claude are marked “all projects” in the report, because those files load everywhere. For installed plugins it only reports. And it didn’t open my settings files, .mcp.json or ~/.claude.json, because they can hold secrets.

Here are the two runs side by side:

Run it twice and the report changes

I ran the CLAUDE.md audit a second time, without opening a session:

claude -p "/doctor prompt-audit CLAUDE.md" --allowedTools "Read,Glob,Grep"

This run took 1 minute and 19 seconds and found 12 problems, where the first found 10.

Both runs agree on the five high-confidence facts. They differ at the edges. The second flagged a description of the build command that leaves out the checks it runs, and a “20+ handbooks” count. The first flagged the port of the dev server.

The first report also had a slip of its own. Its summary says nine issues, and its table lists ten.

It’s a model reading your files, so I treat the report like a review from a careful colleague. The high-confidence findings are checked against the repo, and I found no wrong one. The medium and low ones are judgment calls, and I decide on those.

When to run it

My advice is to run it when a new model comes out, and after any big change to the repo, like a migration or a renamed folder.

Start with the path form on your main CLAUDE.md. It takes about a minute, and the findings are easy to check by hand. Run the full audit when you have time to read a long report, because it also goes through every skill you have.

If your app calls the Claude API, there’s a version of this audit for your system prompts and tool descriptions. It’s /claude-api prompt-audit.

Want me to talk about your product? You can sponsor this site.