Claude Code's /doctor Prompt Audit: What It Checks in CLAUDE.md, and How to Trim Rules Safely

Claude Code's /doctor prompt-audit command checks CLAUDE.md and related instruction files for stale or conflicting rules. It then proposes edits and waits for your approval before changing anything. That is the documented answer to the query "claude code /doctor prompt-audit CLAUDE.md". This note covers what Anthropic's docs say the audit reads, how it differs from plain /doctor, what two third-party write-ups add, and a cautious pruning routine for indie game developers.

What does /doctor prompt-audit check, according to the docs?

The Claude Code memory docs say you run /doctor prompt-audit inside a session. They describe three kinds of finding:

• instructions written for older models
• references to files or commands that don't exist
• instruction files that contradict each other

According to the same page, the audit returns a report of findings with proposed edits. Nothing in your files changes until you ask Claude to apply them.

Which files does the audit read?

The memory docs set out the default scope. The audit covers:

• CLAUDE.md, CLAUDE.local.md and AGENTS.md
• rules, skills and commands under .claude/ and ~/.claude/
• subagents and output styles in those same directories

The docs add three practical details:

• Narrower runs. You can audit a single file or directory by passing its path, for example /doctor prompt-audit .claude/skills/deploy.
• A skill dependency. The audit runs through the bundled /claude-api skill. It is unavailable if that skill is turned off via skillOverrides or disableBundledSkills.
• A minimum version. /doctor prompt-audit requires Claude Code v2.1.283 or later.

One scope detail comes from a third party. Max Nardit's guide says the audit is told not to read settings files, .mcp.json or ~/.claude.json, because those can hold secrets and are not prompt text. Nardit also says plugin-provided skills are audited but only reported on, not edited. Anthropic's memory docs don't state either point, so treat them as Nardit's reading of the procedure.

/doctor vs /doctor prompt-audit: two different checks

According to wmedia.es, plain /doctor used to be a read-only diagnostic. It is now a fuller setup checkup with the alias /checkup. The article splits the checkup into two areas:

• Health: your installation, MCP servers and slow hooks.
• Context cost: unused or duplicated skills, MCP servers, plugins and CLAUDE.md content.

The article says the checkup lists its findings first and asks for confirmation before it changes anything. It also says CLAUDE.md content that Claude could work out from the repository gets flagged as padding. wmedia.es points to prompt-audit as a separate command for wording problems, such as all-caps emphasis and "think step by step" prompts. Nardit gives /checkup prompt-audit as an alias for the audit.

Why do long CLAUDE.md files cost something?

The Claude Code best-practices page says CLAUDE.md is read at the start of every conversation. It should hold persistent context that Claude can't infer from the code alone, such as Bash commands, code style and workflow rules. The page also says /init generates a starter file that you refine over time.

So every line in that file loads into every session, whether or not it is relevant. The memory docs add a second problem. When instructions contradict each other, Claude may pick one arbitrarily. The docs recommend reviewing CLAUDE.md, nested CLAUDE.md files and .claude/rules/ from time to time, and point to the prompt audit as a way to have Claude find the problems.

The memory docs also describe path-specific rules in .claude/rules/. These suit rules that only matter in one part of a project, such as a Shaders/ folder, an Addons/ directory or a native plugin folder. Moving those rules out of the always-loaded file is a structural fix. It doesn't depend on judging which rules a newer model still needs.

What the sources don't show

The case for removing "older-model" wording rests on reasoning, not published data. Nardit summarises the audit procedure's argument: older models needed emphatic wording, while current ones over-apply it, which can make an agent cautious and hedging. He also says files are judged against the model the current session runs on, so the same file can get different findings after a model switch.

None of the sources cited here publish a before-and-after measurement of output quality. Treat "trimming improves output" as a plausible hypothesis to check on your own project, not an established result.

What should a game dev keep, even if the audit flags it?

The best-practices guidance gives a useful filter: keep what Claude can't infer. In game projects, much of that is engine and pipeline fact. Those facts stay true whichever model reads them. Examples:

• "Godot 4 project. Use typed GDScript."
• "Never edit Unity .meta files by hand."
• "Build with this exact command" for a headless export, an Unreal build script or a CI target.
• Folder layout: where scenes, prefabs, Blueprints and generated assets live.
• Asset-pipeline rules: import settings, naming conventions, which folders hold source art and which hold exported art.
• Licensing constraints, such as which third-party assets can't be modified or redistributed.

A model update doesn't make any of these obsolete. If the audit proposes removing one, the likely reason is that the wording looks like older-model prompting, not that the fact has changed. Reword it instead of deleting it. Nardit's guide makes a similar point: the procedure keeps environment facts and the reasons behind constraints, and prohibitions against failures that still happen on the current model should stay.

Likely candidates for removal:

• shouting and emphatic wording (ALL CAPS, "CRITICAL", "YOU MUST")
• step-by-step reasoning prompts such as "think step by step"
• workarounds for habits older models had
• references to deleted scripts, scenes or build targets
• restatements of what the repo already shows, such as listing every file in a folder

CLAUDE.md is not the only place agent instructions pile up. Skills and plugins add their own. See our notes on Unity's official Claude Code plugin, Unity's plugin for Codex and the Awesome Gamedev Agent Skills pack. According to the memory docs, the audit's default scope includes skills and commands under .claude/ and ~/.claude/, so packs installed there may show up in the report. To review one pack on its own, pass its folder path to the command.

How do you prune CLAUDE.md safely?

This routine is based on what the sources describe. It is not a measured result.

1. Check your version. The memory docs say the audit needs Claude Code v2.1.283 or later.

2. Put your instruction files under version control. Commit CLAUDE.md, .claude/rules/ and any nested CLAUDE.md files, so you can revert any edit. The memory docs say CLAUDE.local.md belongs in .gitignore, so back it up separately if you use one.

3. Run the audit and read the report. In a Claude Code session, run:

   /doctor prompt-audit
   

   According to the memory docs, this only proposes edits. To start smaller, pass a path, such as one skill folder.

4. Apply edits in small batches. Start with the low-risk fixes: references to missing files or commands, and contradictions between files. Nardit says these lead the report because the repository alone can confirm them. Treat the "written for older models" removals as hypotheses, not facts. Commit each batch separately.

5. Compare behaviour on tasks you already repeat. Pick one or two, such as adding a new enemy scene or fixing a build error. Run them before and after the change. This step is up to you, because the sources publish no before-and-after data.

6. Re-run after a model change. Nardit suggests auditing again after migrating to a new model and uses Opus 5.5 as his example. It is a reasonable point to repeat the check.

While you are at it, move folder-specific rules into .claude/rules/ as the memory docs describe. That shrinks the always-loaded file without deleting anything.

Who is this for?

• Solo devs whose CLAUDE.md has grown for months or came from a template. A read-only audit is worth running. Stale paths and contradictions are the findings most likely to matter.
• Devs with a short, current file. The docs' description suggests there is little to gain. If the file only holds engine facts and build commands, the audit has little to flag.
• Teams with a shared CLAUDE.md. Review proposed edits in a pull request. The file shapes every teammate's sessions, and the docs warn that contradictions get resolved arbitrarily.

Limits: the audit is itself Claude judging Claude prompts, so some of its proposals will be wrong. According to Nardit, it doesn't read settings or .mcp.json, so problems there need a separate look. And the sources offer no measurement showing that trimming improves output. Use the report as a to-do list to review, not as a set of verified fixes.

For more on agent tooling for game projects, browse the coding agents tag or the rest of our Lab Notes.