CLAUDE.md Audit

Every line in always-loaded context must pass: "Would removing this cause Claude to make mistakes?"

Arguments

• No args /

  --project

  : Project CLAUDE.md + architecture

• --global

  :

  ~/.claude/CLAUDE.md

  + global skills/hooks

• --all

  : Global + project + child dirs

• --fix

  : Apply fixes interactively after report

Phase 1: Discovery

Map the architecture before auditing files. Use Glob/Read to find:

• Always-loaded:

  ./CLAUDE.md

  +

  @imports

  ,

  ~/.claude/CLAUDE.md

  +

  @imports

  ,

  AGENTS.md

• On-demand:

  .claude/skills/*/SKILL.md

  , child

  CLAUDE.md

  files
• Enforcement:

  .claude/settings.json

  hooks,

  .pre-commit-config.yaml

  ,

  .githooks/

• Reference:

  docs/*.md

  ,

  Makefile

• Tooling: Linter configs, build systems (

  package.json

  ,

  Cargo.toml

  ,

  pyproject.toml

  )

Phase 2: Per-File Audit (28 checks)

Use Grep/Read for evidence. Do not guess.

A. Bloat — 1. Line count (flag >200, warn >150, target <100/<50 global) 2. Linter-territory rules (cross-ref linter configs) 3. Self-evident instructions ("write clean code") 4. Conventions Claude already knows 5. AI verbosity (reuse

/humanizer

patterns; 3+ triggers = flag) 6. Tutorials (>3 sentences, no actionable rule) 7. File-by-file descriptions (>10 lines)

B. Staleness — 8. Dead file refs (verify with

ls

) 9. Dead commands (check

which

/

command -v

) 10. Dead

@import

refs 11. Stale branch/PR refs (check

git branch -a

)

C. Misplacement — 12. Should be a hook (deterministic rules; redundant if enforced, suggest hook if not) 13. Should be a skill (domain knowledge >20 lines) 14. Should be in docs/ (>30 lines; use

@import

)

D. Duplication — 15. Global↔project overlap 16. CLAUDE.md↔skill overlap 17. CLAUDE.md↔hook overlap

E. Missing Essentials — 18. No build/test commands (Makefile/package.json exists but undocumented) 19. No branch conventions 20. Missing

@imports

for docs/ markdown

F. Structure — 21. Mixed concerns (commands + style + architecture blended) 22. Missing project CLAUDE.md (

--all

) 23. Unnecessary child CLAUDE.md

G. Architecture — 24. Always-loaded budget (CLAUDE.md + @imports + AGENTS.md total; flag >500 lines) 25. Tier separation (operational essentials only in CLAUDE.md; domain → skills; reference → docs) 26. Cross-ref hygiene (pointers not inlined content; no circular refs) 27. Makefile

help

target (reference

make help

instead of listing targets) 28. Hook coverage gap (advisory text vs deterministic enforcement)

Scoring (0-100)

Line count (15): 15/10/5/0 at <100/<150/<200/>200. Bloat (15): -3/finding. Staleness (10): -5/dead ref. Misplacement (15): -3/block. Duplication (10): -3/dup. Essentials (10): +5 build/test, +5 branch conventions. Structure (10): -3/issue. Architecture (15): +5 tiers, +5 budget, +5 cross-refs.

90+ Lean & well-architected / 70-89 Good / 50-69 Needs attention / <50 Overhaul

Output

Architecture table → per-file results table → category findings with line numbers → suggested improvements.

Fix Mode (

--fix

)

Report → ask which fixes to apply → Edit → re-audit for new score.

Gold Standard

Intactus (75 lines): three-tier progressive discovery. CLAUDE.md has branch workflow + Makefile commands + env vars + architecture pointers. Domain knowledge in

.claude/skills/shadcn/

(hub-and-spoke). Deep reference in

docs/

. Every line passes the litmus test.