How long should CLAUDE.md / AGENTS.md be?

Every always-on instruction file costs tokens on every turn, and past a point it starts costing...

title: "How long should CLAUDE.md / AGENTS.md be?" published: true tags: ai, claude, cursor, productivity canonical_url: https://clogmeter.vercel.app/guides/how-long-should-agents-md-be

Every always-on instruction file costs tokens on every turn, and past a point it starts costing adherence too. Here is what Claude Code, Cursor and Codex actually document about size, plus a checklist for trimming.

Originally published on clogmeter.vercel.app.

Short answer: aim for a lean always-on file — roughly under 200 lines per CLAUDE.md (Anthropic’s documented target) and treat Cursor project rules as under 500 lines each, split by concern. There is no universal “perfect” line count. The real limit is whether the model still follows the rules that matter once system prompt, tools, skills and the task compete for the same attention budget.

No invented benchmarks here. The numbers below come from vendor docs and published guidance as of late 2026.

What the tools themselves say

Community write-ups often talk about a practical “~150 instruction” attention budget for frontier models before adherence drops — that is research/context, not a hard file limit. Your instruction file shares that budget with the agent’s system prompt and tool descriptions, so leave headroom.

Why bloated files get ignored

• Everything always-on costs every turn. Root CLAUDE.md / AGENTS.md is re-read at session start; fat files tax every message and every general-purpose subagent.
• Markdown is advisory. Claude Code docs treat memory files as context, not enforced config. A “never” in prose can still be skipped; hooks and permissions enforce must-holds.
• Conflicts cancel each other. Duplicate or contradictory always/never rules across files make the model pick arbitrarily.
• Long sessions compress early rules. Mid-thread, package-manager or style rules often shrink first while code stays — which feels like “Cursor/Claude is ignoring my rules.”

A practical size checklist

1. Measure first. In Claude Code, run /context (and /doctor for trim proposals). For any stack, paste the files into Clogmeter to see token weight vs common windows and spot duplicates/conflicts.
2. Keep always-on content tiny. Project identity, hard constraints, build/test commands, and pointers. Delete anything the agent can discover by reading the repo.
3. Move procedures to skills. Release checklists and long how-tos should load on demand, not on every prompt.
4. Scope directory rules. Nested AGENTS.md / path-scoped Cursor or .claude/rules files beat one giant root file.
5. Enforce never-rules outside markdown. If ignoring it once would hurt, use a hook, linter or CI check.
6. One source of truth. Prefer a canonical AGENTS.md with thin CLAUDE.md / Cursor adapters instead of divergent copies.

How long is “too long” in practice?

If the root file is hundreds of lines, mixes architecture essays with one-off workflows, or repeats the same rule in three places, it is already too long for reliable adherence — even if the model still “sees” the file. Vendors warn that longer instruction files reduce compliance before hard truncation kicks in (Codex’s 32 KiB cap being the blunt case).

A useful rule of thumb many teams use: if you would not ask a new teammate to memorise the whole file before their first PR, do not force the agent to either. Make the root file the map; put the territory in scoped docs and skills.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.