We cut our CLAUDE.md from 548KB to 34KB: what loads when, measured — and the commit gate that keeps it small
Our CLAUDE.md was 548KB. Every session — including every subagent — loaded all of it before doing any work. One measured headless run wrote about 150,000 tokens to cache before the actual task started, and the file itself was the dominant contributor. This week we cut it to 34KB without deleting a single obligation. This is the write-up I wish I'd had before starting: what the docs actually…
Our CLAUDE.md file was 548KB in size. It loaded in full for every session, including subagents, before performing any task. A headless run wrote 150,000 tokens to cache prior to the actual task, and the file itself was the main contributor to the size. The migration reduced the file size to 34KB without deleting any obligations.
This write-up explains what the docs promise about each mechanism, the numbers from the migration, and two issues that emerged - one caught by a commit gate and one that made it to production. The key to the success of the reorganization is understanding what belongs in CLAUDE.md and what doesn't. CLAUDE.md loads into every session, consuming context and reducing adherence if it's over 200 lines.
Imports do not reduce context size and are for organization/deduplication only. Path-scoped rules load on demand, only applying when relevant files are being worked with. Skills load in two stages, with the description always in context and the full body loading when the skill is invoked. This mechanism absorbs procedures. Maintainer notes were previously costing tokens, but they are free now.
The migration resulted in a 500KB reduction, mostly from procedures and history. In subagent-heavy environments, shrinking CLAUDE.md reduces the fixed overhead of every spawned agent. Enforcement mechanisms were added to prevent the slimmed file from regrowing. A size check warns at 45KB, alerts at 60KB, evaluated every session.
A structure commit gate fails the commit if CLAUDE.md references a missing skill directory, if a skill exists without a trigger, or if a rules file lacks paths frontmatter. The gate caught a real dangling reference during the migration. The most significant issue that reached production behavior was missed freezing, where the records didn't accurately reflect the intended state.
Moving forward, freezes need a first-class representation, and disabling workflows requires a first-class representation in the system.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
