Appendix A - 21. CLAUDE.md rule index (the governance document as a mechanism)

The Structure of CLAUDE.md rule index (the governance document as a mechanism) — its shape at a glance:

The document is booted by every agent and carries three enforced properties — a size budget, an admission predicate, and a per-rule cross-reference — each held by a blocking lint.

flowchart LR
  Doc["Governance document<br/>(booted by every agent)"] --> Agents([Every agent])
  Cap{{Cap / bloat lint}} -.->|fail if over budget| Doc
  Conf{{Conformance lint}} -.->|fail if a rule cites no canonical doc| Doc
  Admit{{Admission test}} -.->|route non-qualifying rules out| Doc

Accessible description: the governance document is booted by every agent; a cap lint fails the build if it exceeds its size budget, a conformance lint fails if any rule stops citing a canonical doc, and an admission test routes rules that don't earn a spot into sub-docs.

Projected from the catalogue entry governance-doc-controls / CLAUDE.md rule index (the governance document as a mechanism).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Treat the top-level governance document as enforced infrastructure: a numbered, stable-numbered rule index, loaded into every agent's boot context, held honest by its own enforcement counterpart (a bloat/cap lint plus a rule-conformance lint), so the document that carries every other mechanism cannot silently rot.

Motivation

The failure class is governance that doesn't bind and doesn't last. Two ways it manifests. First, non-binding: a convention lives in someone's head or a stale wiki page, so a fresh agent never applies it and the failure it was meant to prevent recurs. Second, rot: a living rules document either bloats until nothing in it is read (every agent pays the context cost, none of it lands), or its rules drift out of sync with the canonical docs they were supposed to summarize. Both compound brutally under a fleet: the document is booted by every agent, so a bloated or drifted index taxes or misleads every dispatch, continuously.

Applicability

• A boot-context loader that injects the document into every agent; without this it is just another doc.
• A budget + cap lint, or the index bloats until it is unread. The cap is the forcing function that keeps every bullet paying its way.
• An admission predicate (the earns-its-spot test) and a router to somewhere-else, so keeping the index small doesn't mean losing rules; they relocate to sub-docs / code comments.
• A cross-reference convention (every rule → one canonical doc) plus a conformance lint, so the index stays a map, not a second copy that drifts.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The document is governed like an artifact: a size budget bounds the per-invocation context cost, and an admission predicate — three conditions a rule must all satisfy — keeps the budget satisfiable without deleting real rules. Anything failing the predicate is routed to a sub-doc instead of the index.

def earns_a_spot(rule) -> bool:
    """Admit a rule to the booted index only if all three hold — else route it out."""
    return (
        rule.regression_preventing        # an agent touching unrelated code could violate it
        and rule.not_derivable_from_local # reading the local file wouldn't surface it
        and rule.crosses_files            # it spans files / subsystems, not one class
    )

def lint_index(rules, line_count, budget: int) -> list[str]:
    findings = []
    if line_count > budget:
        findings.append(f"index over budget ({line_count} > {budget}) — evict a rule to a sub-doc")
    for r in rules:
        if not earns_a_spot(r):
            findings.append(f"rule '{r.name}' fails the admission test — route to a sub-doc")
        if not r.canonical_doc:
            findings.append(f"rule '{r.name}' cites no canonical deep doc")
    return findings

Consequences

• A hard budget means perpetual triage. The cap is a fixed context budget, so admitting a new rule eventually means evicting one to a sub-doc. The index is never "done"; it is a continuously re-triaged working set, and the eviction call is judgment-heavy.
• Presence ≠ obedience. A rule being in the index does not make agents follow it; the index can claim a discipline that has quietly rotted. This is exactly why the Epic DoD re-runs owned lints/tests at HEAD rather than trusting the index: the meta-mechanism needs its own audit.
• Stable numbering accretes history. Never renumbering means retired rules leave gaps or tombstones; the citable namespace is durable but carries dead entries forever.
• It taxes every dispatch. The same load that makes it binding makes it a per-invocation cost across the whole fleet. The mechanism's benefit and its price are the same thing.

Example use within DocAble

• CLAUDE.md — the numbered, stable-numbered rule index; boot context for every agent.
• The governance-doc bloat lint — the cap/bloat gate.
• The rule-conformance lint — enforces the per-rule canonical-doc cross-reference.
• The "What belongs in this file" meta-section — the self-governing admission rule and router.
• The Epic Definition-of-Done's "trust nothing" re-run, which re-reads owned rules/lints at HEAD rather than trusting the index's claims: the audit that keeps the enforced document honest.

Adopt it — the starter governance doc, distilled from a real, mature CLAUDE.md: CLAUDE-starter.md. Part A is the portable method (the principles the rules instantiate); Part B is a "write your own" scaffold for the numbered project-reference rules, with the three-part "what earns a spot" admission test built in.

Related Patterns

• See also (two lenses) — docs-hierarchy: the same artifact seen as dispatch-time shared context. This entry is the enforced-infrastructure lens, the hard counterpart and the admission predicate that keep it from rotting.
• Counterpart (audit) — epic-definition-of-done: a hard re-run that verifies the soft index's claims haven't rotted (presence ≠ obedience), complementing the cap/ conformance lints that keep its form honest.
• Consumer — dynamic-context-injection reads this index as the corpus it slices, promoting the relevant subset into a specific brief.
• See also (sibling) — mandatory-snippet-table: another governance document enforced the same way (via brief-linting rather than a bloat lint).
• See also (family) — doc-hygiene-lints: the general family of "documentation with a hard-counterpart lint" this mechanism is the flagship of.