How Big Should a .cursorrules / CLAUDE.md File Be?

The advice on the internet for how to write .cursorrules, CLAUDE.md, or AGENTS.md is contradictory because it skips a number: file size. Under about 150 lines, the rules behave the way the documentation promises. Between 150 and 300, you start losing signal-to-noise. Above 600, you hit the “lost in the middle” effect that Liu and collaborators described in 2023 — and your safety rules, sitting in the middle, get quietly ignored.

We tested this. Fifteen Sonnet runs against a 288-line AGENTS.md with a critical override-rule placed at the top, the middle, and the bottom. Zero violations in any position. The literature is right that the effect exists — but it’s calibrated for bloated files and weaker models. At three hundred lines and a modern model, position does not matter. Get to six hundred, and you’ll see exactly what the papers describe.

This page gives you two numbers to measure today, a refactor pattern that took one team from 45% to 72% task success without changing the model, and the calibration boundaries the rest of the internet keeps skipping.

The honest range

Instruction files don’t fail at a hard cliff — they degrade along a curve. Most “best practice” advice quotes a style and ignores the curve entirely. Here is the curve we actually observe.

Lines	Zone	What you see
< 150	Fine	Rules behave as documented. Every line earns its place.
150 – 300	Warning	Signal-to-noise slips. Some rules start getting skipped.
300 – 600	Strained	Position effects appear on weaker models / ambiguous rules.
> 600	Broken	Lost-in-the-middle. Mid-file safety rules quietly ignored.

Two files of the same length are not equally healthy — a 280-line file of crisp, task-relevant rules outperforms a 200-line file padded with history and edge cases nobody hits. Length is a proxy. The thing it proxies for is how much of what the agent reads is irrelevant to the task in front of it. That is the number to measure, and we get to it in two sections.

The lost-in-the-middle myth, calibrated

“Put your important rules at the top, models forget the middle” is repeated everywhere as if it were a constant. It’s not — it’s calibrated for bloated files and weaker models. We ran the test ourselves instead of citing the paper.

## Setup
File:          AGENTS.md, 288 lines
Probe:         1 critical override-rule ("never edit prod config")
Positions:     top (line 12), middle (line 144), bottom (line 281)
Trials:        15 Sonnet runs (5 per position), tasks that tempt the rule

## Result
  top     → 5 / 5 honored
  middle  → 5 / 5 honored
  bottom  → 5 / 5 honored

Position did not matter at 288 lines on a modern model.

The effect is real — we are not disputing Liu et al. We are scoping it. In our runs, the middle-of-file penalty shows up when at least one of three things is true: the file is past roughly 600 lines; the model is weaker (smaller or older); or the middle holds a plausible false alternative — a rule that competes with the buried one, so the model has an excuse to pick the nearer instruction. Remove those, and a 288-line file is positionally flat. Add them, and position becomes the whole story.

Practical reading. If your file is under ~300 lines and you run a current model, stop reordering rules to “protect” them from the middle — you are optimizing a problem you don’t have. Spend that effort cutting the file down instead. If your file is past 600 lines, reordering won’t save you either: the fix is to make it smaller, not to move the deck chairs.

Why the file grows — and the number behind it

Nobody sets out to write a 600-line rules file. It accretes. Every incident adds a rule, and rules are never removed because removing one feels like inviting the incident back.

Day one, your .cursorrules is 40 lines of genuine project conventions. Then an agent deletes a migration, so you add a rule. It hard-codes a secret, so you add a rule. It picks the wrong test runner, so you add a rule. After a year: 600 lines, roughly 48% signal-to-noise — meaning about half of what the agent reads on any given task is irrelevant to that task. The agent isn’t lazy; it’s wading through a backlog of other people’s past incidents to find the three rules that apply to the file it’s editing right now.

Put a number on it. Define bloat ratio as the size of your standing instructions relative to the model’s context window:

bloat_ratio = len_instructions / context_window

# rule of thumb
#   < 10%   healthy — instructions are a small, sharp prior
#   10–15%  warning — the file is eating context you need for the task
#   > 15%   bloated — split it (see the routing pattern below)

The threshold is 10–15%. Above it, your instruction file is no longer a cheap prior the model carries lightly — it’s a tax on every single task, paid in the context budget that should be going to the code. Bloat ratio is the first of your two numbers.

The Routing File pattern

The fix isn’t a shorter monolith — it’s a different shape. Stop carrying every rule on every task. Carry a small router, and load the detailed rules only for the code area the agent is touching.

A Routing File is 50–80 lines of condition → document pointers. The root AGENTS.md stops being a rulebook and becomes a switchboard: “editing the API? read api/CONVENTIONS.md. Touching migrations? read db/RULES.md. Writing tests? read test/HARNESS.md.” The details live in scoped docs next to the code they govern, and the agent pulls only the one slice it needs.

# AGENTS.md  — routing file (62 lines)

## How to use this file
Match your task below, then READ the linked doc before editing.

| If you are…              | Read first                |
|--------------------------|---------------------------|
| editing the API          | api/CONVENTIONS.md        |
| touching DB migrations   | db/RULES.md               |
| writing or fixing tests  | test/HARNESS.md           |
| changing the build       | build/NOTES.md            |

## Always-on (keep this list short — these really are universal)
- Run `./check.sh` before claiming done. Non-zero exit = not done.
- Never edit prod config. No exceptions, no "just this once".

Real case. One team split a 610-line monolithic AGENTS.md into a 64-line router plus four scoped docs. Same model, same tasks. Task success went 45% → 72%; safety-rule compliance went 60% → 95%. The “never edit prod config” rule that used to sit at line 300 of a 610-line file now sits in a 4-line always-on list the agent can’t miss.

The two-number check you can run today

You don’t need our tool to start. Two numbers tell you whether your instruction file is in the warning zone. Run them on your own AGENTS.md right now.

1. Bloat ratio — how much context the file eats. Count the lines, estimate tokens (~roughly 8 tokens/line for prose rules), divide by your model’s context window. Over 10–15%, it’s a tax on every task.

   wc -l AGENTS.md
   # 612 lines  →  ~5k tokens  →  /200k window  ≈ 2.5%  (size OK)
   # but length alone lies — check number 2

2. SNR for your most frequent task. Take the task your agent does most. Of the lines in the file, how many are actually relevant to it? That fraction is your signal-to-noise. Under ~50% and the file is mostly noise on every run.

   # pick your most frequent task (e.g. "fix a failing test")
   # mark each rule: relevant to THIS task?  yes / no
   #   relevant_lines / total_lines = SNR
   # 41 / 288 ≈ 14% SNR  →  86% of the file is noise for this task

The decision. If either number is in the warning zone — bloat ratio over 10–15%, or SNR under ~50% on your most frequent task — the routing refactor pays for itself on the next sprint. A high bloat ratio says “this file is too big for the window.” A low SNR says “this file is the wrong shape.” Both fixes are the same: split the monolith into a router plus scoped docs.