# 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.

- Author: Jonas Rohde (@edhor)
- Published: 2026-03-31
- Canonical: https://edhor.me/blog/how-to-claude-md/
- Tags: claude-code, claude-md, agents-md, context-window, ai-agents

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](https://arxiv.org/abs/2602.11988)
- [Hacker News discussion](https://news.ycombinator.com/item?id=47034087)
- [Related paper: arXiv 2602.12670](https://arxiv.org/pdf/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 `/init`-style files slightly
_reduced_ success (~−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.

## 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](https://github.com/anthropics/claude-code/blob/main/plugins/frontend-design/skills/frontend-design/SKILL.md)
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](/blog/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.