CLAUDE.md audit
Your CLAUDE.md is the first thing a coding agent reads every session. A good one cuts re-exploration and over-explaining. A bad one quietly burns tokens on every turn. Here's how to tell which you have.
What a good CLAUDE.md does
It front-loads the things the agent would otherwise rediscover: how the project is structured, the exact build/test/lint commands, naming and style conventions, what's off-limits, and how to verify a change. It is specific, current, and short.
The common mistakes that cost tokens
- Too long. A 600-line CLAUDE.md is loaded every turn. Bloat here is the most expensive bloat in the repo.
- Stale. References to moved files or removed scripts send the agent on dead-end reads.
- Vague. "Write clean code" does nothing. "Run
pnpm test; components live insrc/ui" does a lot. - Missing commands. If the agent can't find how to build/test, it guesses — and guessing is expensive.
- No scope/guardrails. Without "don't touch generated files," the agent wanders into
dist/.
The 9-point audit checklist
- Project purpose and architecture in under ~10 lines
- Exact build, test, lint, and run commands
- Where the important code lives (key directories)
- Conventions: naming, formatting, patterns to follow
- What NOT to touch (generated, vendored, lockfiles)
- How to verify a change is correct
- An explicit terseness / output-style instruction
- Paired with a
.claudeignoreso the file tree itself is clean - Short enough that loading it every turn is cheap
Want this audited for your repo?
The free scanner flags whether your repo even has agent instructions and ignore rules. The 48-hour private audit reviews your actual CLAUDE.md, rewrites it, and ships a tuned CI gate plus a fix plan.
The method behind the audit is open source and benchmarked: context-os measured −40.9% total tokens on its own 36-call A/B (Sonnet). Your repo will differ.
Independent service. Not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic. · Reduce Claude Code token usage