How Big Should a .cursorrules / CLAUDE.md File Be?

There is no universal line count at which .cursorrules, CLAUDE.md or AGENTS.md stops working. Measure the instructions actually loaded for a representative task, then check whether relevant rules are found and followed. Line count can reveal growth, but it is a rough proxy for tokens, relevance and conflicting requirements.

A short file can be ambiguous. A longer file can contain necessary constraints. Removing a safety rule merely to reach a target length is not an improvement.

Measure two useful quantities

First, record the instruction tokens loaded for the task. Use the tool’s available context reporting or an appropriate tokenizer rather than a fixed tokens-per-line conversion. Include relevant inherited files and other loaded context where observable. State what the measurement cannot see.

Second, mark which instructions are relevant to the chosen task. Keep universally applicable constraints distinct from area-specific guidance. A low relevant fraction can suggest a scoping problem, but no validated universal 10 percent or 50 percent threshold is asserted here.

Task / tool and model version / date:
Instruction sources actually loaded:
Measured instruction tokens / method / visibility limits:
Applicable context limit / other loaded context:
Rules relevant to this task / all rules reviewed:
Conflicts or missing source pointers:
Observed compliance failures / evidence:

Repeat for a few representative task types before changing the root instructions. A rule irrelevant to a test edit may be essential to a deployment.

What lost-in-the-middle research establishes

Liu and colleagues’ 2023 study tested retrieval of relevant information in long contexts and found that position could affect performance on those tasks. It does not establish a 600-line failure cliff for project instruction files, nor that position never matters below 300 lines.

A small local test with no violations would establish only those observed runs under the recorded setup. To assess your workflow, fix the task set and scoring rule, vary instruction placement or scope deliberately, and record both successes and failures. Preserve model and tool versions. Do not generalise a tiny sample to all current models.

Use a routing file where it helps

Keep project-wide constraints available in the root file. Link detailed guidance to the area where it applies, then verify that the tool or operator actually reads those sources. A pointer is not evidence that the target was loaded.

# Project instructions - illustrative routing pattern

Read the applicable source before changing that area:
API behaviour: api/CONVENTIONS.md
Database migrations: db/RULES.md
Tests and fixtures: test/HARNESS.md
Build and release: build/NOTES.md

Always applicable:
- Respect the current permission boundary.
- Run the required checks before claiming completion.
- Report blockers and unverified outcomes explicitly.

This is an example structure, not a recommendation to create those files or replace an existing canonical queue. Follow the repository’s current loading and ownership rules. Some agent tools support scoped files automatically; others require explicit retrieval. Check the current tool documentation rather than assuming identical behaviour.

Retest the change against the failure

Compare the old and proposed instruction structure on the same representative tasks. Check whether the critical rule was available, whether the agent followed it and whether the final verification caught a deliberate violation. Keep the task outcome separate from instruction compliance.

A useful routing refactor reduces irrelevant reading without hiding required constraints. It can also fail by moving a needed rule to a file that never loads. No success uplift or safety-compliance percentage is claimed here without a dated source set and method.

Keep a source-linked record of why a rule exists and when it can expire. Remove duplication only after checking that the authoritative rule remains discoverable. For safety-critical actions, use an appropriate enforced permission or gate as well as prose instructions.

Start with a written brief containing the recurring task, loaded sources and an observed missed rule. Documentation checked 15 October 2026: Claude Code memory and project instructions. The routing pattern above is proposed guidance, not a newly performed agent experiment.