Standing-Context Audit — CLAUDE.md forensics, trim & going-forward rules
Requested by Fede ("is our claude.md bloated? I think Gera trimmed it"). Three evidence streams:
a duplication audit, a line-by-line forensic provenance/staleness investigation, and a four-lens deep-research
workflow on best practices. Source docs on the Mac mini: ~/agents/006/claude-md-forensics.md and
~/agents/006/claude-md-best-practices.md.
1. The premise was inverted
Fede's hypothesis was that Gera trimmed the repo CLAUDE.md and our copies drifted. The audit found the opposite: the repo file has grown monotonically (2,019 lines in June → 2,185 today) and the local checkout is byte-identical to GitHub. What Gera did on 2026-07-26 was a consolidation: four sections each restated the push→PR→merge flow with different stopping points until two contradicted each other; his fix was one canonical Shipping Vocabulary section (verb sets the ceiling, grant sets the gate, plus a hard floor no grant waives) and a Hot rules — read first digest, with everything else pointing at them.
The neglected file was Fede's personal global ~/.claude/CLAUDE.md: 346 lines, no
git history, grown by accretion — and it carried Gera's exact pre-fix pathology across three layers
(global ↔ repo ↔ memory files), including a fifth restatement of the deploy flow he had just deduplicated.
2. Forensics: age predicts staleness only for facts, not for norms
Every block was dated against its cited artifact (PRs, ADRs, memory files, repo commits) and every falsifiable claim was live-verified. The organizing result: behavioral rules don't decay; filesystem facts do. The 66–76-day-old conduct rules (no PII, no invented numbers, lock user corrections) were all still valid and enforced; nearly every factual claim from the same era was dead.
| Finding | Status |
|---|---|
| Global hold-list had 4 dangerous-diff categories vs the repo hard floor's 8 (missing: secrets, IAM/auth, billing, irreversible third-party mutations) — adjacent to an "auto-merge on green, do not ask" grant. The repo doc itself warns "a partial copy of that floor is worse than none." | safety hazard — fixed by pointer |
npm run deploy:lambda does not exist (six differently-named deploy scripts do) | hard-stale — deleted |
All seven src/lib/* paths in the Code Patterns section moved to src/lib/platform/*; clara-voice.ts exists at no path | hard-stale — deleted |
"Never run Playwright against production — only stage/localhost": stage was retired 2026-04-17, and another line in the same file mandates Playwright-against-prod via /browse | self-contradictory — deleted |
| PR #4102 cited as the UX-screenshot exemplar actually contains zero screenshots (rule good, proof drifted) | rewritten |
| Worktree reap discipline not holding: 132 live worktrees at audit time vs 0 after the June cleanup | operational, flagged |
Three-way secrets conflict: global says Keychain-only · repo says .env.local · smoke TOTP is a plain file in ~/.claude/.secrets/ | held for Fede's ruling |
| 23 ADR numbers are duplicated — "lowest genuinely-free number" is a recurring hazard, not a one-off | noted in docs rule |
3. Research: why size costs compliance
- IFScale (arXiv 2507.11538; 20 models, 500-instruction sweep): compliance decays continuously with rule count, and the failure mode at density is silent omission — rules stop firing with no signal.
- Levy et al. (ACL 2024): reasoning degrades from input padding alone by ~3K tokens — far below any context limit.
- Context Rot (Chroma): a focused 300-token prompt beat a 113K-token one across model families, with Claude showing the largest gap.
- IHEval: contradictory instructions resolve near coin-flip — one owner per rule matters more than any individual rule's wording.
- Field study: 29 root agent files from major OSS repos (airflow, next.js, sentry, posthog, kubernetes, deno) — median 188 lines, none above 520. Anthropic's own guidance: ~200 lines per file.
@path imports do not defer loading; only skills,
path-scoped rules, and unlinked pointers actually save context.4. What was changed (done)
- Global
~/.claude/CLAUDE.mdrewritten: 346 → 76 lines (~8.7K → ~2K tokens). Survivors: the standing auto-merge grant (stated once, pointing at Shipping Vocabulary for the full hard floor), cross-project mechanics with IDs (Trello, Slack, docs-site publishing, secrets, playbooks), non-decaying truth-norms (no fabrication, inference-vs-fact, raw-transcript rule, lock corrections), and unique critical rules (live-saga migration prohibition, ADR-PR review hold, never--no-verify, outbound-comms boundary). Everything stale or duplicated was deleted; incident rules live on as one-liners with the war stories in memory files. - A precedence ladder is now explicit: repo CLAUDE.md wins on repo matters; memories are background, not instructions.
- The file is now git-tracked (a scoped repo in
~/.claudeignoring everything but CLAUDE.md), with the pre-trim original archived as the first commit — every future change is reviewable and bisectable, closing the no-history gap the forensics identified as the root cause of the rot.
5. Going-forward rule (recommended standard)
Admission gate for any new standing rule — first match wins:
hook → linter → skill → path-scoped rule → docs pointer → repo CLAUDE.md → global CLAUDE.mdA rule earns a place only if the failure has been observed twice, fits one sentence, is positively phrased, and is quantified where possible. Every addition names an eviction. (A hand-sort of 252 real-world rules found ~84% were mechanizable as hooks/lint — prose should be the last resort, not the first.)
6. Open items
| Item | Owner | Shape |
|---|---|---|
Repo CLAUDE.md trim: 2,185 → 200–300 lines. Keep hot rules, commands, repo map, Shipping Vocabulary, hard boundaries, routing table; move ~800 lines of runbooks (renewal debugging, env vars, project structure, API endpoints, Workspace rename, offboarding) to docs/runbooks/*.md behind one-line pointers; path-scope area rules under .claude/rules/. The consolidation Gera already did is the right pattern — this extends it. | Gera | proposal — claude-md-best-practices.md is written as the handoff |
Secrets ruling: Keychain vs .env.local vs ~/.claude/.secrets/ — three live conventions. The trimmed global file keeps a neutral line pending the call. | Fede | decision |
| Worktree reap drift: 132 live worktrees despite the enforced-reap rule — either the fleet pattern needs a scheduled reap or the rule needs a hook. | Fede/eng | ops follow-up |
Prepared by Fable, 2026-07-27. Evidence files:
claude-md-forensics.md (20-block provenance/staleness table),
claude-md-best-practices.md (four-lens research synthesis, all cited). Global-file history:
git -C ~/.claude log -- CLAUDE.md.