Your CLAUDE.md is too long

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	Author target: root under 150 lines; scope local context and review obsolete rules. No universal size threshold

A product-focused meetup reached the same conclusion about AI configuration files months earlier. Those talks describe a configuration-maintenance problem. They do not establish a universal size ceiling for 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 project instructions loaded into the conversation are an obvious place to remove irrelevant material. 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). Dense general instructions can compete with the specific task and accumulate contradictions. That is a reason to inspect the configuration and test adherence, not evidence of a precise physical boundary at a particular line count.

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

A large CLAUDE.md consumes conversation context and can include instructions irrelevant to the current task. Part one separates the long-context findings from hypotheses about configuration. Emmanuel Sciara’s smart-zone / dump-zone language is a practical metaphor from a talk, not a measured partition of every model’s attention. Moving a task earlier or shortening a file does not guarantee that the model will follow it correctly.

Guillaume Laforge describes another failure in IFTTD episode 361: a capable model can answer from general training knowledge while ignoring the supplied context. An explicit grounding instruction and an output check are possible interventions. Neither that instruction nor trimming the file guarantees the failure disappears.

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 memory documentation recommends targeting fewer than 200 lines per CLAUDE.md file because longer files consume more context and may reduce adherence. That is guidance, not an enforced cap or a universal quality threshold. 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 makes the instruction set easier to review. 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 concrete steps for restructuring and verification. 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.

Some rules should leave CLAUDE.md rather than move deeper into the repository. “Lead with the result” is a response preference, not codebase context. Claude Code Output Styles put persistent response format in the system prompt, while skills carry workflows that load for a matching task. That separation leaves CLAUDE.md responsible for facts and conventions the project actually owns.

Trimming one Claude Code file solves a context-budget problem, not cross-host delivery. I separate those concerns in Portable agent configuration is a release system, not a shared folder, which maps canonical source, Claude Code and Codex projections, installation and runtime proof.

---

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

My working target is a root CLAUDE.md under 150 lines, containing 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
• A model can ignore supplied context; grounding instructions and a separate output check are interventions to test, not guaranteed cures
• 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