Data: CLAUDE.md instructions lose effectiveness as context grows

[nicolalessi]

I've been tracking how CLAUDE.md instruction compliance changes as context size grows during Claude Code sessions.

On a ~800 file project, Claude Code averages 23 tool calls per prompt (Read/Grep/Glob), pulling ~180K tokens into context. At that volume, CLAUDE.md instructions start losing statistical weight. The model doesn't "decide" to ignore them, they just get diluted in a massive context window.

I measured this directly: instruction compliance dropped noticeably after ~40K tokens of codebase context was loaded alongside the CLAUDE.md.

Reducing what goes into the context window before the agent reads CLAUDE.md significantly improves compliance. On my tests, pre-filtering codebase context to only relevant files improved both instruction adherence and output quality.

Has anyone using this memory bank system noticed similar degradation on larger projects? Curious if the memory bank approach partially addresses this or if it's orthogonal.

Data: vexp.dev/benchmark

[m13v]

ran into this exact dilution problem running 5 parallel Claude agents on a monorepo. our CLAUDE.md was ~350 lines and by the time the agent loaded 40+ files, compliance on the rules near the bottom dropped to maybe 60%.

the biggest win for us was splitting into a global ~/.claude/CLAUDE.md for identity/preferences and per-project CLAUDE.md for repo-specific rules. keeps each file shorter so nothing gets buried. we also front-load the most critical instructions (things that will break the build if ignored) at the very top of each file.

the other thing that helped was being ruthless about what goes in CLAUDE.md vs what stays as code comments or lint rules. if eslint or the compiler can enforce it, don't burn CLAUDE.md tokens on it. save that context budget for the behavioral stuff the model actually needs reminding about.

curious what your 180K token sessions look like in terms of tool call distribution - are most of those Read calls? we found that pre-scoping with Glob patterns before reading cut our context bloat roughly in half.

[m13v]

fwiw here is how we structure the tmux-based parallel agent setup that motivated our CLAUDE.md splitting approach: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md - each agent gets its own session with scoped context so the CLAUDE.md stays relevant throughout the run.