CLAUDE.md Wrangler — lint and line-count enforcement for CLAUDE.md files¶
- Date: 2026-03-24
- Status: Accepted
- Tags:
tooling|workflow|process
Context¶
Multiple repositories now carry CLAUDE.md files at project, user, and
subfolder levels. Anthropic recommends keeping these files to approximately
150 lines for optimal context loading. Concise CLAUDE.md files load more
efficiently into context windows and reduce instruction noise.
No automated audit existed to detect files that had grown beyond this
threshold. Without tooling, bloated CLAUDE.md files accumulate silently
across repos and degrade agent performance over time.
Decision¶
We will maintain scripts/claude-md-wrangler.py — a stdlib-only Python
script that scans configured roots for CLAUDE.md files, reports line
counts in a fixed-width table, and exits non-zero when any file exceeds
150 lines (configurable via --max-lines).
Key design choices:
- Stdlib only (
argparse,pathlib,sys) — no third-party dependencies - Configurable scan roots via positional arguments; defaults to
~/sandbox,~/repos,~/.claude - Exit code 1 when any file fails the threshold — makes the script CI-friendly
--quietflag to suppress per-file table and print summary only- Graceful error handling — missing roots are silently skipped;
unreadable files show
ERRORstatus and do not crash the script - Phase 1 scope: line-count check only. Intelligent content analysis (duplicate sections, stale instructions) is deferred to a future issue.
The 150-line threshold comes from Anthropic guidance that concise CLAUDE.md
files load more efficiently and reduce instruction noise.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Shell script | Path expansion and fixed-width table formatting are cumbersome in shell; pathlib is cleaner and more testable |
| markdownlint rule | markdownlint has no concept of a line-count threshold scoped to a specific filename |
| Third-party linter | The issue explicitly requires stdlib only; the check is simple enough to not warrant an external dependency |
Consequences¶
Positive:
- CI-friendly exit codes allow the script to gate workflows on
CLAUDE.mdhygiene - Configurable threshold accommodates repos with legitimately larger instruction sets
- Handles nested
CLAUDE.mdfiles across multiple scan roots in one run --quietmode is suitable for scripted/CI invocation
Negative / Trade-offs:
- Phase 1 detects only line-count violations; anti-pattern detection (duplicate sections, stale instructions) is not yet implemented
- No auto-fix capability — the script reports but does not pare down files
Ongoing obligations:
- Update
DEFAULT_ROOTSin the script if new canonical scan locations are adopted across the team - Revisit the 150-line threshold if Anthropic publishes updated guidance
- Track a follow-up issue for phase 2 (intelligent content analysis via Claude skill)
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.