Write rules that are concrete, durable, and worth their tokens

/init gave you a baseline, and you corrected it. Now you start adding the things the agent could never have discovered by reading the repo — the knowledge that currently lives only in your morning re-explanations. But there’s a discipline to this, because a CLAUDE.md isn’t a free notepad. Every line you add is loaded into every session, spending context tokens before you’ve typed a single word of your actual task. The file is a budget, and a rule has to earn its slot.

The economics of a rule

Here’s the framing that makes the whole decision easy. A rule is context you pay for once instead of re-establishing every session. That’s the entire trade.

The morning ritual — “test command is npm test, charges are in cents, we use Conventional Commits” — is you spending tokens and keystrokes to re-teach the agent the same three facts daily. Move them into CLAUDE.md and you pay for them once, in a few lines, and the tax is gone. That’s a brilliant trade, and it’s the whole reason the file exists.

But the trade only works when the entry is true, durable, and not otherwise available. Pad the file with vague or generic content and you’ve inverted it: now you’re paying context rent every session for lines that don’t change the agent’s behavior at all. A bloated CLAUDE.md is worse than a lean one, and not by a little — the canonical guidance is to keep each file under about 200 lines, because longer files both cost more and, counterintuitively, get followed less reliably as the signal drowns in noise.

What belongs

The rules that pull their weight share a shape: specific, verifiable, and particular to this project. Things the agent cannot infer and would otherwise get wrong:

The domain fact that bites. “Charges are stored in cents, never dollars — a $10 charge is 1000.” This is the single most valuable line in the payments service’s file. The agent has no way to know it, and getting it wrong means money bugs.
The exact command, not the gist. “Run npm test before committing” beats “test your changes.” A command the agent can run verbatim is worth more than an instruction it has to interpret.
The convention with teeth. “Commit messages use Conventional Commits (feat:, fix:, chore:).” Now it writes commits your way without being told each time.
The thing it must never touch. “The v1/ routes are frozen legacy — never modify them.” A guardrail the agent would otherwise trip over.

Notice the pattern: each is concrete enough that you could check whether the agent followed it. That testability is the tell of a good rule.

What doesn’t

The entries to keep out are the ones that feel responsible but change nothing:

Generic best-practice filler. “Write clean code.” “Follow best practices.” “Handle errors properly.” The agent already aims for these; the words just burn tokens.
Anything the code already states. The framework, the language, the directory names — Claude reads those. Don’t transcribe the repo into the file describing the repo.
One-off task notes. “We’re refactoring the charge handler this week.” That’s not durable; it’s true for a week, then it’s stale context misleading every session after. If it isn’t a standing fact about the project, it doesn’t belong in a rule.

The honest test for any candidate line: would I have to tell a new teammate this, and will it still be true in three months? Yes to both — it’s a rule. Vague, obvious, or temporary — leave it out. You’re curating, not dumping.

So far every rule you’ve written goes in one project file that your whole team shares. But not every rule wants the same audience — some are personal, some belong to one corner of the codebase. Rules layer across scopes, and knowing which scope a rule belongs in is the next move.