claude-md-audit

name	claude-md-audit
description	Audit CLAUDE.md against the 40K size budget; propose moves of reference-time content to CONTRIBUTING.md or new/existing ADRs, then apply with user approval. Use when CLAUDE.md approaches 40K chars or feels bloated.

claude-md-audit

Codified procedure for trimming CLAUDE.md back under the size budget without losing write-time utility. The routing rule lives in CLAUDE.md § "What goes in this file" — apply it here mechanically.

Procedure

1. Measure

• wc -c CLAUDE.md — anchor the audit to this number.
• Report it back to the user alongside the budget (hard fail at 40K, target ≤ 35K for headroom) and the delta to target.

2. Walk the file with the routing axis

For each ## section, classify:

• Write-time → KEEP — invariants, hard nos, project-specific overrides on platform docs, small canonical snippets (≤ 5 lines) the agent will reach for inline, decision tables (role → intent, label → use).
• Reference-time → MOVE to CONTRIBUTING.md § X — setup procedures, run commands, debugging walkthroughs, operator workflows, ASCII art, multi-step verification flows.
• Decision + rationale → MOVE to docs/adr/XXXX-*.md — why the project diverges, alternatives considered, revisit criteria. Mirror format of docs/adr/0001-*.md through the latest. Increment the next ADR number.
• Sections that mix both: split. Keep the invariant in CLAUDE.md; link out for the procedure / rationale.

3. Sections never to trim

Flag and stop if proposed changes touch these — they are pure write-time invariant content and trimming them costs more than the chars they save:

• § Sources of truth
• § Project-specific overrides
• § Features — test coverage workflow (the three-axis planning gate is a write-time forcing rule; trimming it reopens the manual-testing leak)
• § Security boundaries
• § Accessibility (WCAG 2.2 AA)
• § Design system (role → intent table)
• § Analytics events (hard rules)
• § Error tracking (hard rules + RuntimeException wrap snippet)
• § Copyright headers (the block IS the invariant)

User must explicitly approve any exception.

4. Propose, do not execute yet

Print a section-by-section table to the user:

Section	Current chars	Action	Δ chars
...	...	KEEP / TRIM / MOVE TO CONTRIBUTING.md § X / NEW ADR	...

Wait for explicit approval before any edit. If plan mode is active, write the plan to the plan file.

5. Execute (after approval)

• Move content to target file. Match target's heading hierarchy and writing style (English; see CLAUDE.md § Repo writing language).
• In CLAUDE.md, replace moved content with a one-line link: ... see CONTRIBUTING.md § X. or ... see ADR XXXX.
• New ADRs: include an ## Invariants section if grep-enforceable, and extend scripts/check-adr-invariants.sh in the same PR.
• Cross-refs: every see CONTRIBUTING.md § X must match an existing heading; every see ADR XXXX must map to a real file under docs/adr/. Grep verify.

6. Re-measure and verify

• wc -c CLAUDE.md — must be under 35K (target) or at minimum under 40K.
• bash scripts/check-adr-invariants.sh — must pass.
• ./gradlew check -x test — sanity (meta-only changes shouldn't break the build).
• Smoke read: read CLAUDE.md as a fresh agent. The file still answers: "can I use Hilt?" / "what dispatcher?" / "how do I track errors?" / "top-bar accent color?" / "inbound URI policy?" — if yes, trim preserved write-time utility.

7. Commit + PR

Single PR with a:docs label. Frame the description around what the agent gains (or doesn't lose), not what content moved where.