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

> Claude Code's /doctor prompt-audit finds stale facts, contradictions and dated wording in CLAUDE.md, AGENTS.md and your skills. I ran it on this site's repo.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-11-13 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/claude-code-prompt-audit/

Lydia Hallie, from the Claude Code team at Anthropic, [posted a reminder on X](https://x.com/lydiahallie/status/2121011733699633613) 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](https://code.claude.com/docs/en/memory#audit-your-instruction-files) 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:

```txt
/doctor prompt-audit
```

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

```txt
/doctor prompt-audit CLAUDE.md
```

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

![Claude Code running /doctor prompt-audit CLAUDE.md, with the scope and model it assumed and a summary of the stale facts it found](https://flaviocopes.com/images/claude-code-prompt-audit/start.webp)

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.

```mermaid
flowchart TD
  accTitle: How /doctor prompt-audit works
  accDescr: Claude lists the instruction files, then checks the paths and commands they name against the repository, compares files that rule on the same point, and compares the wording with the model the session runs on. The result is a report ordered by confidence and a proposed diff. Files are edited only when you ask.
  A[Instruction files] --> B[Inventory of what loads]
  B --> C[Paths and commands checked in the repo]
  B --> D[Rules on the same point compared across files]
  B --> E[Wording compared with the session's model]
  C --> F[Report, ordered by confidence]
  D --> F
  E --> F
  F --> G[Proposed diff, one hunk per finding]
  G -. only when you ask .-> H[Edits applied]
```

## 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.

| Line | CLAUDE.md says | The repo says | Confidence |
|---|---|---|---|
| 34-35 | `description` and `tag` are optional in the frontmatter | both are required in `src/content.config.ts` | High |
| 45-46 | pages live in `blog.astro` and `books.astro` | neither file exists, they're `blog/[...page].astro` and `ebooks/[slug].astro` | High |
| 106 | "Use TypeScript for all code implementations" | `functions/`, `lib/` and `scripts/` are all `.js` and `.mjs` | High |
| 30 | MDX is how content is written | the posts collection only loads `*.md` | High |
| 48 | "500+ files" in the posts folder | 2,265 files | High |
| 75, 78 | two notes about things removed in the past, with dates | history, with nothing for the agent to do | Medium |
| 84 | "No Cursor rules or Copilot instructions detected" | `.cursor/rules/` has 4 files | Medium |
| 105 | "Always use the latest version of Tailwind (v4)" | "latest" next to a pinned version goes stale at v5 | Low |

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 findings in Claude Code: a table with the count for each group, then each finding with its location, evidence, reason, confidence and action](https://flaviocopes.com/images/claude-code-prompt-audit/findings.webp)

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:

```diff
@@ 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:

```diff
@@ 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
```

![The proposed diff in Claude Code, with removed lines in red and their replacements in green, one hunk per finding](https://flaviocopes.com/images/claude-code-prompt-audit/diff.webp)

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:

```txt
/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`](https://code.claude.com/docs/en/memory#agents-md). I keep my rules for writing posts in [`AGENTS.md`](https://flaviocopes.com/agents-md/), so Claude never saw them.

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

```md
@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:

| | One file | Everything |
|---|---|---|
| Command | `/doctor prompt-audit CLAUDE.md` | `/doctor prompt-audit` |
| What it read | `CLAUDE.md`, plus `AGENTS.md` to look for conflicts | the project's files, `~/.claude/CLAUDE.md`, my skills, the plugins |
| Time | 1m 6s | 6m 44s |
| Findings | 10 | 23 |
| Edits outside the project | none | marked "all projects" |

## Run it twice and the report changes

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

```bash
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](https://flaviocopes.com/agent-skills/) 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`.