The 300-line instruction budget: what actually fits in your agent config

#ai #devtools #programming #claude

Ask five developers what belongs in a CLAUDE.md and you will get five files between 40 and 900 lines. The useful question is not "what can I put in" but "what does the model actually follow past line N". This article is the working answer we use: a hard ceiling around 300 lines of always-on instructions, and a budget for how to spend them.

Why a ceiling exists

Two mechanisms work against long instruction files:

Selective attention. Instruction-following degrades as instruction count grows, and it degrades non-uniformly. Rules near the top and bottom of the file get followed more reliably than rules in the middle. A model given 40 constraints will violate several under cognitive load (a big refactor, an ambiguous requirement); a model given 10 will usually hold all 10. The failure is quiet: nothing tells you the model ignored rule 34. You just find the console.log in your PR anyway.

Token spend per request. Always-on config is loaded into every single interaction. A 900-line CLAUDE.md is roughly 8-10k tokens. That is real context window, and in long sessions it crowds out the actual code under discussion. In agentic tools that run for dozens of turns, that cost multiplies.

The 300-line budget

The number is a working ceiling, not physics. It comes out at roughly 2,400 tokens for typical rule density, which leaves the bulk of a 200k-token window for code and conversation, and it is short enough that selective attention stays manageable. What matters more than the exact number: it must be a number. Without a ceiling, config grows to fill all available good intentions.

Budget	Lines	Content
Project identity	10-20	What the project is, runtime versions, package manager
Hard commands	15-25	Build, test, lint, dev server commands, exactly as runnable
Non-negotiables	10-15	The 5-10 rules that are genuinely always true (never commit secrets, never edit generated dirs)
Architecture map	30-50	Directory layout with one-line "what lives here" per area
Conventions	40-60	Naming, error handling, import style, test style
Workflow rules	20-30	When to run tests, how to handle migrations, PR expectations
Imports/pointers	10-20	`@docs/..` references to deep context loaded on demand
Slack	~50	Growth room before you are forced to cut

That totals 185-270 lines of core content plus slack. If you are over budget, you do not have a config problem, you have a scoping problem: rules that only apply to some files are sitting in a file that loads for all files.

What does not belong in always-on config

Most of what people write in CLAUDE.md is file-scoped by nature. Move it out:

You wrote	It actually is	Where it goes
"API routes must return ProblemDetails"	Applies to `src/api/**`	Glob-scoped rule
"Use testcontainers for integration tests"	Applies to test files	Glob-scoped rule
"Component props use `interface` not `type`"	Applies to `*.tsx`	Glob-scoped rule
"Explain the ADR process before schema changes"	Rarely needed	On-demand doc, referenced by pointer
"Always respond in Portuguese"	Meta-instruction	Top of file, 1 line (this one IS always-on)
Your full API style guide, 120 lines	Mostly dead weight	A doc; import the 10-line summary

A note on Cursor

Cursor rules give you an escape hatch the single-file formats lack: globs frontmatter scopes a rule to matching paths, so it only loads when relevant files are in play. That is how you keep the always-on file small without throwing away specific knowledge. See our teardown of the four config formats for where each format breaks, including the failure mode where a wrong glob means the rule never fires and nothing warns you.

Enforcement

A budget only works if something checks it:

#!/usr/bin/env bash
# fail CI if always-on config grows past budget
LINES=$(cat AGENTS.md CLAUDE.md | grep -cv '^\s*$')
if [ "$LINES" -gt 300 ]; then
  echo "Agent config is $LINES lines (budget: 300). Cut or scope rules."
  exit 1
fi

Three lines of bash. Teams that adopt a budget without a check grow past it within two months, usually during a deadline sprint when someone needs the agent to stop making the same mistake and slaps a rule at the bottom of the file. That is fine, occasionally. The check exists so it stays occasional.

DEV Community