Keep Your Rules File Lean

Your AI agent re-reads one file on every single message. Not once per session — once per request. If your CLAUDE.md is 800 lines of history, half-finished style guides, and instructions nobody's touched since March, you're paying the token cost for all of it, every time, whether the current task needs it or not.

The file is a system prompt, not documentation

It's easy to treat a rules file like a wiki page — a place to dump anything that might someday be useful. That's the wrong mental model. Documentation is something a reader chooses to open. A rules file is prepended to every prompt whether it's relevant or not. It behaves like a system prompt, and system prompts have a cost curve: every line is tokens spent before the model has read a single word of the actual task.

That cost compounds two ways. First, literally — more tokens per request, on every request, for the life of the project. Second, it dilutes signal. A model given 200 focused lines of "how this codebase actually works" follows them more reliably than one given 800 lines where the ten that matter for this task are buried between a changelog and a paragraph about a deprecated build step. Bloat doesn't just cost money, it costs obedience.

What belongs in, what belongs out

A useful heuristic: keep only what changes how the agent behaves on most tasks. Push everything else into files it can open on demand.

Keep in the rules file:

• Conventions — naming, folder structure, patterns you actually enforce
• Commands — how to build, test, lint, deploy
• Gotchas — the non-obvious thing that bites every new contributor (this service needs two env vars set before tests pass, this directory is generated and must never be hand-edited)

Link out instead of inlining:

• Full API references or schema dumps
• Long historical context ("why we migrated off X in 2024")
• Style guides longer than a checklist
• Anything task-specific rather than project-wide

The pattern is a short root file that states the essentials and then points to detail files — docs/testing.md, docs/deploy.md, docs/decisions/ — that the agent opens only when the task actually touches that area. You get the depth when it's needed and none of the tax when it isn't.

Before and after

A bloated file mixes everything into one flat wall of text: setup instructions, a full REST API reference, three paragraphs on why a library was swapped out, formatting rules, and the actual commands to run tests — all with equal weight, all loaded every time.

A lean file instead reads like a table of contents with just enough detail to act:

## Commands
- Test: npm test (coverage gate 98%)
- Build: npm run build

## Conventions
- One component per file, PascalCase
- API errors always return {error, code} — see docs/api-errors.md

## Gotchas
- .env.local is required for tests; see docs/setup.md
- Generated files live in /gen — never edit by hand

Same information ecosystem, radically different token bill. The lean version tells the agent exactly what changes its behavior right now and defers the rest to files it can pull in only when the task needs them.

A rough budget: ~200 lines

There's no hard limit enforced by any tool, but ~200 lines is a workable ceiling for the root file. Past that point you're almost always documenting something task-specific that belongs in a linked file instead of the always-loaded one. If your file has grown past that, the fix isn't to trim adjectives — it's to find the sections that only matter for one kind of task and move them out.

Power tricks

• Update it as you go. The rules file isn't a one-time setup artifact — when the agent learns something new about the codebase mid-session (a gotcha it just hit, a convention it just confirmed), tell it to save that fact back to the file. That keeps the file current without a separate maintenance pass, and keeps the next session — or the next teammate — from re-deriving the same lesson.
• Audit for token bloat periodically. Read through the file and ask, for each section, whether it changed the agent's output in the last month. Sections that didn't are candidates to move out or delete. The goal isn't a short file for its own sake — it's a file where every line is still pulling weight.

The takeaway

Your rules file isn't a library you're building for posterity. It's a boarding pass — it should tell the agent exactly what it needs to board correctly, and nothing else. New session, new teammate, same context, no re-explaining — as long as what's in the file earns its place on every single request.