03 — The rules/ Directory

When CLAUDE.md gets long, split it. A rules/ directory holds small, domain-specific files that load only when relevant. The main file stays scannable; context enters when it matters.

The Problem with One Big File

A single CLAUDE.md that covers agents, design rules, database conventions, git workflow, and MCP references all at once has two failure modes:

Claude front-loads all of it into context every session, whether or not it's relevant.
You stop updating it because it's too tangled to edit confidently.

The fix is to split by domain and load on demand.

The Pattern

~/.claude/
├── CLAUDE.md          ← short, pointers only
└── rules/
    ├── agents.md      ← when and how to spawn specialist agents
    ├── design-dna.md  ← visual and animation standards
    ├── mcp.md         ← which MCP servers exist and what they're for
    └── database.md    ← schema conventions, migration rules

CLAUDE.md references these files but doesn't inline them:

Full agent reference (load on demand): `~/.claude/rules/agents.md`
Design rules: `~/.claude/rules/design-dna.md`

Claude reads the pointer. It pulls the file when the task requires it — not before.

The @-Import Trigger

For context that should load automatically at session start, use @-imports at the top of CLAUDE.md:

@~/.claude/rules/design-dna.md
@~/projects/my-app/context.md

These load immediately. Use @-imports sparingly — only for rules that apply to nearly every session. Everything else stays as a prose pointer.

Naming Conventions That Work

Name files after the domain they govern, not after their format. A few examples:

File	What it covers
`agents.md`	Which specialist agents exist, when to use each
`design-dna.md`	Visual standards — typography, color, animation rules
`mcp.md`	Available MCP servers, prefixes, usage sequencing
`git.md`	Commit conventions, branch naming, PR rules
`database.md`	Schema patterns, migration workflow, query rules

The filenames become part of the mental model. When Claude sees "design feedback → load design-dna.md" in context, the mapping is obvious.

What Goes in Each File

Keep each rule file narrow. A good rule file:

Covers one domain
Fits in a single scroll
Reads as instructions to Claude, not documentation for humans

If you find yourself adding a "for context, here's some background" section, trim it. Rule files are directives, not explanations.

Project-Level Rules

The same pattern works at the project level. A .claude/rules/ folder inside a repo can override or extend global rules for that project:

my-app/
└── .claude/
    ├── CLAUDE.md       ← project-specific pointers
    └── rules/
        └── api.md      ← route conventions specific to this codebase

Global rules apply by default. Project rules supplement or override where they conflict. Local machine rules (in settings.local.json or a local CLAUDE.md) sit on top of both.

The mental model: global → project → local, narrowing scope at each layer. Rules files follow the same layering as settings.json.