The Day My CLAUDE.md Ate a Third of Every Session

The Setup

For a few weeks I had been hitting the compaction limit in Claude Code after only a handful of messages. Worse, a brand-new session showed itself as roughly 60 percent full after my very first message. I assumed it was the conversations getting long. It was not.

I asked Claude to explain it, and the first thing it did was measure what gets loaded before a session starts. The answer was sitting in my own project: CLAUDE.md had grown to nearly 300 KB. Well over a hundred sections. A list of pipeline commands for every library and museum I ingest, one line each with a long comment. Every Android build-guard rule. Every origin story for every bug I had ever fixed. All of it, every session, before any work began.

The first measurement, before anything changed. Shares are of a 200,000-token window; the exact bytes and the token estimates behind them are one tap below each table:

Ranking the sections showed where the bytes were. Two sections were a third of the file on their own:

The reason it had grown that way was also my own doing. Four of my rules said that every learning, every mistake, and every "going forward" commitment must be written into CLAUDE.md in addition to a memory file. I had built a file that could only grow.

The First Cut

The quick win was obvious once measured. The pipeline command list moved into its own file that gets grepped on demand. The Android rules moved into a nested CLAUDE.md inside the Android folder, which Claude Code only loads when it touches that directory. An eighty-row table saying the same thing about every script collapsed into two sentences. The root file dropped by about a third with nothing deleted.

The three files after the cut held 287,184 bytes against the original 288,225; the difference is the collapsed table, a few rewritten policy rules, and the new file headers:

Before doing any of it I asked the question I ask on every non-trivial change: have you thought about all the scenarios? That question turned up things the plan had missed. Two skills wrote new sources into the pipeline section by name and would have written to the wrong file. A memory file would have re-taught the old location every session. My PreCompact hook, the one that refuses to compact until a session note is saved, meant auto-compaction never ran at all, so hitting the limit felt abrupt because the session simply stalled. And the folder is not a git repository, so a bad edit had no undo. I backed the file up first.

Two guards came out of that pass. The fetcher lint got a new check that fails when a fetcher has no entry in the commands file, because a file that becomes the only registry of something needs a drift guard the day it is created. And a hook now warns whenever a rules file is written above a size budget.

My Idea: One File Per Platform

The first cut was good but not enough. I suggested going further: separate rule files for iOS, Android, the pipeline, and the web, so a session loads only the rules for what it is working on. Claude liked the idea and produced a bucketing of the remaining sections by heading keyword.

This was that first pass over the 181 KB root. The cross-platform row is the one that turned out to be wrong:

I asked the scenarios question again. This time Claude's own answer opened with "my previous answer had two mistakes." The keyword sort had filed rules that bind two platforms, like the series start-date rule and the event-field rule that iOS and Android must both follow, under a single platform. And "move process rules into the skills" was only half right: a rule that triggers a skill cannot live inside the skill, because the skill is not loaded until it runs. The corrected design kept a smaller root of cross-platform contracts and "before you act" rules, and it raised a question nobody could answer by reasoning: when does a per-platform file actually load?

The Loading Test

Claude Code supports a rules folder where a file can declare which paths it belongs to, and the docs say such a file loads when Claude reads a matching file. Claude wrote three marker files, one scoped to the iOS folder, one to the pipeline folder, and one unscoped as a control. Then it ran the test inside subagents, because a headless session could not authenticate from inside the desktop app, and I ran the two checks only a real fresh session could answer.

Every step, where it ran, and what was visible afterwards (Claude Code 2.1.81):

The findings changed the design:

• Only the normal file reader triggers a scoped file. Reading a file through the terminal, which is how Claude had read almost everything that week, loads nothing.
• A subagent keeps what it loads to itself. The main session never saw the markers the agents loaded.
• Scoped files are dropped at compaction. Only the unscoped control and the root file came back after /compact.
• The rules folder is recognised on my version, and a folder name with a space works in the glob.

So automatic loading became a bonus, not the mechanism. The root file now opens with a table saying which file to read before which kind of work, that the read must be repeated after any compaction, and that any subagent must be told to read it too.

One correction along the way was mine and small, but it went into memory anyway: Claude kept calling the morning's work "yesterday's move." All of this happened in one afternoon. There is no clock between turns, and the length of a conversation is not evidence that a day has passed.

The Split

I asked for the classification table before anything moved. Claude sorted every section by hand into destinations, saved the mapping as a file the split script would consume, and showed me the judgment calls it wanted me to be able to overrule. I made two changes. I asked for the files to be named CLAUDE_IOS.md, CLAUDE_ANDROID.md and so on, which works inside the rules folder even though it would not at the project root. And I asked for analytics to get its own file, because analytics cuts across every platform and had been sitting in the iOS bucket.

The hand classification, after the analytics file was added, is what the split script consumed:

The split itself ran in one pass and verified that every original section landed exactly once. The root file ended the day at under 60 KB, down from nearly 300 KB that morning. A sanity read caught one slip: the root's title line and its first heading had been glued together because the split lost a newline. Fixed before I saw it, but it went on the list.

Where everything ended up, measured at the end of the day. Every one of the 113 original sections is present exactly once across these files, verified by heading:

And what that means per session. The floor dropped for everyone; the ceiling, a session that touches every platform, is roughly unchanged:

An analytics change on any platform adds the 18 KB analytics file, about 2 percent of the window, on top of that platform's row. It is a topic file, not an iOS one, which an earlier version of this chart got wrong by listing it only for iOS.

On a 200,000-token window, a general session now starts at roughly 30 percent full instead of roughly 60.

Where Claude Got It Wrong: The Android Analytics Rules

After the split Claude listed what it had deliberately left for later, including that the web and SwiftUI subsections inside the analytics rules were still together. I read that and asked: what about Android?

There was no Android subsection because the Android analytics rules had never been in the analytics section at all. They were two bullets inside the old Android section, so the split carried them into the Android file only. A second block, the cross-platform checklist for adding a new analytics parameter, was inside the iOS push-notification rules, so it went to the iOS file only. The practical effect: an iOS session adding an event would never have seen the rule that the reference CSV must be updated in the same change, and an Android session reading the analytics file would never have seen the rule to copy iOS event names exactly.

Claude moved both blocks into the analytics file and left pointers behind. Its own explanation was the useful part: this was the same class of mistake as the keyword sort. It had classified by section, and analytics rules were hiding inside sections about other things.

The gap was real bytes, not phrasing. This is how the three files changed when the rules moved:

The Guards

Then I asked the question that ends most of my sessions: what can we do so none of this happens again, not just the last one, all of it? The honest answer was that every mistake that day was the same kind, checking the shape but not the content, and every one happened with the relevant rule already in context. Advisory rules did not prevent any of them. So each became a named check:

• A rule-file lint. It fails on a glued title, a rule file without a paths header (which would load every session and undo the split), a file over budget, a file not named in the root's read-first table, an import of a rule file into the root, a nested platform CLAUDE.md that would double-load, duplicate headings, and stale paths. It warns when analytics keywords appear in any other rule file. On its very first run it found one more analytics checklist hiding inside the cross-platform parity rule.
• A session-note lint. Earlier that day a transcript append had silently never run because a validation inside an && chain failed while a trailing echo still printed "appended," and the command log then landed inside a quoted block. The checker verifies the note's live structure, which required switching to four-backtick fences so a quoted command body cannot close the outer fence.
• A hook that runs both. It fires after any tool call and checks whatever rule file, skill, or session note changed in the last two minutes, feeding failures straight back to Claude before the turn ends.

What each check caught on its first run:

The learnings-routing rules changed too. Memory files are now the primary store. The root gets an entry only for a standing rule, kept short, with a link to the memory for the story. The file that could only grow now has a budget and a reason to stay small.

Learnings

• Measure the fixed load before blaming the conversation. A rules file is read whole into every session; its size is the floor under every session, and compaction restores it in full.
• A rule only helps if it is read at the right time. Scoped rule files load on one kind of read, not from the terminal, not in subagents, and not after compaction. Make the read explicit and treat auto-loading as a bonus.
• Sort rules by content, never by heading. Cross-platform rules and topic rules hide as bullets inside sections about something else. A keyword grep across every file is the only classification that works.
• Keep "before you act" rules where every session sees them. Deploys, deletes, and builds do not involve reading a file, so a platform file would load too late or never.
• Every mistake becomes a check the same day. Advisory rules were in context for all of them and prevented none. The lint that came out of the last mistake found the next one on its first run.
• Ask the scenarios question twice. The first time it found the skills and the hook. The second time it made Claude say "my previous answer had two mistakes." Both times it changed the design.