Contexts are not compliance. A year of agent configs points the same
direction: shorter instruction blocks get followed better — and the
ceiling arrives earlier than you think.
There's a failure mode spreading through agent configs, and it feels
productive. Every time an agent does something you don't like, you add
a rule. Six months later your CLAUDE.md is 600 lines, and — this is
the part nobody wants to hear — the agent is following less of it
than when it was 80.
The compliance curve
Instruction-following is not a bucket you fill. It's closer to a
signal-to-noise problem: every rule competes with your source code and
with every other rule for a finite attention budget. A short list of
concrete rules gets followed. A long list gets skimmed — and skimming
is not 50% compliance, it's unpredictable compliance, where the rules
that survive are not the ones you'd have picked.
The pattern I've seen in my own configs and others':
- Under ~100 lines: rules function as rules. Adding one more visibly changes behavior.
- 100–300 lines: the comfortable zone for a full baseline plus tool-specific guidance, if every line earns its place.
- 300–600 lines: redundancy sets in (the same idea phrased twice, then three times, added on different bad days). Compliance becomes selective. Review comments go up, not down.
- 600+: the file is a cargo cult. Nobody reads it — including, in every way that matters, the model.
Why more rules make each rule weaker
Three mechanisms, all boring:
Competition. Attention spent on rule 47 is not spent on rule 3.
When everything is emphasized, the model's choice of what to emphasize
is arbitrary — and your priorities lose to recency and position.
Redundancy is noise. People add duplicates on purpose ("I'll say
it in both files so it sticks"). The model doesn't experience
repetition as emphasis. It experiences two similar-but-not-identical
rules, which is exactly the input shape that degrades all
instruction-following.
Staleness compounds. Long files rotate slower. Rules for problems
you fixed months ago stay in context forever, contradicting the newer
rules that replaced the practice. Conflicts don't error; they resolve
randomly, per session.
The diet that works
1. Cut by checkability. For each rule ask: what observable diff
would violate this? If there's no answer, the rule is a mood, and
moods don't steer agents. "Write clean code" goes; "no unused imports"
stays.
2. Scope instead of delete. The testing rule that's wasting budget
on every request but only matters for test files doesn't need to die —
it needs a Cursor glob. Claude Code reads CLAUDE.md whole, but
Cursor's rules load per-glob, and most repos run more than one tool.
Put the rule where its scope is expressible.
3. Extract procedures. The TDD ritual, the investigation checklist,
the release dance — these aren't context rules, they're procedures.
Move them to skill files and import them where the work calls for
them. Your always-on budget stops paying for content that only matters
during specific tasks.
4. One home per rule. The baseline (AGENTS.md) holds standards
once; tool files reference or triage. The moment the same rule lives
in two places, you've started a drift clock.
5. Count it in CI. wc -l CLAUDE.md with a ceiling — we use 300 —
turns budget creep into a failed check instead of a slow surprise. The
ceiling isn't magic; the enforcement is.
What a dieted config looks like
Ours, after the same diet: an imported baseline (commands, conventions,
safety — ~70 lines), a verification loop, three to five stack notes,
and a short anti-pattern list. Under 100 lines in most repos. Rule
compliance is visibly better than the 600-line version it replaced —
same standards, fewer words, no contradictions to resolve.
The uncomfortable summary
Your CLAUDE.md's length is a ledger of unresolved decisions. Every
paragraph of prose is usually a rule you haven't made concrete; every
duplicate is a file you haven't unified. The diet isn't editing — it's
deciding.
If you'd rather start from a pre-dieted, pre-validated baseline: our
kits keep every CLAUDE.md under a validated 300-line ceiling, with
stack detail pushed into scoped rules instead of the always-on block,
for twelve stacks. The Next.js kit is free (MIT) on
AgentConfig Studio on Gumroad — all 12 kits.
Top comments (0)