Every Claude Code session opens by reading your CLAUDE.md file. It is the first thing Claude sees, and it colours every answer that follows. A tight file makes Claude behave like an engineer who already knows the repo. A bloated one quietly taxes every request you send, in tokens you pay for and in attention the model spends reading filler instead of solving the problem in front of it.
At Automata AI we review a lot of these files for Australian teams picking up Claude Code, and the same failure modes turn up again and again. The good news: fixing a CLAUDE.md is a half-hour job with an outsized payoff. Here is what bloats context, what actually belongs, and how to tell the two apart.
Why a bloated file costs you twice
The file is re-read at the start of every session and rides along in context for the whole conversation. That carries two costs. The first is money, because those tokens are billed on every turn. The second is quality, and it matters more. When Claude is holding several thousand tokens of repository trivia, the signal you actually care about competes with noise, and instruction-following gets measurably worse.
Put rough numbers on it. A Sydney team of eight engineers, each running dozens of sessions a day against a file four times larger than it needs to be, can burn millions of extra input tokens a week for context that makes answers worse rather than better. Depending on the model, that is a five-figure line item over a year, often $15,000 or more, spent on filler. Trim a 5,000-token file down to about 1,200 tokens of genuine signal and most of that waste simply disappears.
The anti-patterns that bloat context
Almost every oversized CLAUDE.md is made of the same recurring mistakes. If your file contains any of these, they are candidates for the cut:
The pasted README. Onboarding prose written for humans, most of which Claude can read straight from the code when a task actually needs it.
The full file tree. Long directory listings go stale the moment someone adds a folder, and Claude can list files itself in seconds.
Aspirational rules. "Always write a test for every function" reads well, but if the repo does not really do that, the instruction is noise the model learns to ignore.
Restating the obvious. Telling Claude "this is a React project" when package.json already says so earns nothing.
Stale commands. A build or deploy step that changed three months ago now steers Claude wrong on every run.
The copied style guide. Forty lines of formatting rules your linter already enforces on save.
Conflicting instructions. Two sections that quietly disagree, so Claude picks one at random and you cannot tell which.
What actually belongs
A useful CLAUDE.md is dense with things Claude could not have guessed. The keepers are the facts that are true, current, and expensive to rediscover:
The commands that are not obvious: how to run the test suite, the one lint command, how to start the dev server, any non-standard build step.
Architecture decisions you cannot infer from a single file: why state lives where it does, which module owns what, the boundary between two services.
Conventions the code does not announce: naming patterns, the folder where new API routes go, the commit style you enforce.
Landmines: do not edit the generated directory, never run the migration script against production, the file that looks safe to change but is not.
Project facts with no home in the code: the staging URL, the ticket prefix, who to tag on a release.
The test is simple. If Claude could work it out by reading one or two files, leave it out. If it would take ten minutes of searching, or if getting it wrong breaks something, write it down.
How to trim a CLAUDE.md in half an hour
You do not need a rewrite, just an honest pass with a delete key. Work through it in this order:
Measure it. Count the tokens. For a single repo, anything past roughly 1,500 tokens deserves a hard look.
Delete anything the model can infer. Language, framework, file tree, obvious structure. Claude reads all of that from the code.
Move depth into linked docs. Keep a one-line pointer in CLAUDE.md and let Claude open the full document only when the work calls for it.
Cut the aspiration. Describe how the code behaves today, not how you wish it behaved.
Re-read it monthly. Stale facts are worse than missing ones, because a missing fact makes Claude search while a wrong one makes it confident and wrong.
The governance angle for regulated teams
For a business under APRA supervision, or one handling personal data covered by the Privacy Act, a CLAUDE.md earns its place as a guardrail rather than a convenience. This is where you write the rules that keep an eager assistant inside the lines: do not paste customer records into prompts, do not touch the payments module without a second review, keep secrets out of committed files. Those lines are worth every token they cost. A directory listing is not.
The pattern that works for Australian teams is to keep the guardrails short and specific, and to make them the part of the file you review most often. A rule nobody reads protects nobody, so the same discipline that keeps the file small also keeps the important parts visible.
The short version
A good CLAUDE.md is brief, current, and full of things Claude could not have worked out on its own. Everything else is rent you pay on every single request. Measure the file, cut what the model can infer, keep the guardrails and the genuinely hard-won context, and re-read the whole thing once a month.
If you would like a second pair of eyes on how your team is running Claude Code, we help Australian businesses set this up properly and keep it that way. You can book a free brainstorm on our contact page.
