Split Memory: Modular CLAUDE.md Strategy

Core Principles

1. Start monolithic, split when it hurts — A single CLAUDE.md is simpler to maintain, easier to understand, and has no conflict risk. Only split when the file exceeds ~300 lines, when multiple teams need different instructions, or when finding the right rule takes too long.

2. Root CLAUDE.md is the index — After splitting, the root CLAUDE.md becomes a concise index that points to detailed files. It contains only universal rules and references. Think of it as a table of contents, not the full book.

3. Claude auto-discovers .claude/ files — Claude Code automatically reads files in the .claude/ directory. Use this to your advantage: place instruction files where Claude will find them without explicit loading directives.

4. No conflicting instructions across files — When instructions span multiple files, contradictions cause unpredictable behavior. Establish clear precedence: root CLAUDE.md > module-level > team-level. Never define the same rule in two places.

5. Split by a single axis — Split by concern (architecture, testing, API) OR by module (Orders, Catalog, Identity) OR by team. Never mix axes — it creates overlapping ownership and conflicting rules.

Patterns

Pattern 1: Single File (Default)

For most projects, one CLAUDE.md is sufficient: