Last updated: July 2026
Claude Code loads your CLAUDE.md into context at the start of every session, so every wasted line is a recurring per-session token tax. To save tokens, keep it lean and high-signal: state durable facts, conventions, and commands; reference files instead of pasting them; prune regularly; and scope per-directory files.
CLAUDE.md is the most read file in your project — Claude Code loads it before you type a single word, on every session. That makes it uniquely worth optimizing: unlike a one-off prompt, its cost repeats forever. This guide covers exactly what to keep, what to cut, and how to keep the file lean without losing the context that actually helps.
Most prompts you write are paid once. CLAUDE.md is different. Claude Code reads it into context automatically at the start of every session, before your first message, and then carries it forward through the conversation. That changes the economics completely: a wasteful line in a normal prompt costs you once, but a wasteful line in CLAUDE.md costs you on every session you ever open in that project.
Multiply that by a busy week — dozens of sessions across a team — and a bloated instructions file quietly becomes one of your largest, least-visible token line items. The fix is not to delete CLAUDE.md; a good one saves far more than it costs by preventing wrong turns. The fix is to make every line earn its recurring price. If you want to see how per-session context adds up across a real workflow, our breakdown of AI coding agent costs walks through where the tokens go. Below are the six rules that keep the file lean.
CLAUDE.md should hold the things that are true about your project for months, not the thing you happened to be debugging on Tuesday. Durable facts pay for their recurring cost because they steer the model correctly across many sessions: the build and test commands, the directory layout, hard architectural constraints, and conventions that are non-obvious from the code.
Transient notes are the opposite. "Currently investigating the flaky login test," "remember to revert the temporary logging in auth.ts," or "the staging DB is down this week" all become dead weight the moment the situation changes — but they keep loading and keep costing tokens until someone deletes them. Keep those in your task tracker or a scratch file, not in the file that loads every session.
A surprising amount of CLAUDE.md bloat is the model being told things it learned in pre-training. "Use meaningful variable names," "write tests for new features," "Python uses indentation for blocks," "prefer async/await over callbacks" — none of this changes the model's behavior, because it is already the default. You are paying tokens to tell an expert that water is wet.
The test for any line is simple: would the model do something different without this? If the instruction just restates a general best practice or a language basic, cut it. Reserve CLAUDE.md for the project-specific overrides — the places where your conventions differ from the obvious default, like "we use tabs, not spaces" or "never import from internal/ outside its package." Those are worth their recurring cost; generic advice is not.
The single fastest way to bloat CLAUDE.md is to paste in a large block of code, a full config file, or an entire schema. A 200-line config pasted into CLAUDE.md is thousands of tokens loaded on every session, whether or not the current task touches that config at all.
Instead, point to it. A line like "DB schema lives in db/schema.sql; migrations in db/migrations/" costs a dozen tokens and lets the model read the real file only when a task actually needs it. The model is already good at opening files on demand — that is what its tools are for. Your job in CLAUDE.md is to tell it where things are, not to inline their contents. If you want to measure how much a pasted block inflates the file, our token calculator shows the count before you commit it.
Prose is expensive per unit of information. A paragraph explaining "the reason we structure our services this way is that historically we found..." carries one useful fact wrapped in dozens of connective words that get re-sent every session. A bullet delivers the same instruction at a fraction of the cost.
Write CLAUDE.md as a dense list of directives, not an essay. "Run make test before committing." "API routes live in src/routes/." "Never edit generated files in gen/." Each is a single scannable line the model can act on. Cut narrative justification unless the why genuinely changes what the model does — most of the time it does not, and it is pure recurring overhead. This is the same discipline Terse applies to the prompts you type into Claude Code: strip the padding, keep the signal.
CLAUDE.md files rot upward. Everyone adds lines; almost nobody removes them. A note that was essential three months ago describes a subsystem you have since deleted, but it keeps loading on every session because no one thought to check. Left alone, the file only grows, and so does its recurring cost.
Make pruning a habit. Every few weeks, read the file top to bottom and ask of each line whether it still earns its place. Delete stale references, resolved reminders, and anything superseded by a change in the code. Treat it like the dependency list it effectively is: something you keep tight on purpose, not a log you append to forever. A ten-minute prune can shave a meaningful slice off every future session's token count.
In a large repo, a single root CLAUDE.md tends to accumulate rules for every corner of the codebase — the frontend build quirks, the backend service conventions, the infra scripts, the data pipeline. When you are only working in one of those areas, you are still paying to load instructions for all of them.
Claude Code supports nested CLAUDE.md files, so split by directory. Put frontend-specific conventions in frontend/CLAUDE.md, backend rules in services/CLAUDE.md, and keep only truly repo-wide facts at the root. Now a session working in the frontend loads the frontend context and skips the rest. This both trims tokens and sharpens relevance — the model sees the rules for the code it is actually touching. For more ways to keep Claude Code's working set small, see our guide to reducing the Claude Code context window.
Saving tokens is the obvious win, but there is a second reason to keep CLAUDE.md lean: accuracy. As the context fills with low-signal text, the model's ability to attend to what matters degrades — a phenomenon often called context rot. A CLAUDE.md padded with stale notes, generic advice, and pasted configs does not just cost more; it dilutes the instructions you actually care about, making the model more likely to overlook the one constraint that mattered.
A lean file is therefore doing double duty. Every line you cut is tokens you stop re-paying and one less distraction competing for the model's attention. If you want the token side of this quantified against Claude Code's plans and rates, our Claude Code pricing guide lays out what per-session context actually costs. And if you would rather not audit the file by hand, Terse can generate concise CLAUDE.md rules from your recurring session patterns — a light-touch way to capture what's durable without the bloat.
Terse watches how you actually work in Claude Code and suggests concise, high-signal CLAUDE.md rules — on-device, no API calls. Capture what's durable, skip the padding, and stop re-paying for context you don't need.
Terse for Claude CodeYes. Claude Code loads your CLAUDE.md into context at the start of every session, before you type anything. That means every line — useful or not — is billed on each new session and carried through the conversation. A lean file pays off repeatedly; a bloated one is a recurring token tax.
Durable, project-specific facts the model cannot infer: build and test commands, key directory layout, coding conventions, and hard constraints. Keep it to concise bullets. Leave out transient notes, general language basics the model already knows, and large code or config blocks — reference those files instead of pasting them.
Prune it regularly. Every few weeks, delete stale notes, one-off reminders, and anything the model no longer needs told. Prefer references over pasted content, and split project-specific rules into per-directory CLAUDE.md files so only the relevant context loads for the area you are working in.
Yes. Beyond the token cost, a long CLAUDE.md worsens context rot — the more low-signal text the model carries, the harder it is for it to attend to what matters. A lean, high-signal file both saves tokens and keeps the model focused on the instructions that actually change its behavior.