A bloated CLAUDE.md is a problem. If your persistent context document is 5000 lines long, Claude reads all of it every session even when you're only touching a payment form. Context spent on rules for database replication is wasted when you're editing homepage copy.
The fix: structure CLAUDE.md as an architecture, not a monolith. Root file is a short index. Domain-specific guidance lives in hall files. Specific topics inside halls are rooms. Root loads every session; halls load on demand.
The Architecture
Root CLAUDE.md: ~150 lines. Says who you are, what's non-negotiable, and points to halls. Example:
{`# CLAUDE.md Structure — Halls & Rooms
## Halls (load on demand)
- payments.md — Stripe, invoicing, subscription state
- database.md — schema, RLS, multi-tenancy
- design-engineering.md — component API, Tailwind rules, animation patterns
- integrations.md — third-party APIs, webhooks, error handling
Read a hall when working in that domain.`}Hall files live in `docs/claude/halls/`. Each hall is 400–800 lines covering one domain. Example: `halls/payments.md` has these rooms: "Stripe Events", "Invoice Schema", "Subscription State Machine", "Error Handling".
Rooms are `### Room Name` subsections inside a hall. They contain specific, actionable rules for that topic. Frontend halls (design, components) have rooms per common component (Buttons, Modals, Cards). Backend halls have rooms per data flow (Users, Licenses, Reports).
Why This Works
Claude reads the root CLAUDE.md on every session — project overview, stack, hard rules, tone. That's overhead you accept. But when you're writing a payment form, you load `halls/payments.md` so Claude knows your Stripe webhook shape, invoice state machine, and the exact field validation rules you use.
Without halls, you'd either stuff all payment rules in the root (bloat) or leave them undocumented (Claude guesses and you correct). With halls, domain-specific knowledge is findable, reviewable, and separated from the noise.
Real Example: Design Hall
Root mention: "Design and component rules live in halls/design-engineering.md — load when building UI."
Hall structure:
{`### Buttons Room
- Use size variants: sm (12px), base (14px), lg (16px)
- Always include a loading state (icon spinner)
- Hover effect: scale 0.98, shadow-lg
- Never use button color directly; use color from \`theme.buttons.primary\`
### Modals Room
- Never use full-screen modals for data entry; use drawers instead
- Side panels (desktop) + bottom sheets (mobile)
- Z-index: 1000 base, 1001 for content inside
- Close button top-right, always visible`}When Claude edits a button, it checks the Buttons Room. When it needs modal guidance, it reads the Modals Room. No need to scroll past payment rules.
Navigation & Discovery
Keep a wiki-style index at `docs/claude/halls/index.md` listing every hall and their rooms. Example:
{`# Halls Index
**Payments** — halls/payments.md
- Stripe Events
- Invoice Schema
- Subscription State Machine
**Database** — halls/database.md
- Auth & RLS
- Multi-tenant Schema
- Migrations`}Claude can search this when deciding which hall to read, so context isn't lost.
The Rule
Root CLAUDE.md loads once per session. Halls load explicitly when the task touches that domain. Rooms inside halls are read on demand. If a rule spans multiple rooms or affects multiple components, mention it in the root under "Cross-Cutting Concerns". If it's specific to one payment flow, keep it in the Payments hall.
Bottom Line
Your CLAUDE.md can scale from one file to ten halls with fifty rooms without drowning Claude's context window. Root stays lean, domains stay discoverable, and specific rules stay specific. Better session quality, fewer corrections. Set up halls once, reap the benefit for every feature after. See `/pricing` for a breakdown of when halls save the most time, and read more on our complete production playbook.