Bootstrap Doc Pattern

The file an agent reads first, every session. Two files together: one for non-negotiables, one for routing.

TL;DR (human)

CLAUDE.md (or AGENTS.md per your toolchain) at the repo root, loaded automatically. It carries the eight non-negotiables, the build commands, and a pointer to a separate AGENTS.md (routing table). Under 200 lines. Updated only when the rules change.

For agents

Why two files

CLAUDE.md: non-negotiables. Stable. Mirror of the rules in ../../README.md. Updated rarely.

AGENTS.md (or equivalent): routing. Volatile. Updated when packages get added, renamed, merged. Lists every package + which surface it owns.

Why separate: the routing changes far more often than the rules. Keeping them in one file forces a rule re-read every time a package is renamed, which is wasteful. Keeping them separate lets the rules cache in the agent's working memory across sessions while routing stays current.

CLAUDE.md shape

Six sections, in order:

1. Title + one-paragraph repo at a glance. Stack, package count, app count, top-level layout.
2. Pointer to the canonical doc. "AGENTS.md is the routing table — read it first when you don't know which package to touch."
3. Non-negotiables. The eight-rule kernel (see ../../README.md) trimmed to what applies to this codebase, numbered.
4. Before you ship. The exact commands (lint, test, gate). Per-package versus whole-repo distinction.
5. Where to look next. Five-row table mapping intent to doc path.
6. When a doc contradicts the code. "The code wins. Update or remove the doc."

Template: ../../templates/CLAUDE.md.template.md.

AGENTS.md shape

1. TL;DR philosophy — 3–5 numbered statements. Why this codebase looks the way it does.
2. Mental map — 4–7 logical groups, each with the packages in that group and the concern they own. Agents triage faster by group than by alphabetical name.
3. Routing table — two-column: "I want to change…" → "Edit…".
4. Workflow — verify-first; one sub-unit; intent manifest; self-review.
5. When something is unclear — escalation path (read for-agents doc → ADR → code → open discuss: issue).

Template: ../../templates/AGENTS.md.template.md.

Length discipline

• CLAUDE.md: ≤ 200 lines (the agent reads it whole every session).
• AGENTS.md: ≤ 400 lines; if it grows past that, split per-package detail into docs/for-agents/packages/\<pkg\>.md and link.

If either file is over budget, agents skim instead of read. Skim defeats the purpose.

Versioning

These files are part of the code. They go through PR review. Changes to the non-negotiables require an ADR (the rule change IS an architecture decision).

Routing-table changes do not require an ADR — they reflect the codebase, which itself went through ADRs.

Gate

Recommended automated checks:

1. Existence — CLAUDE.md (or AGENTS.md) must exist at the repo root. CI fails otherwise.
2. Size budget — CLAUDE.md ≤ 200 lines.
3. Routing currency — every package in the workspace appears at least once in AGENTS.md's mental map or routing table. Stale entries (referring to deleted packages) fail.

Reference impl: a check-agent-docs.example.mjs in ../../scripts/ (ship in a future session).

Common failure modes

• One mega-file. Non-negotiables + routing + per-package detail all in one place; 1500 lines; agents read the first 300 and miss the rest. → Split into the two-file pattern.
• Routing table out of date. Lists a package that was renamed 3 weeks ago. Agents follow it, fail. → Make routing currency a gate.
• Non-negotiables marketed as "guidelines". Hedged language ("try to", "prefer"). Agents treat hedged rules as optional. → Imperative voice. "No any." not "Avoid any when possible."
• CLAUDE.md references files that no longer exist. → Gate that resolves every relative link.

See also

• memory-pattern.md — MEMORY.md index loads alongside CLAUDE.md.
• ../architecture/universal.md — the non-negotiables come from here.
• ../../templates/CLAUDE.md.template.md, ../../templates/AGENTS.md.template.md.