Español

Score Your CLAUDE.md Like a Linter

Your CLAUDE.md is taxing every single prompt.

An instructions file like CLAUDE.md, AGENTS.md, or a system prompt is not free documentation. It's prepended to context on every turn of every conversation. Every contradictory rule, every vague platitude, every duplicated instruction gets re-read by the model on each message you send. That means bloat isn't just untidy — it inflates token cost and, worse, degrades the model's ability to follow the rules that actually matter. Treat the file like code and run a linter over it.

Why the file taxes every turn

Context isn't persistent memory; the whole instructions file is re-sent with each request. So a 4,000-token CLAUDE.md costs you 4,000 tokens on turn one and turn fifty alike. Two failure modes make this worse than the raw token count suggests:

• Contradictions — "always write tests first" three sections above "move fast, skip tests for spikes" forces the model to guess which rule wins, and it guesses inconsistently.
• Platitudes — "write clean, maintainable code" consumes tokens and steers nothing, because it has no operational meaning the model can act on.

The model's attention is finite. Filler dilutes the signal of the rules you care about.

The mechanism: score it out of 100

Run a rubric over the file, manually or with a quick script, starting at a perfect 100 and deducting:

Start:                      100
- each contradiction pair:  -10   (two rules that can't both hold)
- each redundancy cluster:  -5    (same instruction stated N times)
- each platitude:           -3    (no operational, checkable meaning)
- oversized (> ~2k tokens):  -10   (whole file re-sent every turn)

You can even have the model audit its own instructions: paste the file and ask "find every pair of rules that contradict each other, every cluster that repeats the same instruction, and every line with no checkable meaning." Then cut what lost points. Keep rules that are specific, non-conflicting, and stated once.

Before and after

A lean rules file means cheaper prompts and sharper adherence on every turn.

Power moves

• Automate the audit in CI. A small script (or a scheduled model pass) can flag the file when it grows past a token budget or when two rules conflict, before the bloat compounds.
• Prefer checkable rules. "Run pytest before claiming done" beats "test carefully" because the model can verify it did the thing.
• Push detail into referenced files. Keep CLAUDE.md to the always-relevant rules and link out to per-area docs the model loads only when needed (progressive disclosure).
• Re-score after every edit. Instruction files rot the same way code does; a quarterly lint keeps the tax from creeping back.

Resources

• Anthropic docs — Manage Claude's memory (CLAUDE.md)
• Anthropic — Claude Code best practices
• Anthropic — Effective context engineering for AI agents
• AGENTS.md — a simple, open format for agent instructions