split-claude-md

Split CLAUDE.md - prune, archive, consolidate, extract, compress, scope

An always-loaded file is re-read on every request of every session. Text in it is not stored once; it is paid for continuously. Six things grow over time:

1. Old dated records load every turn even when no future session needs them.
2. Recurring bugs accumulate as scattered prose with stale instance counts, so a future session cannot tell that a "new" bug is the Nth instance of a known one.
3. Stable reference docs sit inline although they are consulted rarely, and every session that does not need them still pays for them.
4. Rules accumulate their own evidence, and the war story outgrows the rule.
5. Content the repository already answers gets written down and then goes stale, so the file starts contradicting the code.
6. Rules that only matter for one file type load in every session regardless.

There are TWO reasons to cut, and the second one is usually missed. Cost is the obvious one. Adherence is the other: a longer file is followed less reliably, which Anthropic states twice. So a file sitting exactly at its cost threshold is not finished, and a rule being ignored is a reason to cut rather than a reason to restate the rule more loudly.

Read this first

reference/loading-model.md holds the mechanics every phase depends on: what each destination costs, what loads lazily, what is free, what is lost after a compaction, and the hard limits. Read it before choosing a destination for anything. Two facts from it decide most of a run:

• @path imports do not reduce context. Imported files load at launch with the file that imports them. This is the usual wrong answer to a large CLAUDE.md and it saves nothing.
• A rule moved to a lazy destination is LOST after a compaction until a matching file is read again. A rule that fires on a FILE survives that. A rule that fires on a CONVERSATION does not, and must not be moved.

The six destinations, cheapest last