# claude-md-management
Your CLAUDE.md does not break. It rots.
Nothing warns you. A line that names a file you deleted three months ago throws no error — it is read, believed, and acted on, at the start of every session, for as long as it sits there.
I measured it on my own machine before writing any of this. A scanner over every CLAUDE.md I own: 39 files, 421 real file references, 70 of them dead. One file had 27 of its 48 references missing, more than half, including its own design spec. That file has been steering an agent all month.
Anthropic already shipped the fix. It is an official Claude Code plugin called claude-md-management, it has been in their own plugin directory since January 2026, it is Apache-2.0 and free — and it does not come turned on.
Install it in one minute
/plugin install claude-md-management@claude-plugins-official
There is no marketplace add step: the official directory ships pre-registered in Claude Code. Then, in plain English:
audit my CLAUDE.md files
## What you actually installed
A plugin is a package. This one carries two things, and the difference matters if you have ever been unsure what you were installing:
| what it is | how you trigger it | what it does | |
|---|---|---|---|
claude-md-improver | a skill | say *"audit my CLAUDE.md files"* | finds every CLAUDE.md, scores it, proposes edits |
/revise-claude-md | a command | type it at the end of a session | folds what the session taught you back into the file |
It runs in two phases. Discovery globs for CLAUDE.md, .claude.md and .claude.local.md across the repo, plus ~/.claude/CLAUDE.md. Assessment scores each file out of 100 and prints a report with a letter grade before it touches anything.
The rubric, so you can score yourself first
Six categories, summing to exactly 100:
| Category | Max | Full marks means |
|---|---|---|
| Commands / Workflows | 20 | build, test, lint, deploy all present, with the context to use them |
| Architecture Clarity | 20 | key directories, module relationships, entry points |
| Non-Obvious Patterns | 15 | gotchas, workarounds, *why we do it this way* |
| Conciseness | 15 | no filler, no restating what the code already says |
| Currency | 15 | commands still work, file references still resolve |
| Actionability | 15 | a new session can act without asking a human |
And seven red flags it hunts: commands that would fail · references to deleted files or folders · outdated tech versions · uncustomised template copy-paste · generic advice · TODOs never completed · duplicate information across several CLAUDE.md files.
What it cannot do
Read this before you build a habit on it.
It does not check whether your paths exist. "References to deleted files" is a red flag a *model* looks for while reading, not a resolver hitting your disk. A plausible-looking dead path can pass. That is exactly why the kit ships claude-md-deadrefs.py — stdlib-only, no network, no opinion.
**It does not see .claude/rules/*.md.** Discovery covers CLAUDE.md, .claude.md and .claude.local.md only, and the rubric never assesses *where* content is placed. That is open issue #734.
It is additive by nature. The documented behaviour is to propose targeted additions based on gaps. Conciseness is scored, so cut-pressure exists as a number — but do not expect a line-level delete list. If your file is too long, the score will say so and the edits mostly will not fix it.
It is a judgement, not a measurement. Run it twice and the number can move. Treat the score as a direction, never as a metric to optimise.
It writes to your files — after showing you the report and the diff, and only with your approval. Commit before you run it, so the diff is the whole story.
The honest bit about the claim
"A longer instruction file degrades adherence" is well supported in general — Liu et al., *Lost in the Middle* (TACL 2024) shows models miss information buried mid-context, and Chroma's *Context Rot* (2025) shows accuracy falling as input grows even far below the limit. Neither studies CLAUDE.md specifically. The mechanism is real; the exact cost to your file is not something anyone has measured, including me.
Comment SCORE and I'll send it over.