Five habits in your CLAUDE.md that are quietly burning tokens

CLAUDE.md is loaded into every Claude Code session, from the first prompt to the last. Whatever’s in it gets paid for, every time, by every engineer on your team. A 1,200-word file with three “examples” in it doesn’t feel expensive — until you multiply by sessions per day, engineers per team, and weeks per month.

Here are the five habits we see in roughly every CLAUDE.md audit. Each is mechanical, easy to fix, and worth real money once you find them.

1. Multi-paragraph examples for behavior you can describe in one sentence

The single most common cost driver. Engineer wants Claude to use a specific naming convention, so they paste a three-paragraph “for example, if the file is…” block to be safe. The model now carries that paragraph in context forever and reproduces it on demand. The instruction it actually needed was one line.

Before:

For naming React components, please use PascalCase. For example,
if you have a component that displays a user profile, you would
name the file UserProfile.tsx (not user-profile.tsx, userProfile.tsx,
or user_profile.tsx). Similarly, a component for a payment form
would be PaymentForm.tsx, and for an order summary it would be
OrderSummary.tsx. Make sure the file extension is .tsx and not .jsx.

After:

- React components: PascalCase, `.tsx` extension (e.g. `UserProfile.tsx`).

You saved ~80 tokens × every session. Across a 6-person team running 5 sessions each per day, that’s roughly 12,000 tokens of avoidable load per week.

The general rule: if you find yourself writing “for example” inside CLAUDE.md, that’s a smell. Replace the example with a tighter spec, or move the example to a code comment in the actual codebase where it belongs.

2. Stale rules that contradict newer rules without removing the old one

Files grow by addition. Six months in, the rule about “always use tabs” lives 40 lines above the rule about “spaces, never tabs,” and nobody knows which one was added last. The model picks one — usually the first one — and the team alternately corrects it and gives up.

Every contradiction is worse than no rule at all. The model spends tokens trying to reconcile two opposing instructions, then picks one with low confidence and produces output that’s both wrong half the time and lukewarm the rest.

The fix is editorial, not technical. Once a month, read your CLAUDE.md top to bottom out loud. Every time you hit a rule that contradicts an earlier one, delete the loser. Most teams’ files lose 30–40% of their length in the first review. Claude’s output improves visibly within a session.

3. Personal preferences inside a shared file

Engineer A likes terse responses. Engineer B finds terse responses unhelpful. Engineer A adds “always be concise, minimize prose, prefer code” to the project CLAUDE.md. Engineer B now gets terse responses they didn’t ask for, on a project they share with engineer A.

Personal style preferences belong in ~/.claude/CLAUDE.md (the per-user file), not in the project file checked into git. The project file is for things that are true about the codebase — its conventions, its constraints, its non-obvious gotchas — not about how any individual engineer likes to be talked to.

Quick test: would this rule apply to a new hire who joined yesterday? If yes, project file. If “only Alice prefers it this way,” personal file. Most teams have never done this audit on a single shared file; the result is a checked-in file full of one engineer’s personal preferences paid for by everyone.

4. Conventional-wisdom platitudes

Lines like “Write clean code.” “Follow best practices.” “Add appropriate error handling.” “Keep functions small.” These look helpful and feel responsible. They are zero-bit instructions to the model — it already does all of these by default — and they add tokens to every session without changing behavior.

Rule of thumb: every line in CLAUDE.md must be contrarian relative to a generic well-trained model. If the model would do this thing anyway, the line is dead weight. The instructions that earn their place are the ones a fresh model would not guess: your specific testing framework, your specific deployment quirk, the one function nobody is allowed to touch without paging the on-call.

A useful exercise: for every rule, ask “if I deleted this, what would Claude do differently in our codebase?” If the honest answer is “the same thing,” delete the rule.

5. Restating what’s in the framework’s docs

Closely related to #4 but more specific: spelling out language and framework basics. “Use async/await, not callbacks.” “Prefer functional components over class components.” “TypeScript’s strict mode is on; respect it.” The model already knows. You’re paying tokens to remind it of things in its training data.

What’s worth keeping: the places where your codebase deviates from the framework’s defaults, or where you’ve made a non-obvious choice. For example:

Useful (specific to your codebase):

- We use Zustand for global state, not Redux. There's a single `store/index.ts`;
  do not add another store file.
- HTTP errors from our API are handled by `lib/api/errors.ts`; do not
  swallow or rethrow them ad-hoc.

Wasted tokens (the model already knows this):

- Use React hooks for state.
- Avoid global mutable variables.
- Use TypeScript's type system; do not use `any`.

The first version earns its place because no fresh model could have guessed your specific choices. The second is paying to teach the model what it already knows.

Putting it together: the 100-line target

After a single pass, most teams’ CLAUDE.md files come down by 30–60% with no loss of guidance — usually more guidance, because the signal-to-noise has improved. A reasonable target for a typical codebase: under 100 lines, organized into 4–6 sections, every line earning its place.

If you want a second pair of eyes, that’s the CLAUDE.md audit we run on this site — 90 minutes, written diagnosis, one rewritten root file plus five reusable templates. $299 solo, $799 team of 2–10. The five habits above account for somewhere between half and three-quarters of every audit we’ve done so far.

What we did not cover (and probably should next)

A few patterns worth their own article: deeply nested CLAUDE.md files (root + sub-directory + per-package) and how they merge, the relationship between CLAUDE.md and the new memory tools that landed earlier this year, and how AGENTS.md differs in practice from CLAUDE.md — we wrote that one up here. If one of the others is what’s biting you right now, let me know.

Companion reading

• The CLAUDE.md problem in teams of 5+ — what happens to all of these mistakes at team scale.
• How to write a great CLAUDE.md — the file-craftsmanship companion piece.
• What AI coding agents write to your disk — the directory map, if you want to see what’s actually getting loaded.