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.
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 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.
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 nottype " |
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 |
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.
A budget only works if something checks it:
#!/usr/bin/env bash
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.
We hold every kit in AgentConfig Studio under this 300-line ceiling by validation, not by policy: the harness fails a kit whose CLAUDE.md exceeds the budget, and file-scoped knowledge moves into glob-scoped rules instead. If you want config that arrives pre-budgeted for your stack, the AgentConfig Studio on Gumroad, all 12 kits lists what fits in each of the 12 kits.