·6 min read

The 200-line rule: why my agent instructions stay short

A long CLAUDE.md feels responsible and reads like diligence. In practice it buries the rules that matter under the ones that do not. Here is the structure I use instead.

context engineeringClaude CodeAI-native developmentdeveloper workflow

There is a specific kind of file that grows in every project that uses an AI coding agent. It starts as a short note about the stack. Then someone adds the deploy steps. Then a list of gotchas. Then the naming conventions, the folder map, the do-not-touch warnings, three paragraphs about a bug from last quarter. Six months later it is five hundred lines long, and everyone feels good about it, because surely an agent that reads all of this will make fewer mistakes.

It will make more. I learned this the slow way, and the fix turned out to be a rule I now apply without thinking: the entry point an agent reads on every turn stays under two hundred lines. Everything else lives one level deeper and gets pulled in only when a task actually needs it.

The reason is not aesthetic, it is measured

The intuition that a longer instruction file means better compliance is exactly backwards, and there is now data on it. A 2025 benchmark called IFScale tested how well models follow instructions as you stack more of them into a single request. The result is blunt: adherence falls as the count climbs, and even the strongest models drop toward 68 percent once you hand them hundreds of simultaneous instructions. Worse for our purposes, the failures are not random. Models systematically favor the instructions that came first and quietly drop the ones near the end.

Sit with what that means for a five-hundred-line instruction file. Your most recently added rule, the one you added precisely because it caught you out, is sitting at the bottom of the pile in the position the model is most likely to ignore. You did not make the agent more careful. You added your rule to the end of a queue and pushed the important ones toward a compliance cliff.

practical ceiling ≈ 150 to 200 ≈68% at 500 Number of simultaneous instructions Instructions followed
Every rule you pile on competes for a shrinking budget. Past a couple hundred, something you care about is being dropped.

The structure that actually works: three tiers

The fix is not to write less. It is to stop loading everything at once. Anthropic’s own Agent Skills are built on exactly this idea, which they call progressive disclosure, and it maps cleanly onto how I organize any agent instructions.

1 · Metadata name + one-line description, roughly 80 tokens always loaded 2 · Entry point under 200 lines: what exists, when to reach for it loaded when relevant 3 · Reference files the deep detail, split by topic loaded on demand
The agent always sees the map. It only pays for the territory it decides to walk into.

Tier one is metadata. A name and a one-line description, on the order of eighty tokens, always present. This is the agent’s table of contents. It is enough to decide whether a capability is relevant, and nothing more.

Tier two is the entry point. Under two hundred lines. It says what the project is, what the conventions are, where the patterns live, and which things are dangerous to touch. Critically, it points outward rather than embedding. It says “migrations follow the pattern in the reference,” not the full six hundred lines of migration lore.

Tier three is the reference material. The detailed guides, one topic per file, loaded only when a task reaches for them. This is where the deploy runbook and the payment-integration notes actually live. They are not gone. They are just not in the agent’s face on every unrelated turn.

What belongs in the entry point, and what does not

The discipline that keeps the entry point short is deciding what earns a place in it. My test is simple: does the agent need this on most tasks, or only on some? General-purpose context stays; task-specific detail moves down a tier.

So the entry point carries the project’s domain language, the shape of the architecture, the conventions that are not obvious from the code, the external systems it talks to, and the handful of genuine do-not-do-this rules. It does not carry style guidance a linter already enforces, tutorials for frameworks the model already knows, or a running history of past incidents. Those either belong in tooling that runs automatically or in a reference the agent can open when the topic comes up. A rule the model reads and ignores on every turn is worse than a rule in a file it opens exactly when it is relevant.

The habit compounds

Once you build this way, a second benefit shows up that has nothing to do with compliance and everything to do with cost. A short, stable entry point is cache-friendly. Coding agents cache the stable prefix of your context and reuse it at a fraction of the price, so a two-hundred-line file that rarely changes is both more likely to be followed and cheaper to send on every turn. A five-hundred-line file that you keep editing is the opposite on both counts: it invalidates the cache each time you touch it, and it dilutes the very rules you were trying to reinforce.

The whole thing comes down to a shift in how you think about an instruction file. It is not a contract where more clauses mean more protection. It is an attention budget, and every line you add spends some of it. Treat the entry point as a map, keep the map short, and let the agent open the detailed pages when the road actually goes there. Two hundred lines is not a limitation. It is roughly the point where a map stops being a map and starts being the territory it was supposed to summarize.

← Back to writing