<!--
  scaffold: claude-md-hygiene.md
  bucket: knowledge-memory (Bucket 4)
  what belongs here: CLAUDE.md immutability + 7-bucket sizing-by-need doctrine.
    - Anthropic <200 line target.
    - New rules go to bucket knowledge docs, not the body of CLAUDE.md.
    - 7 buckets are conceptual, not structural — always-on rules per bucket sized by need, not by number.
-->

# CLAUDE.md hygiene

## The discipline

CLAUDE.md is expensive per token (loaded on every session boot) and expensive per edit (the operator eyeballs every change). Both costs collapse if the file is allowed to accrete.

Rules:

- **7 conceptual buckets.** Operator interface, work management, delegation & dispatch, knowledge & memory, engineering discipline, content & voice, platform tooling.
- **Always-on rules per bucket capped by need, not by number.** No target rule count; a bucket ships as many rules as the operating model requires, no more.
- **New rules land in bucket knowledge docs**, referenced from the bucket's "Deeper reference" pointer in CLAUDE.md. Not in the body of CLAUDE.md.
- **CLAUDE.md changes only when the operating model shifts.** Not for every new finding. A finding is a knowledge-doc addition; a model shift is a CLAUDE.md refactor pass.
- **The Librarian never writes to CLAUDE.md.** Only the operator does.
- **The PA does NOT append ad-hoc.** Additions land in deliberate refactor passes, with intent.

## Line-count guardrail

Target: **under 200 lines** including framing. Anthropic's guidance from the CLAUDE.md best practices doc; corroborated by experience — files above 200 lines lose their always-on effectiveness because the model reads them as background rather than as instructions.

If the file grows past 200, the compensating cut is a demote-a-rule pass: which rule can move to a bucket knowledge doc without losing operating fidelity? If nothing can move, the operating model has genuinely expanded and a refactor is warranted.

## When to refactor

- The operating model shifts (a new discipline emerges, a discipline consolidates).
- A pattern of ad-hoc questions surfaces that a rule would answer.
- A bucket has grown to twice its original rule count without a corresponding model shift — probably some rules should demote to the knowledge doc.

## When NOT to refactor

- Every session. Refactor is a load-bearing operation; frequency erodes stability.
- On a single correction. Corrections go to staging; the Librarian synthesises; the operator refactors CLAUDE.md if the synthesis warrants.
- To fit a new tool or extension. New tools go in `pa --help` and knowledge docs; CLAUDE.md's rules stay stable.

## Related

- CLAUDE.md.template Bucket 4 rule 8.
- CLAUDE.md.template § Immutability + stability discipline.
- `librarian-synthesis-mandate.md` — the Librarian's side of the discipline.