How long should CLAUDE.md be?

Is there a CLAUDE.md size limit?

Only a soft one. The limits across tools, as their docs state them on 2026-09-23:

Sources: Claude Code memory docs, Codex AGENTS.md guide, Cursor rules.

How many tokens does CLAUDE.md use?

All of it, on every turn. CLAUDE.md is loaded at session start and delivered as a message right after the system prompt, so it is part of the prefix every later request sends. After /compact, the project root file is read from disk and injected again. Each subagent that loads project instructions pays for its own copy in its own context; the built-in Explore and Plan agents skip it.

Prompt caching makes the repeat cheaper in money. On Claude Opus 5.5, per the 2.1.280 changelog, cache reads are $0.20 per million tokens against $4 for fresh input. It does not make the repeat cheaper in attention. The lines are still in front of the model on a CSS change and on a database migration alike.

To see the real number, run /context in a session. It breaks the window down by category and lists which CLAUDE.md and memory files loaded. Note that @path imports do not shrink anything: imported files load at launch with the file that imports them.

Does a longer CLAUDE.md reduce adherence?

The vendor says yes. The one controlled study of file size could not find the effect. Both are worth reading closely.

Anthropic's context engineering post (Thariq Shihipar, 2026-07-24) reports removing over 80% of Claude Code's own system prompt for Claude 5 generation models with no measurable loss on their coding evaluations. The advice for your file follows: keep it lightweight, say briefly what the repo is for, and spend most of the tokens on gotchas.

Damon McMillan's factorial study (arXiv:2605.10039) ran 1,650 Claude Code sessions and varied file size, instruction position, file architecture and contradictions in adjacent files. None produced a detectable difference in compliance after correction, and for size the data affirmatively favoured no effect. The largest effect was inside the session: each additional function the agent wrote came with about 5.6% lower odds of compliance. That finding was not pre-specified, and the target was a single trivial annotation, not a real rule set.

Read together: a long file may not be ignored because it is long. It costs you because every line competes for a place in a session that is already drifting, and because most long files are long with material that never needed to be there.

What should I cut from CLAUDE.md?

Start with what the agent can derive by reading the repo. The ETH Zurich study found repository overviews, though popular, did not help agents find the relevant files any faster. Claude Code's own /doctor checkup (v2.1.206 and later) proposes trims on the same logic: it cuts directory layouts, dependency lists and architecture overviews, and keeps pitfalls, rationale and conventions that differ from tool defaults.

• Cut directory trees, dependency lists, framework descriptions, anything a linter or formatter already enforces.
• Move multi-step procedures to a skill, which loads on demand, and rules that only matter for one area to .claude/rules/ with a paths: field.
• Enforce anything that must happen every time (tests before commit, no writes to migrations/) with a hook. A hook runs regardless of what the model decides.
• Relocate personal preferences to CLAUDE.local.md or ~/.claude/CLAUDE.md.
• Keep the non-obvious build and test commands, the traps, and the decisions with their reasons. “Webhook handlers return 200 and enqueue; the payment provider retries on timeouts and we double-charged in March” is a line worth its tokens.

Where each mechanism belongs is its own note: CLAUDE.md vs skills vs hooks.

How long should AGENTS.md be?

The same answer, for the same reason. AGENTS.md is loaded the same way by every tool that reads it, and Claude Code puts it exactly where a CLAUDE.md would go. Codex adds a hard stop at 32 KiB combined by default, which is far beyond 200 lines of prose; you will hit the attention problem long before the byte limit.

The ETH study is the one that measured cost directly. Across its agents, adding a context file raised inference cost by roughly 20 percent, in part because agents followed the file's instructions and did more steps. A line that says “run the full test suite before any change” is obeyed, and billed, on every task, including the ones where it did not matter.

Why does my CLAUDE.md keep growing?

Because adding is the only move anyone makes. A mining study of 7,310 AI IDE rules from Cursor, Windsurf, Kiro and two others across 83 projects (arXiv:2606.12231) found rule changes are mostly expansions and enrichments, and surveyed developers said they edit rules mainly to correct AI errors, usually by adding a new negative rule rather than editing an old one. Nobody opens the file to delete a line, because nobody can tell which lines are still doing anything.

How do I know which lines are pulling their weight?

The file cannot tell you. That is the gap Harbor is built around, and the point is subtraction, not a smaller bill.

Start with what is always on. harbor context needs no account, no token and no network. It reads the machine's disk and prints the context loaded on every turn, per source: the skills index, agent definitions, MCP tools, injected context, and who put each there. It is the one command to run before signing up for anything.

npm install -g harborloop
harbor context

Past that, Harbor serves each agent only the team facts that apply to the task, and counts per rule how often it was served and how often an answer cited it. A cite is evidence, not proof; an uncited rule may still have shaped a turn. But a rule served three hundred times and never once cited is the line you now have a reason to question. That is served vs cited, and the CLI docs cover the commands.

Related: what the research says about instruction files and why Claude ignores CLAUDE.md.