Your CLAUDE.md is too long

TL;DR

Most CLAUDE.md files are too long, and the reason is not a magic line count: rules accumulate without anyone rereading them, until some contradict each other. My working target is a root file under 150 lines, with local context scoped to directories, procedures in skills and response preferences in an Output Style.

What	Details
Problem	Accumulated instructions can add irrelevant context and conflicting rules; test adherence rather than infer it from line count
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

The two Dev With AI talks cited below describe a configuration-maintenance problem in AI configuration files. They do not establish a universal size ceiling for Claude Code.

A configuration can grow one justified addition at a time until its rules become difficult to review together. File length makes that maintenance problem visible. It does not establish why an agent failed on a particular task.

---

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: “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.

Evaluating AGENTS.md provides a direct comparison across Python repository tasks. Generated files often increased cost without improving resolution; human-written files had mixed benefits across agents. These results evaluate particular files and tasks, not a universal length limit or a rule that every generated file is harmful.

---

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.

Evaluate a smaller candidate against the current file on representative tasks, including cases that exercise the rule you intend to remove. Hold the model and task inputs fixed, retain failures, and inspect both compliance and resource use. Fewer lines establishes a smaller file; an improvement needs observed outcomes.

Marmelab’s harness survey also recommends retiring obsolete components. Record each rule’s original incident, owner and review condition so that pruning remains a reasoned change. Low everyday usage does not make a rare security constraint obsolete.

---

For a removal decision, use the guide’s paired evaluation protocol: compare the current file, a targeted version and an absent-file baseline on reserved tasks with the same relevant initial state. Include rare mandatory rules. A shorter prompt or an unchanged average alone does not establish that a rule is unnecessary.

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
• My root-file template keeps project description, non-negotiable constraints, a conventions block and pointers to local rules. Test the placement and usefulness of each instruction on the tasks it governs

Footnotes

1. Original French: “la guerre du token quand on utilise Claude Code, c’est une guerre du quotidien”. Source: Bonjour Claude, dessine-moi un projet (Dev With AI, April 2026). ↩