Audit and improve CLAUDE.md files in repositories. Scans for all CLAUDE.md files, evaluates quality against criteria, outputs quality report, then makes targeted updates.
Audit, evaluate, and improve CLAUDE.md files across a codebase.
Find all CLAUDE.md files:
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
File Types:
| Type | Location | Purpose |
|---|---|---|
| Project root | ./CLAUDE.md | Primary project context (shared with team) |
| Local overrides | ./.claude.local.md | Personal/local settings (gitignored) |
| Global defaults | ~/.claude/CLAUDE.md | User-wide defaults |
| Package-specific |
./packages/*/CLAUDE.md |
| Module-level context in monorepos |
| Criterion | Weight | Check |
|---|---|---|
| Commands/workflows documented | High | Build/test/deploy commands present? |
| Architecture clarity | High | Can Claude understand the codebase structure? |
| Non-obvious patterns | Medium | Gotchas and quirks documented? |
| Conciseness | Medium | No verbose or obvious info? |
| Currency | High | Reflects current codebase state? |
| Actionability | High | Instructions executable, not vague? |
Quality Scores:
Output quality report BEFORE making any updates.
After user approval:
Apply changes using Edit tool. Preserve existing structure.