Español

Make Your Rules File a Map, Not a Library

Your always-on rules file is making your agent dumber.

The instinct is to teach the agent everything up front: coding conventions, deploy steps, the schema, the style guide, every gotcha you've ever hit. So the rules file (a CLAUDE.md, a system prompt, a .cursorrules) grows and grows. But everything in that file is loaded on every turn, whether the task needs it or not. Past a certain size it stops helping and starts hurting.

Every line is a per-turn tax

An always-on rules file is prepended to the context on every request. That has two costs:

• Token cost — you pay for those tokens on every turn, and they crowd out room for the actual task and the code the agent needs to read.
• Signal cost — this is the one people miss. When the file is stuffed with detail that's irrelevant to the current task, the few rules that do matter get diluted. The model has to find the signal in your noise, and instructions buried in a wall of text get followed less reliably.

A 2,000-line rules file doesn't make the agent smarter. It makes the important 20 lines harder to see.

A map points; a library hoards

Reframe the file as a map of the codebase, not a library of everything about it. A map is short. It says where things are and how to find more, and it trusts the agent to go get the detail when a task actually calls for it.

# CLAUDE.md (the map)

## Durable rules (always true, keep these tight)
- Run `make test` before every commit; coverage gate is 98%.
- Never commit to `main`; branch first.
- API errors return the `Problem` shape in `src/errors.ts`.

## Load on demand (pointers, not contents)
- Deploy steps: see `docs/DEPLOY.md`
- Data model + migrations: see `docs/schema.md`
- Frontend style guide: see `docs/style.md`

The durable rules — the handful of things that are true on every task — stay in the always-on layer. Everything else becomes a pointer the agent follows only when the work touches it. Progressive-disclosure features (skills, referenced docs, tool-loaded files) exist precisely so detail can live off the hot path.

Split by "always vs. sometimes"

Sort every candidate rule into one of two buckets:

If a rule only matters when you're touching the payment code, it shouldn't tax every unrelated turn. Move it next to the payment code or into a doc the map references.

Power moves

• Budget the always-on layer. Give it a hard line cap. When it's full, adding a rule means moving one out to an on-demand doc, not growing the file.
• Put docs where the work is. A note about a module lives best in that module's directory, loaded when the agent reads that area, not globally.
• Prune on a schedule. Rules rot. A convention you dropped six months ago is still costing tokens and diluting signal until someone deletes it.
• Write pointers, not summaries. "See docs/schema.md" beats a half-accurate inline summary that drifts from the real schema.

Resources

• Anthropic — Manage Claude's memory (CLAUDE.md)
• Anthropic — Agent Skills and progressive disclosure
• Anthropic Engineering — Effective context engineering for AI agents
• "Lost in the Middle": how context length degrades retrieval (Liu et al.)