47,065 words before my first prompt

I use AI to build just about everything I work on now. Over time I've given Claude Code something like an employee handbook: a file called CLAUDE.md that it rereads at the start of every single conversation, before it can act on anything I ask. In the one session where I counted, that file, and everything it pulls in with it, came to 47,065 words before I'd typed a single request.

It got that long because I was optimizing it the only way I knew how: every time I learned something, I taught it to the system, so I wouldn't have to relearn the same lesson twice. The problem is I was writing the lesson and the rule onto the same page, and both got reread every time. In my main file, the lesson had quietly grown into more than half of it.

Why I built it this way

I work alone, with no team to catch what I miss, so CLAUDE.md does a team's job instead. It sets hard limits I don't want Claude Code crossing on its own: sending a real message or spending money means stopping and asking me first, every time, no exceptions. And it has separate sections for the different kinds of work I do: how to write, how to test something before it ships, how to think about pricing, what to check before touching anything security- or legal-related.

Every time I learned something new in one of those areas, a bad legal assumption, a security gap I'd missed, I wrote it down in the same file, right next to the rule it justified. Over months, that turned CLAUDE.md into a running log of everything I'd ever figured out, far beyond just the rules I needed on hand. I expected every recorded lesson to make the whole system smarter. Instead, the file built to make Claude Code more efficient became the thing slowing it down.

What was actually loading

CLAUDE.md itself is small. What makes it expensive is everything it points at, which loads right alongside it. Measured in the session that prompted this post:

A context window is just how much material a model can hold at once: instructions, history, files, my request, all competing for the same space. More material sitting there before I've asked anything means more for the system to sift through before it gets to what's relevant.

Why it stopped working

I only add a rule when something has actually broken. One example: I wrote a security test meant to check one person's access. It was checking the wrong person instead, so it would have passed even when it should have failed. That became a permanent rule because it was a real failure, not a guess about what could go wrong. I kept the story of catching the mistake next to the rule itself, in the same file, reread every time.

There's real research behind why this matters. Andrej Karpathy named this practice context engineering in 2025, and Anthropic has since built its own agent guidance around the same idea: give the system only what it needs, not everything you happen to have.

A separate 2023 study found something related: these systems pay closer attention to whatever sits at the start or end of a long document, and less to whatever's buried in the middle. Neither study tested anything exactly like my file. But both are a real reason to treat thousands of words of pure explanation, inside something reread constantly, as a cost worth paying down.

I still can't point to a specific case where the bloat made Claude Code get something wrong. The case for fixing it comes from research and arithmetic, not a failure I caught, and nothing in this setup would have told me if it had.

What got me to fix it

A single prompt did it. One ordinary request, and my status line, a live read of how full the context is, hit 18%. I run Sonnet, which defaults to a million-token window. That 18% covers more than my file: the system prompt, tool definitions, everything else sharing the space, counted in tokens, not words. My files were the part I could see and change. I'd never looked closely at what was in them.

Practitioners running their own tests put that drift somewhere past roughly 100,000 tokens, regardless of the advertised window. 180,000 tokens is well past that line, not approaching it. That's what got me to go measure it.

The fix: keep the rule, move the reason

I'd already tried part of this once, on my main file: I moved the reasoning behind each rule into a separate history file, leaving just the rule and a short dated pointer behind. The main file went from rule plus full explanation, about 3,600 words, to rule plus short pointer, about 540.

This time I applied that same fix everywhere else, plus one bigger lever: a Claude Code setting called claudeMdExcludes that tells it which files to leave out of the automatic load entirely. They only get pulled in when something specific calls for them.

What I changed

1. Moved the eleven topic sections to on-demand loading. They load only when the skill that needs one calls for it.
2. Trimmed the main file: 445 lines down to 291.
3. Split seven more sections the same way, moving their reasoning into separate files, so even when one loads, it's the rule and not the backstory.
4. Retired one section from autoload entirely. The pricing rules had been loading into every session for months, briefing me on pricing psychology whether I was writing code or drafting an email, and nobody was reading it.
5. Flagged the settings file itself as needing extra care to edit: a one-line change there can silently reshape what loads into every future session.

// ~/.claude/settings.json
{
  "claudeMdExcludes": ["/Users/douglaswang/.claude/rules/**"]
}

Before, Claude Code opened every session already briefed on pricing psychology and legal caution notes, needed or not. Now it opens lean and pulls those files only when the task actually calls for them.

Steal this pattern

Keep the rule, move the explanation

What to do stays in the file that gets reread every time. The reason behind it, what happened, when, who caught it, goes in a short dated note elsewhere, not a full retelling. Once the explanation outweighs a file's instructions, move the full story out and leave one line pointing to it. The common advice is to delete the old reasoning entirely, not relocate it. I think that's wrong: the history is cheap to keep, as long as it isn't sitting in the file that reloads every time.

Check whether anything you're loading has a consumer at all

One of my sections had been loading every session for months to be read by nothing. No tool, no process, ever used it. A rule nothing enforces still costs you on every task. The cheapest audit question isn't “is this rule good,” it's “what reads this.”

Question what has to load automatically at all

Moving the explanation out of a file makes it smaller. It doesn't stop the file from being read in full, every time, regardless of whether the task needs it. That's a separate question, and it's the one that saved 85% here.

Curating what loads is the actual practice; trimming a file's word count is just the easier half of it.

A prompt to audit your own CLAUDE.md

If you keep a CLAUDE.md file, or anything like it, for an AI assistant, hand it something like this:

That third question is the one that mattered here. The first and second just clean up a file. The third changes whether the file gets read at all when it doesn't need to be.

The handbook was never the problem. What I had wrong was the assumption underneath it: that everything worth keeping was also worth rereading, before every task, whether it applied or not. The operating rules still load when the task calls for them. They just don't all show up before I've said anything.

Marie Kondo's rule for a home is that everything gets a designated place, so the things you use daily stay in sight and the rest stays out of the way until you need it. Same rule here. A place for everything: the rules visible at a glance, the reasons why tucked into a drawer I only open when I need it.