Your CLAUDE.md Is Too Long
Two Dev With AI talks, Allainmat and Gallet & Dahan, converge on the same warning about CLAUDE.md bloat: past a size threshold, more rules make outputs 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 |
The same warning surfaces outside developer circles too: a product-focused meetup independently reached the identical conclusion about AI configuration files months earlier, suggesting the size ceiling isn’t a quirk of how developers use Claude Code specifically, it’s a property of how these models handle dense instruction sets in general.
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.
The default advice is wrong past a certain size
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.
This is not a hypothetical. 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, not one: 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 bloated file did not sink velocity on its own. It removed the one 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.
There’s a second mechanism worth naming, distinct 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). That’s not the model failing to weigh instructions correctly, that’s the model choosing not to use them. 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 is not just wasteful on tokens; it forces the model to weigh constraints that have nothing to do with what 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.
The obvious objection
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 don’t 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. Not a full explanation, just enough 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: something to add with intention and remove aggressively when no longer needed. The developers at Dev With AI who had the smoothest AI workflows were not the ones with the most elaborate CLAUDE.md files. They had the most recently pruned ones.