Your CLAUDE.md Is Too Long and Claude Is Quietly Ignoring Half of It

Your CLAUDE.md file has grown for six months: a line added after every code review comment, every correction you typed twice, every question a new hire asked. It's past 300 lines now, and somewhere in the back half, Claude Code has quietly stopped applying half of what you wrote. Not because it can't read the file, it reads every line, every session. Reading a rule and reliably acting on it are two different things once you've stacked up enough rules in one place.

This post gives you the point where that stacking starts to matter, a five-minute test for whether one of your rules is still landing, and a clean split between what belongs in CLAUDE.md and what only looks like it does. It will not tell you to write terser sentences. You already know that, and it isn't the fix.

What actually happens when CLAUDE.md gets long

Claude Code loads CLAUDE.md whole, at the start of every session, from every directory between your working folder and the filesystem root, plus your personal file at ~/.claude/CLAUDE.md. All of it is concatenated into a single block and handed to Claude as a plain user message right after the system prompt, not folded into the system prompt itself, according to Anthropic's own documentation. Nothing about that delivery enforces compliance. Claude reads the instructions and tries to follow them, but there's no guarantee of strict adherence, especially when instructions are vague or contradict each other.

Position inside that block matters too. A 2023 study, "Lost in the Middle: How Language Models Use Long Contexts", found that model performance on long inputs is highest when relevant information sits at the very start or end, and drops significantly for anything buried in between, even in models built for long context. A CLAUDE.md file doesn't escape that shape just because you wrote it yourself. The rule you added first is the one most likely to still get read closely. Everything from month three is sitting in the middle.

The instruction budget: how many rules actually land

Anthropic's guidance is blunt: keep each file under 200 lines, because longer files "consume more context and reduce adherence." That's vendor advice, worth checking against research that isn't trying to sell you anything.

The closest match is IFScale, a 2025 benchmark measuring how instruction-following degrades as instruction density rises. Researchers gave 20 frontier models, including Claude 3.7 Sonnet and Claude 3.5 Haiku, a report-writing task carrying up to 500 simultaneous keyword instructions, then counted how many showed up. Even the best model hit only 68% accuracy at the maximum density. Three failure shapes emerged: "threshold decay" models like Gemini 2.5 Pro and OpenAI's o3 hold near-perfect accuracy and fall off past roughly 150 instructions; "linear decay" models like Claude 3.7 Sonnet degrade steadily across the range; "exponential decay" models like Claude 3.5 Haiku lose accuracy fast at low densities and flatten at a low floor.

That study measured keyword instructions in one prompt, not a CLAUDE.md file, so treat the number as a shape, not a spec. But it matches the 200-line ceiling above, from a different angle: GitHub's own guidance for auto-generating Copilot's equivalent file also caps the output at two pages. A useful working rule: count every distinct always-or-never line across every CLAUDE.md that loads for your session, and treat 150 as the point where you stop adding and start cutting.

A five-minute test for whether a rule is still landing

You don't need instrumentation to find out which rules survived the trip. Pick one near the bottom of your CLAUDE.md with a concrete, checkable effect: a banned dependency, an unusual date format, a naming convention no other project uses. Start a fresh session and give Claude a task that would trip the rule if it weren't reading it, then repeat with a rule near the top, as a control.

If the top rule lands and the bottom one doesn't, that's your answer, and it isn't a comprehension problem. Claude read the whole file; it weighted the back of it less. The fix isn't to repeat the rule louder. Move it higher, make it concrete enough to verify, or cut something else so it isn't competing with 150 others.

If Claude breaks the same rule again in a later session after you've confirmed it was reading it correctly, that's a different failure with a different fix, covered in why agents repeat the same mistake across sessions.

What belongs in CLAUDE.md

Four kinds of content earn a permanent seat in the budget, true and useful in every session:

• Commands you'd otherwise retype. Build, test, lint, and deploy commands specific to this repo.
• Conventions that differ from the tool's defaults. Indentation, naming, import order: anything Claude would guess wrong without being told.
• Architecture facts the code doesn't announce. Which service owns which database, why a layer is split the way it is: context a new engineer needs on day one that isn't obvious from the file tree.
• Hard always/never rules with no exceptions. The things you'd otherwise type into chat every single session.

The format Anthropic recommends for all four is concrete enough to check against a diff, not a general instruction to be careful:

Use 2-space indentation.
Run `npm test` before every commit.
API handlers live in `src/api/handlers/`.

What doesn't belong in CLAUDE.md

Four more kinds look like they belong and don't:

• Anything that has to happen 100% of the time. A written rule is a strong suggestion, not a guarantee. If a violation is unacceptable, a secret leaking into a commit, a migration running against production, it belongs in a hook: a shell command Claude Code runs at a fixed lifecycle point regardless of what the model would have chosen.
• Procedures used occasionally, not every session. A 40-line release runbook you touch twice a quarter doesn't need to sit in context the other 89 days. Anthropic's guidance is to move it to a skill Claude loads on demand.
• Rules that only apply to part of the codebase. A lint convention that only matters inside src/api/ shouldn't cost every src/frontend/ session part of its 150-instruction budget. It should be scoped, covered below.
• Decisions, gotchas, and the reasoning behind them. The biggest one, and worth its own section.

Instructions are not knowledge, and CLAUDE.md only holds one of them

An instruction is a rule that governs behavior: always do X, never do Y. Knowledge is a fact about the project that's just true, independent of any task: the staging database seeds wrong unless you run the reset script first, why the checkout flow skips the shared component library, which vendor's webhook is flaky on Mondays. CLAUDE.md is built for the first kind, short by design and read whole every session, competing for the same 150-instruction budget from above. Cramming knowledge in either blows past that budget or sits unread while the instructions you need get crowded toward the middle.

Teams that notice this usually reach for a running NOTES.md or TODO.md instead. That fixes the budget problem but not the survival problem: a plain file like that doesn't reliably carry information from one Claude Code session into the next unless something is actively re-reading and rewriting it.

Trail takes a different approach to that gap: project reference memory that lives outside any file Claude has to read start to finish, written by whichever session hits the gotcha first, and opened automatically by the next session through Trail's MCP connector (the open standard AI applications use to connect to external tools and data) before the same mistake gets made twice.

Worked example: cutting a 312-line CLAUDE.md down to 84

Here's what the split above looks like against a fairly typical file, accumulated the normal way over a year:

1. An 18-line deploy runbook, touched a handful of times a year, becomes a skill Claude loads on request instead of every session.
2. Roughly 40 lines of "why we did X" (the ORM the team moved away from, why the auth service is separate, a vendor integration's quirks) move to a project memory system that stores them once and surfaces them to future sessions.
3. 25 lines of React-specific lint conventions become a path-scoped rule under src/**/*.tsx, so they stop costing anything on backend-only sessions.
4. 30 lines describing the directory layout get cut outright. Claude can read a file tree itself.
5. Six overlapping formatting rules, added by different people at different times and half-contradicting each other, collapse into two.

What's left: build and test commands, six always/never rules, naming conventions Claude can't infer, and one line pointing at where the rest of the project's knowledge lives. Eighty-four lines, comfortably inside budget.

Rules that only apply sometimes

Claude Code's answer for instructions that don't belong in every session is a .claude/rules/ directory: files that work like CLAUDE.md, except each can carry a paths field naming the glob patterns it applies to.

---
paths:
  - "src/api/**/*.ts"
---

A rule scoped this way only enters context when Claude opens a matching file, not at every session start, according to Anthropic's documentation. Here's how the four mechanisms compare:

Splitting a bloated CLAUDE.md into @path imports organizes the file but doesn't touch the budget above; imported files still load in full at launch, the same documentation notes. Path-scoped rules are the only one of the four that actually removes content from a session's context instead of moving it to a file that loads anyway.

What to do the next time your agent breaks a rule that's written down

Start with the test from earlier. Three outcomes, three fixes.

If the rule sits near the top of a short file and still gets ignored, it's a specificity problem, not a budget problem. Rewrite it concrete enough to verify from a diff.

If your CLAUDE.md is past 200 lines and the broken rule was buried past line 150, run the split above tonight instead of adding a 313th line and hoping repetition helps. It won't. The file is already past where independent benchmarks show frontier models start missing instructions.

If what actually broke wasn't a rule at all but a piece of institutional memory, a gotcha, a decision, a reason something is built the way it is, that was never a CLAUDE.md problem. Put it somewhere built to survive outside the instruction budget instead.

If you're running Claude Code alongside Codex or Gemini CLI on the same repo and maintaining separate instruction files for each, see how CLAUDE.md, AGENTS.md, and GEMINI.md actually differ. And if the knowledge half of this problem is what's costing you time, a comparison of the trackers built for agent workflows covers where the field has landed on it.