Your Claude Code context window can be half full before you type a word. One developer found their project rules taking up 454,900 tokens at the start of every session, which was enough to crash a subagent asked a one-line question.
They fixed it without deleting a single rule. They moved the rules instead, and the fixed cost fell by 85.8%.
Key takeaways
- At the start of every session, Claude Code loads
CLAUDE.md, everything it imports with@, and every rule file that has nopaths:field. - In one repository that added up to 487,500 tokens before the first prompt. That is 49% of a 1-million-token window and 244% of a 200,000-token one.
- Three changes brought it down to 96,600 tokens: path-scoped rules, splitting rules from records, and looking things up on demand.
- A CI check with an 80,000-token budget now stops the bloat from creeping back.
What actually happened?
A subagent is a helper Claude instance that the main session starts for a side task. This one got a one-line question about Claude Code’s documentation and failed before its first step with Prompt is too long: 347,814 tokens against a 200,000 limit.
The question itself added almost nothing. The window was already full of the project instructions that every session in that repository gets at start. The developer wrote up the investigation in a detailed post on dev.to on 22 October 2026. The repo figures below come from their measurements.
On 15 October 2026 they ran /context in a fresh session on Opus 5.5 with a 1-million-token window. Project instructions alone came to 454,900 tokens. The system prompt, tools, skills and agents added 27,900, and auto memory added 4,700. That made 487,500 tokens used before anyone asked anything.
Why does the Claude Code context window fill before you start?
Some instructions are a fixed cost. Anthropic’s memory documentation lists three things that load at launch:
- the project
CLAUDE.md - every file it imports with
@path, up to four hops deep - every file in
.claude/rules/that has nopaths:frontmatter (the settings block at the top of a file)
The docs say plainly that imports “help you organize a long file but don’t reduce its context cost.” They also suggest keeping each CLAUDE.md under 200 lines. Think of it as a rucksack you carry on every errand, even a quick trip to the corner shop. Everything you pack goes with you every time.
In this repo the load grew quietly. By the developer’s estimate, the rule files totalled 8,600 tokens on 1 April 2026 and 441,100 on 14 October 2026. Three files made up almost half of the project instructions: a test rule at 124,000 tokens, a register layout rule at 70,700 and a brand rule at 28,600.
Why did the subagent crash when the main session didn’t?
The main session had a 1-million-token window, so being half full was fine. The subagent ran on a model with a 200,000-token window. Custom subagents load the same CLAUDE.md files as the main session, project rules included. The subagent documentation says only the built-in Explore and Plan agents skip them, plus any custom agent whose definition sets omitClaudeMd.
This has happened before. In GitHub issue #41208, opened on 30 March 2026, a user on Claude Code 2.1.87 reported that every subagent failed with the same error while the main Opus session worked. Their workaround was to give the subagent a model with a larger window. The issue was closed as “not planned” on 4 May 2026 after it went stale.
The three levers that cut 390,200 tokens
The developer’s key idea is the difference between a rule, which guides the next decision, and a record, which documents a past one. Both belong in the repository. Only rules need to be in context at start.
| Lever | What changed | Tokens saved |
|---|---|---|
| Bind rules to paths | Rule files with paths: went from 3 of 30 to 24 of 30 | 264,300 |
| Separate rule from record | A 162-row test inventory moved to docs/inventories/, and the test rule fell from 124,000 to 20,300 tokens | 103,700 |
| Look up, don’t preload | The roadmap moved out, the feature index is no longer imported, and only the first 30 lines of the bug register are read | 25,500 |
| New overhead | A rule map (one line per rule) plus a convention | -3,300 |
Project instructions fell from 454,900 to 64,700 tokens. The total before the first prompt fell from 487,500 to 96,600, which is 10% of a 1-million-token window instead of 49%. The subagent that crashed now starts with 66,887 tokens and answered its question correctly.
What are the traps when you scope rules to paths?
- Rules arrive late for new files. A scoped rule loads only when Claude reads, writes or edits a matching file. So a new file can be written before its rule loads. The developer deliberately kept the rules that apply when a file is created global (31,300 tokens).
- Unquoted globs fail silently. A glob is a file-matching pattern. One like
**/*.tsxwithout quotes breaks the YAML. Anthropic’s docs confirm that when the frontmatter doesn’t parse, the rule loads as if it had nopathsat all. Runclaude --debugto see the parse error. - Scoping changes who sees a rule. A review skill that only read
git diffoutput never opened the SQL files, so the SQL rules never loaded. The fix was to have the skill read those rules directly.
Measure instead of guessing. The developer first estimated 3.7 bytes per token and got about 244,000 tokens. Their files actually came to 2.0 bytes per token, so that first estimate was almost half too low.
How to audit your own repo
- Open a fresh session, run
/contextand note the size of your memory files. - Find every file in
.claude/rules/that has nopaths:field. For each one, ask whether it really applies to every task. - Move inventories, logs and changelogs out of rule files and into
docs/, and leave a pointer behind. - Replace large
@imports with a short map that tells Claude where to look. - Add a CI check with a token budget. The developer’s script divides bytes by 2.0, which they say lands within about 2% of
/context.
My opinion: this is the agent-era version of a bloated node_modules folder. Nobody adds 400,000 tokens on purpose. They pile up one helpful row at a time. If you already evaluate your AI agents before you ship, add context size to that checklist.
What happens next
Claude Code now has more ways around the problem than it did in spring 2026. Custom subagents can set omitClaudeMd: true (from v2.1.271), and the CLAUDE_CODE_SUBAGENT_MODEL environment variable picks the model for subagents. Neither one shrinks a bloated rules folder. They only work around it.
Expect teams to start tracking fixed context cost the way web teams track bundle size. You pay for every preloaded token again in every session and every subagent, and that adds up the same way agent usage limits run out faster than chat ones. Also keep in mind that the measured number is the minimum cost, not what a normal working day costs.
FAQ
Do @ imports in CLAUDE.md save context?
No. Imported files load at launch along with the CLAUDE.md that imports them. They make the file tidier but cost the same tokens. Only path-scoped rules and on-demand reads push the cost later.
Why do I get “Prompt is too long” from a Claude Code subagent?
Usually the subagent’s starting context, including your project rules, is bigger than its model’s window. You can trim the rules that always load, set omitClaudeMd on custom agents that don’t need them, or give the subagent a model with a larger window.
How big should CLAUDE.md be?
Anthropic suggests under 200 lines per CLAUDE.md file. Move rules that only cover part of the codebase into path-scoped files. Check the real size with /context, because line counts can mislead.
Next step: open a fresh Claude Code session in your busiest repo, run /context and write down the number. That is your fixed cost, and now you know how to shrink it.
2 comments