Why Your CLAUDE.md File Might Be Costing You More Tokens Than It Saves

CLAUDE.md is one of the best habits a Claude Code user can build: a file describing your project's conventions, commands, and gotchas, read automatically at the start of every session so you don't have to re-explain them each time. It's genuinely useful. It's also easy to over-build, and past a certain point, the file that was supposed to save you tokens starts quietly costing you more than it saves.

Here's how that happens, and how to tell if it's happening to you.

The trade you're actually making

Every CLAUDE.md file gets loaded into context at the start of a session, whether or not any given task needs most of what's in it. That's the core trade: you're paying a fixed context cost on every single session in exchange for not having to re-explain things in the sessions where they'd actually come up.

That trade is a clear win when the file is short and the information in it is genuinely needed often, your test command, your directory structure, the one non-obvious constraint that trips people up constantly. It stops being a clear win when the file grows to cover everything you can think of, on the theory that more context can only help. It can't, every line is competing for space with the actual task at hand, and a bloated CLAUDE.md shows up as the same kind of degradation as any other bloated context: slower responses, missed details, occasional confusion about what's actually relevant right now.

Signs your CLAUDE.md has crossed the line

• It's long enough that you've forgotten what's in it. If you couldn't summarize your own CLAUDE.md from memory, it's not functioning as a quick-reference anymore, it's just weight.
• Most sections are relevant to only a fraction of tasks. Deployment instructions, a style guide for a subsystem nobody's touched in months, a changelog of past decisions, useful to have written down somewhere, but not useful to load into every single session regardless of what that session is about.
• It duplicates what's discoverable from the codebase itself. Claude Code can read your package.json, your test config, your directory structure. A CLAUDE.md that just restates what a quick look at the repo would reveal is spending tokens to save an exploration step that often isn't expensive in the first place.
• It reads like documentation, not like a briefing. A README explains a project to a new team member who has unlimited time to read it. A CLAUDE.md gets re-read, in full, at the start of every session, the bar for what belongs in it is much higher.
• You've started adding exceptions and caveats to earlier entries. This is a natural growth pattern, a rule gets added, then a case where the rule doesn't apply gets added as a caveat, then another caveat. Each is individually reasonable; the cumulative result is a file that takes real effort to parse correctly, for a model as much as for a person.

What actually belongs in it

The highest-value content is short, stable, and applies broadly:

• Commands you'd otherwise have to explain every time, how to run tests, how to build, how to lint, and what "the tests pass" actually means in your setup if it's non-obvious.
• Non-obvious constraints that would otherwise cause real damage if violated, "never commit directly to main," "don't touch legacy_auth.py, it's still load-bearing for the old mobile clients." The reason matters as much as the rule; a bare instruction is more likely to get accidentally worked around than one with context for why it exists.
• Conventions that aren't inferable from the code, a naming scheme, an architectural decision that isn't visible just by reading files, a "we do X instead of the more common Y because Z."
• Where things live, if your project's structure is unusual enough that discovery would otherwise take real exploration time.

Notice what's not on that list: exhaustive style guides, full architectural documentation, a history of past decisions and why they were made, anything that's really a wiki page rather than a briefing.

What belongs somewhere else

A lot of what ends up in an over-stuffed CLAUDE.md isn't wrong to write down, it's just misplaced:

• Deep architectural rationale belongs in actual documentation the model can read on demand when a task touches that area, not in every session regardless of relevance.
• Rarely-needed procedures (a quarterly migration script, a one-off deployment process for a legacy service) belong in their own file, referenced from CLAUDE.md rather than inlined into it.
• Anything genuinely task-specific belongs in the prompt for that task, not as a standing instruction loaded every time.

A good pattern: keep CLAUDE.md itself lean, and let it point to other files for anything detailed, "see docs/deployment.md for the full release process" costs a line, versus inlining the whole process and paying for it in every unrelated session.

A rough test

Before adding something to CLAUDE.md, ask: would I want this loaded into context for a session that has nothing to do with it? If the honest answer is no, it probably belongs in a more targeted place, a linked doc, a comment in the relevant code, or just something you mention when it's actually relevant, rather than in the file that gets read every single time.

CLAUDE.md earns its keep by being the small set of things that are almost always worth knowing. The moment it starts trying to be everything worth knowing, it stops being a shortcut and starts being its own kind of overhead.