CLAUDE.md Mistakes That Slow Claude Code Down

Most CLAUDE.md best practices tell you to keep the file short, structured, and free of contradictions. Two 2026 studies found none of that measurably changes how well Claude Code follows instructions — while the repository overview /init writes for you raises inference cost by over 20% and buys nothing back. This guide covers the four mistakes that do cost you, measured against the 135-line CLAUDE.md running this site and the two rules in it that went stale and had to be pulled.

Key takeaways

• Repository overviews — directory layouts, dependency lists, architecture summaries — raise inference cost with no measured gain in task success. Anthropic's own /doctor trim now removes them.
• A factorial study across 1,650 Claude Code sessions found no detectable adherence effect from file size, instruction position, file architecture, or contradictions between adjacent files.
• Adherence decays within a session, not across file length — roughly 5.6% lower odds of compliance per additional function generated.
• Coding agents follow context-file instructions well, which is precisely why a stale instruction is expensive: it gets followed too.
• A project-root CLAUDE.md is re-injected after /compact. Nested CLAUDE.md files in subdirectories are not.

What the evidence says about CLAUDE.md best practices

Two things are now measured rather than asserted: context files reliably cost tokens, and the structural rules everyone repeats do not reliably buy adherence.

The first result comes from Evaluating AGENTS.md, by researchers at ETH Zurich's SRI Lab and LogicStar, presented at the MemAgents workshop at ICLR 2026. They tested coding agents on SWE-bench tasks with generated context files, and separately on repositories carrying developer-committed ones. Their finding, in the paper's own words: providing context files "does not generally improve task success rates, while increasing inference cost by over 20% on average." That held across different LLMs, different agents, and both generated and hand-written files.

The why is the part worth keeping. Instructions in the context files, the paper reports, "are well followed by coding agents." What failed to earn its tokens was the repository overview.

The second result attacks structure head-on. A factorial study of four file-structure variables, published in May 2026, manipulated file size, instruction position, file architecture, and contradictions between adjacent files across 1,650 Claude Code CLI sessions on two TypeScript codebases. None of the four produced a detectable contrast after correction for multiple testing.

Neither paper says CLAUDE.md is useless. Both say its cost is real and its formatting is not the lever you have been told it is. If you have not written one yet, start with the file structure and load order — this guide is about what goes wrong afterwards.

Mistake 1: shipping a repository overview

Delete the part of your CLAUDE.md that describes the repository. It is the first thing /init writes, the largest thing in most committed files, and the one component the evidence specifically found unhelpful.

Anthropic's tooling has quietly converged on the same conclusion. The memory documentation describes the /doctor trim check as cutting "content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews," while keeping "pitfalls, rationale, and conventions that differ from tool defaults." That is the vendor's own trim heuristic matching the study's negative result.

The test for any line is whether Claude could recover it by reading the code:

One mechanic makes pruning cheaper than it looks. Block-level HTML comments in a CLAUDE.md are stripped before the content reaches Claude's context, so notes addressed to human maintainers cost nothing at runtime. You can explain why a rule exists to your team without paying tokens for it every session.

Mistake 2: treating length as the problem

"My CLAUDE.md is too long" is usually the wrong diagnosis. It is the easiest thing to measure, which is why it absorbs attention that belongs somewhere else.

The two authorities genuinely disagree here, and the honest reading is that both are partly right. Anthropic documents a target of under 200 lines and states plainly that longer files consume more context and reduce adherence. The factorial study looked for that adherence penalty and did not find it within the range it tested.

Reconcile it this way. The token cost of a long file is arithmetic and certain — every line loads every session. The adherence cost is asserted by the vendor and unconfirmed by the one study that measured it directly. So trim for cost, and do not expect trimming to fix a behavioural problem.

There is a second reason to keep the file short, and it has nothing to do with the model. A CLAUDE.md too long to re-read is a CLAUDE.md nobody audits — which is how you get the next mistake.

Mistake 3: leaving an instruction in place after the code moves

This is the one we got wrong, and the evidence is what makes it expensive. If instructions are followed well, then a wrong instruction is followed well too.

The CLAUDE.md in this repository carried two rules that had quietly stopped being true. Both were removed in commit 38d964a on 2026-07-24. Here is the actual diff:

 `undefined`. Write `width="1200"`, never `width={1200}`. This applies to every
 prop on every MDX component.

-The build error in `components/article/MdxContent.tsx` currently tells authors to
-write `width={…}`, which is the form that fails. Trust this file, not that
-message.
-
 **Images.** Markdown `![alt](src)` is deliberately mapped to a build-time error.

The component had been fixed weeks earlier. The rule survived it, and its instruction was to distrust a build error that had become correct — training every contributor, human and agent, to ignore an accurate message.

The second one failed differently:

 **Heading IDs strip dots.** `rehype-slug` turns `## What CLAUDE.md actually does`
-into `#what-claudemd-actually-does`, not `#what-claude-md-actually-does`. The
-example in `content-rules.md` §5.4 is wrong on this. Verify any `toc` href with
-github-slugger rather than hand-writing it — a mismatch fails silently.
+into `#what-claudemd-actually-does`, not `#what-claude-md-actually-does`. Never
+hand-write a `toc` href — a mismatch fails silently. Run `npm run check:anchors`,
+which reproduces the ID generation exactly and also catches a stray `#` H1 or a
+`####` heading.

That rule was not stale — it was documenting a bug instead of fixing it. It pointed at a wrong example in another file and asked the reader to route around it. The replacement names a command that makes the whole class of error impossible to ship.

Now the number that matters. That commit took the file from 138 lines to 135. The two failures cost three lines. No length target would have caught either one, no structural refactor would have surfaced them, and both were followed exactly as written for weeks. Accuracy is the variable the studies leave standing, and it is the only one that degrades silently.

Mistake 4: assuming nested files survive compaction

A project-root CLAUDE.md survives /compact — Claude re-reads it from disk and re-injects it. Nested CLAUDE.md files in subdirectories do not. They reload only the next time Claude reads a file in that directory.

That asymmetry is documented and easy to miss, and it punishes exactly the setup that monorepo guidance recommends. If your root file is a thin pointer and the real rules live in packages/api/CLAUDE.md, then a long session that compacts mid-task carries the pointer forward and drops the rules. Work continues, plausibly, against conventions that are no longer in context.

Two diagnostics are worth knowing before you start rewriting the file:

• /context lists what actually loaded under Memory files. If a file is not there, nothing else about its contents matters.
• The InstructionsLoaded hook logs which instruction files loaded, when, and why — the only way to see path-scoped and lazily loaded rules resolve in real time.

What actually degrades adherence

Session length, not file length. The factorial study's four manipulated variables all came back null, but the effect it did find is the useful one: each additional function the agent generates is associated with roughly 5.6% lower odds of compliance (OR = 0.944) within the session lengths tested. It reproduced on a second codebase and on a second model at matched configuration.

Two caveats keep that number honest. The relationship is non-monotonic rather than a flat per-step penalty, and it was identified during analysis rather than pre-specified — a strong signal, not a constant you should budget against.

The mechanism underneath is the one Chroma documented as context rot: across 18 frontier models, performance degrades as input length grows, well before any documented context limit. For Claude Code specifically, context rot means the thing eroding your instructions is the conversation that accumulated on top of them, not the file they arrived in.

Which reverses the usual advice. When adherence slips forty minutes into a session, the fix is to start a fresh one, not to reorder your CLAUDE.md. Agreeing an approach up front and then executing it in a clean context is the cheapest version of that — plan mode does both in one step when showClearContextOnPlanAccept is enabled.

Best practices

• Write the pitfall, not the map. Overviews are the measured dead weight; traps and rationale are what Claude cannot reconstruct from source.
• Re-read the file on a schedule. Staleness is the failure mode with no symptom — the rule keeps getting followed, which is the problem.
• Fix the source instead of documenting the bug. A rule that routes around a broken error message or a wrong doc is a rule that has to be maintained forever.
• Split the session before you split the file. Adherence decay tracks session length; imports cost the same context they replace.
• Escalate anything that must run. CLAUDE.md is advisory by design. A hook executes regardless of what Claude decides.

Conclusion

Audit your CLAUDE.md for accuracy first, cost second, and structure last — that is the order the evidence supports. Delete the repository overview today; it is the largest measured waste in most files. Then diff the file against your codebase on a schedule, because a stale rule is followed just as faithfully as a correct one and shows no symptom until someone traces a bad decision back to it. More on working with agents in AI Coding Assistants.

Frequently asked questions

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.