Short answer: treat bootstrap files as a thin always-on index, and put durable knowledge in reviewed memory cards plus handoffs. Brigade enforces bootstrap budgets, wires handoff inboxes, and (with Memory Doctor / Bootstrap Doctor) lints dead links and oversize files.
The problem
It is easy to paste every preference, runbook, and incident into CLAUDE.md or AGENTS.md. The file becomes the single source of truth and the single failure mode: token waste, stale claims, and agents that never see the last half of the file.
The Brigade path
brigade operator quickstart --target . --harnesses claude
brigade doctor --target . # bootstrap budgets, card links, handoff inboxes
brigade handoff draft --inbox claude ... # durable note, not another CLAUDE.md paragraph
brigade ingest --target . --promote-cards
brigade add memory # memory-doctor + bootstrap-doctor when you want deep auditsRules of thumb:
- Bootstrap (
AGENTS.md,CLAUDE.md,USER.md,TOOLS.md): short, stable, always loaded. - Cards under
memory/cards/: atomic topics, linked fromMEMORY.md. - Handoffs: session-to-session facts with evidence, then promote or discard.
Related tools
| Tool | Role |
|---|---|
| Brigade doctor | bootstrap size budgets, broken card links, inbox presence |
| Memory Doctor | dead links, pending handoffs, memory index health |
| Bootstrap Doctor | soft/hard limits on bootstrap files |
| Handoffs compare page | multi-agent handoff path |
When this is enough
Use this layout when bootstrap files keep growing and quality drops. Keep a single personal CLAUDE.md only if it stays under a few hundred lines and you have one harness.
Questions
Will Brigade delete my CLAUDE.md? No. Doctor warns and budgets; you choose what to split into cards.
Is this only for Claude Code? No. The same slim-bootstrap pattern applies to Codex, Grok, Hermes, and other writers. Claude is just where bloat shows up first for many people.
See memory ownership and handoff docs.