Treat CLAUDE.md as a routing table

Agent instruction files grow. Someone corrects the agent, a line gets added, and six months later the file is three hundred lines of accumulated rules that get loaded on every single turn whether they apply or not.

The fix is a reframe. Your instruction file is a routing table, not a content store.It tells the agent where to look. The domain knowledge lives in the files it points at. The routing table itself should almost never change, because it's the index rather than the encyclopedia.

That changes the question you ask. Instead of “what should I add to this file,” you ask “where does this knowledge live, and does the routing table point there.”

Six items, and that's the file

1. Project description. Two or three sentences on what this codebase or vault is. No history, no aspirations.
2. File structure map. Top-level folders, one line each, so the agent never scans blindly.
3. Identity context. Who the agent is acting as, for whom, toward what outcome.
4. Knowledge routing. Pointers to the domain files. Voice file, patterns file, metrics, platform folders.
5. Workflow pointers. The skills, commands, or procedures to invoke for specific kinds of task.
6. A self-improving prompt. Three lines, below.

The three lines

1. Before starting any task, review existing rules and hypotheses for this domain.
2. Apply confirmed rules by default to your work.
3. After completing work and receiving feedback, update rules and hypotheses based on what you learned.

Every session becomes a knowledge update without manual rewriting. The system starts discovering its own patterns and ranking them by evidence, as long as you let it write to the domain files rather than treating them as read-only.

Where the knowledge actually goes

• Writing style rules, in a voice file per channel
• Good and bad examples, in a patterns file
• Platform-specific instructions, in a folder per platform
• Historical metrics, in their own file
• Hypotheses and confirmed rules, one file per domain
• Detailed procedures, in skill folders

The agent reads the routing table, works out which domain it's in, and loads only what that requires.

Freshness beats size

File length is the wrong metric. A six-item file looks pristine and is still useless if half the items haven't changed the agent's behavior in a month.

Two checks worth running:

• For each rule, when did it last actually change what the agent did?
• Stale rules still cost tokens on every turn. Delete them, or move them into a domain file that only loads on demand.

The context tax

A growing instruction file is an unbounded tax you pay on every turn. Every line is re-read, every time, forever. The routing-table model treats it as the smallest possible front door, with everything else loaded only when the task calls for it.

If you run several of these across projects, the same rule applies at each level. The global file holds identity and universal rules and points at the rest. Per-project files hold stack-specific rules only. Neither should duplicate what the other already says.