How to CLAUDE.md
A recent study measured what CLAUDE.md and AGENTS.md files actually do: developer-written ones help a little, LLM-generated ones hurt results and raise cost. Keep yours tight.
CLAUDE.md (or AGENTS.md, by the way: just symlink them) is the context file coding agents load into every session, and it’s easy to overuse. A recently published study looked directly at this, so I want to share it here so we stay aligned with the latest evidence.
- Study: arXiv 2602.11988
- Hacker News discussion
- Related paper: arXiv 2602.12670
- There are also some videos about the topic
TL;DR
AGENTS.md / CLAUDE.md files seem easy to overuse. The study found that
developer-written files produced only a modest average improvement
(+4 percentage points), while LLM-generated −3 points) and increased cost by more than 20%, largely
because agents explored, tested, and reasoned more. Agents also tend to
follow these instructions quite literally./init-style files slightly
reduced success (
What that means in practice
From my personal experience, I can attest to that. Having a detailed AGENTS.md / CLAUDE.md and constantly working on and adjusting it was worse than having a super tight and focused one. The same goes for MCPs and skills.
There are useful ones, like the frontend-design skill from Anthropic itself, but they should be installed very selectively.
Agents are now so good at searching for context on their own (e.g. via Explore subagents) that an overly explicit context file that doesn’t match 100% of the time can mislead them and worsen results. On top of that, a big CLAUDE.md occupies context in every single session, see Be aware of the context window for why that matters.
Since most of us use Claude, we don’t benefit from Codex 5.4’s ability to strongly align with existing patterns in the codebase. So this is more of a model-skill gap than something we’ll need to handle ourselves in the very near future.