CLAUDE.md Best Practices: Stop Paying for Bloated Instructions

Your CLAUDE.md file is the single most expensive piece of text in your repository. Not because it is large — the median CLAUDE.md in our 100-file corpus is 1,285 tokens, and the median config overall is 964 — but because Claude Code reads it on every session start, for every developer, on every project. A 2,000-word CLAUDE.md costs roughly 2,700 input tokens per session (chars÷4 estimate). At Claude Opus 4.8 pricing ($5/M input), a team of ten running 15 sessions per day each burns 2,700 × 150 sessions × 22 workdays ≈ 8.9M tokens a month — about $45/month just reading that one file, before caching. Multiply by several repos and the number gets uncomfortable.

Here is how to write a CLAUDE.md that earns its tokens.

Common bloat patterns

Aspirational text. Paragraphs explaining your team's engineering philosophy, mission statements, or design principles the agent will never act on. If it does not change the agent's next tool call, delete it.

Stale references. Instructions pointing to files that were renamed, APIs that were deprecated, or conventions your team abandoned two sprints ago. These do not just waste tokens — they cause the agent to hallucinate about code that no longer exists.

Duplicated instructions. The same rule stated three different ways because different people added it at different times. Claude does not need persuading; it needs one clear directive.

Inlined documentation. Pasting entire API schemas, config examples, or style guides into CLAUDE.md instead of referencing them by path. The agent can read files on demand — do not force-feed it on startup.

The rules

Keep it under 500 words

This is roughly 650-700 tokens. That is your budget for project-level instructions that genuinely need to be present on every turn. If you cannot fit it in 500 words, you are including things the agent does not need on every session.

Use imperative voice

Not "We prefer to use TypeScript strict mode" — write "Use TypeScript strict mode." Imperative sentences are shorter and unambiguous. Every word you save is a token you save, multiplied by every session.

Split into skills files

Claude Code supports a skills system that loads instruction files on demand. Move specialized instructions — deployment procedures, migration guides, test patterns for a specific module — into separate files. Reference them from CLAUDE.md with a one-line pointer. The agent loads them only when relevant, instead of carrying the full weight on every session.

# Skills
- Deployment: see /docs/skills/deploy.md
- Database migrations: see /docs/skills/migrations.md

Reference docs by path, not content

Instead of pasting your ESLint config into CLAUDE.md, write:

Lint rules are in .eslintrc.js — read it before suggesting code changes.

The agent will read the file when it needs to. You save the tokens on every session where linting is not relevant.

Audit quarterly (at minimum)

Instructions drift. Set a calendar reminder to re-read your CLAUDE.md with fresh eyes. Ask: does every line here change agent behavior in a way that matters this month?

A concrete before/after

	Words	Tokens (~chars÷4)	Contents
Before	1,400	~1,900	Team philosophy, three paragraphs on Git conventions, inlined TypeScript compiler options, a deprecated API reference, the same "always write tests" instruction stated twice
After	380	~510	Imperative directives for language, test runner, lint command, branch naming, and a skills index — everything else moved to referenced files or deleted

That refactor saves ~1,390 tokens per session. For a team of ten at 15 sessions/day: 1,390 × 150 × 22 ≈ 4.6M tokens/month, or roughly $23/month at Opus 4.8 input rates ($5/M) on a single file — recovered in the first hour.

Measure it

TokenCheat includes a free CLAUDE.md auditor that tokenizes your file, flags common bloat patterns, and estimates the monthly cost based on your team size and session frequency. Run it before your next sprint planning and turn "we should clean up CLAUDE.md" into a ticket with a dollar figure attached.

Your instructions should be worth what they cost. Most are not — yet.