Skip to content

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
  • --quiet flag to suppress per-file table and print summary only
  • Graceful error handling — missing roots are silently skipped; unreadable files show ERROR status 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.md hygiene
  • Configurable threshold accommodates repos with legitimately larger instruction sets
  • Handles nested CLAUDE.md files across multiple scan roots in one run
  • --quiet mode 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_ROOTS in 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.