Your CLAUDE.md is too long
Your CLAUDE.md past 200 lines? Two independent Dev With AI talks (Allainmat, Gallet & Dahan) found the same pattern: more rules make Claude less precise, not more.
TL;DR
| What | Details |
|---|---|
| Problem | CLAUDE.md grows unbounded; adherence degrades with size (official guidance: under 200 lines per file) |
| Source | Allainmat + Gallet & Dahan (Dev With AI), two talks converging on the pattern independently |
| Mechanism | Dense config consumes effective context, rules accumulate contradictions |
| Fix | Root file under 150 lines, directory-scoped files for local context, prune rules that no longer solve their original problem |
A product-focused meetup reached the same conclusion about AI configuration files months earlier. The size ceiling appears to come from how models handle dense instruction sets, rather than a quirk of how developers use Claude Code.
You’ve iterated on your CLAUDE.md for months. Every misunderstanding from Claude got a new rule. Every context gap got a new paragraph. The file is now 800 lines. And the outputs are somehow less precise than when you had 50.
Where more context stops helping
The standard recommendation is simple: more context means better outputs. Give Claude your tech stack, your conventions, your constraints, your preferred patterns. That advice is true up to a point. Florian Allainmat spent part of his Dev With AI talk (Bonjour Claude, dessine-moi un projet, April 2026) on that limit: context quality degrades as a session grows, Claude itself warns you to compact, and the CLAUDE.md that gets read on every single turn is the first file to keep lean. His phrasing: “la guerre du token quand on utilise Claude Code, c’est une guerre du quotidien” (the token war with Claude Code is a daily fight). The mechanism behind that limit is attention weighting: the model struggles to weight a recent specific instruction against a dense block of general context, and at some file size the accumulated rules stop helping and start competing. The config file that felt thorough six months ago is now competing with your actual prompt for the model’s usable attention.
Samuel Gallet and Geslain Dahan found CLAUDE.md bloat as a contributing factor in their velocity decline post-mortem (“What Worked, What Didn’t, What We Learned”), presented at the same conference in March 2026. They had added rules progressively over several months. The file looked complete and thorough. The outputs had quietly gotten less predictable, and tracing the cause took time because the degradation was gradual rather than sudden. Their post-mortem names two compounding causes: handing off entire user stories to an agent with no guardrail, and a CLAUDE.md that had grown past the point of being reviewable. The bloat did not sink velocity by itself. It removed the guardrail that might have caught the first problem before it compounded.
Why it happens
When CLAUDE.md grows large, the model spends more of its effective context window processing the configuration file itself, leaving less capacity for the actual task (context is the hidden variable develops why that budget dominates output quality). That cost is invisible in normal use; you see the output quality drop without a clear signal about the cause. Emmanuel Sciara, at Dev With AI in February 2026, described this as the smart zone / dump zone split: the early part of the context window where attention is dense and reliable, versus the trailing portion where the model drifts and approximates. A config file that fills the early context pushes your actual task into the dump zone.
A second mechanism differs from attention dilution. Guillaume Laforge calls it the mansplaining effect: a model capable enough to have strong priors from training will sometimes ignore the context you handed it altogether, defaulting to what it already knows instead, and produce an answer that’s correct in general but irrelevant to the specific CLAUDE.md you wrote (IFTTD, episode 361). The model skips the provided context instead of merely weighing it poorly. The practical difference matters: attention dilution is a size problem you can fix by trimming the file. The mansplaining effect is a prompting problem: it needs an explicit instruction to stay within what’s provided rather than falling back on training knowledge, no matter how much room is left in the context window.
Rules also accumulate without pruning. A rule added in January to prevent a specific pattern may now subtly contradict a rule added in April that was solving a different problem. Neither rule is wrong in isolation. Together, they create a surface where the model’s behavior on ambiguous tasks becomes harder to predict, because the instruction set is too large to optimize against cleanly. The model is trying to satisfy constraints that were never designed to coexist.
Published research points the same direction. Liu et al.’s “Lost in the Middle” (TACL 2024) measured language models using long contexts unevenly, with recall degrading depending on where information sits, and no clean universal threshold. Anthropic’s own documentation is blunt about the config-file case: long CLAUDE.md files consume more context and may reduce adherence, and the official recommendation is to keep each file under 200 lines. A bloated config file wastes tokens and forces the model to weigh constraints unrelated to the task you just asked it to do.
What the Claude Code guide recommends
The Claude Code guide’s memory systems chapter documents a specific structural approach: keep the root CLAUDE.md concise and use nested, scoped files in subdirectories for context that only applies to parts of the codebase. The root file handles project identity, non-negotiable constraints, universal conventions, and pointers to where specific rules live. Directory-level files carry the local context that would otherwise inflate the root.
This matters because structure affects how the model weighs instructions. A short, high-signal root file is much easier to apply consistently than an 800-line document where every paragraph competes for attention. The context engineering guide on this site walks that restructuring level by level, with the adherence data behind the size threshold. The architecture also makes pruning easier: a rule about the payments/ module lives in payments/CLAUDE.md, not buried on line 340 of the root, so it’s visible when you’re working in that directory and ignorable when you’re not.
Why pruning is hard
Each rule was added because it solved a real problem. That’s true. The issue is that rules don’t expire automatically. The problem a rule was added to prevent may no longer exist: the library was upgraded, the team member who needed the guardrail left, the pattern it was guarding against was refactored away. The rule stays. Multiply that by 18 months of iteration and you have a file full of locally-reasonable constraints that are globally incoherent.
Pruning requires knowing why each rule was added, which most teams do not track. A useful practice is a brief comment at the end of each rule noting the problem it was solving and the date it was added. Keep it short, with enough detail to evaluate whether the original condition still holds. A rule with no recorded rationale is nearly impossible to prune safely, so it stays forever. This is the exact problem I built ctxharness to catch: it flags the rules in your CLAUDE.md that have drifted from the code they describe, so pruning stops depending on memory.
What a well-maintained file looks like
A root CLAUDE.md under 150 lines typically contains four things: a one-paragraph project description covering tech stack and primary use case, a short list of non-negotiable constraints (security rules, deployment targets, output language), a conventions block covering naming and commit format, and explicit pointers to directory-level files for specialized context. Everything else belongs closer to the code it governs.
Teams with high-performing configs tend to treat the file the way they treat dependencies: add with intention and remove aggressively when no longer needed. At Dev With AI, the developers with the smoothest AI workflows had the most recently pruned CLAUDE.md files.
YSNK
(You should now know)
- The Gallet and Dahan post-mortem names two compounding causes, not one: handing an entire user story to an agent with no guardrail, and a CLAUDE.md too bloated to review. The bloat didn’t sink velocity by itself, it removed the guardrail that would have caught the first problem
- The mansplaining effect is a different failure than attention dilution: a capable model sometimes ignores your context entirely and answers from training priors instead. Trimming the file doesn’t fix it, only an explicit instruction to stay within what’s provided does
- A rule added in January to stop one pattern can quietly contradict a rule added in April solving a different problem. Neither is wrong alone, together they make behavior on ambiguous tasks harder to predict
- Without a recorded reason, a rule is nearly impossible to prune safely, so it stays forever. A one-line comment, the problem it solved and the date, is what makes pruning possible later
- A well-maintained root file holds four things only: project description, non-negotiable constraints, a conventions block, and pointers to directory-level files. Everything else belongs closer to the code it governs