Do AGENTS.md & CLAUDE.md Actually Work? What the Research Says (Keep Them Short, 2026)
Do files like AGENTS.md / CLAUDE.md actually help coding agents? A 2026 study answers: yes, but barely - and writing them long backfires. Across many agents and models, context files did not reliably improve task success, while inference cost rose by over 20%. The fix isn't to drop the file - it's to write it lean (test/build commands, must-not-break rules, key paths) and push the rest into files loaded on demand, progressive-disclosure style.
- The research figures and tool status (AGENTS.md as a cross-tool standard, import syntax) were cross-checked against sources at the time of writing; these tools change fast, so verify the live docs.
AGENTS.md and CLAUDE.md - are they the same?
They're essentially the same idea - a file the agent reads to learn the project's conventions - just with a different name per tool. CLAUDE.md is Claude Code's convention. AGENTS.md is the rising cross-tool standard: read by Codex CLI, Copilot CLI, Gemini CLI, Cursor, and Claude Code too.
Both do the same job: give the agent a persistent briefing that survives across chat sessions, so it doesn't re-ask your conventions every time. The one difference worth remembering: CLAUDE.md keeps a few Claude Code-specific capabilities that AGENTS.md doesn't standardize - most notably hierarchical loading and imports. To learn how to write a CLAUDE.md end-to-end with a template, see the CLAUDE.md guide.
One line to avoid confusing three look-alikes: AGENTS.md (the file standard) is different from AgentKit (the kit for Claude Code, agentkit.best) and from OpenAI AgentKit (Agent Builder/ChatKit).
What the research found - helpful, but barely
The "do context files actually help" question now has data. The study "Evaluating AGENTS.md" by Gloaguen et al. (submitted Feb 2026) measured context files across many agents, models, and repositories. The results are worth pausing on:
- No general improvement in task success - true for both LLM-generated and developer-committed files. That runs against the common recommendation.
- Inference cost rose by over 20% on average.
- Repository overviews - popular and recommended by model providers - were not helpful. By contrast, the instructions inside a context file were properly followed by agents.
One thing that gets overstated: it's not that "developer-written files are better." The study found neither type reliably improves success. But since instructions get followed while overviews don't, the practical conclusion is sharp: cut the overview padding, keep the actionable instructions. Smaller file, same success, lower cost.
The paradox - the agent follows too enthusiastically
The interesting part is that the agent doesn't ignore instructions - it follows them a little too enthusiastically. Mention tests, and it runs more tests. Mention tools, and it uses more tools. Mention repo-specific workflows, and it explores more.
The problem is that many of those instructions don't help solve the task faster - they just make the task heavier. Every line you add is another line the agent feels it "must" act on. That's why a bloated file both burns tokens and drags out the task without a better result.
So AGENTS.md isn't wrong - the way we write it is
The takeaway isn't "drop the context file." It's: don't turn AGENTS.md into a 2,000-word handbook for the agent to re-read every time it fixes a bug.
Keep the actionable parts:
- The test command, the build command, the run command.
- The rules it must not break (don't change the public API, don't touch directory X…).
- The important paths / directories.
Then let the agent figure out the rest. Put bluntly: if we bind agents too tightly to our own knowledge, they'll end up... dumb like us. Give them some room to fly, then steer them back toward the actual requirements afterward.
Write it "progressive-disclosure" style (like SKILL.md)
The style worth borrowing comes from SKILL.md itself: progressive disclosure - load on demand. Instead of stuffing everything into one file, split it into small files and lazy-load: "if doing A, read file X." When it's not needed, the agent skips it and spends no context on it.
In CLAUDE.md you do this with the @path/to/file import syntax (verify the live syntax, since tools change fast): the root file keeps only the always-true core, while details for each kind of work live in separate files pulled in when relevant. This is the same mechanism Claude Code skills use to load instructions by context; to build one, see how to create a custom skill. For overall context budget, see managing context & memory.
One file or two? (the symlink trick)
If you keep only one file, make it AGENTS.md, since it's read by the most tools. If Claude Code is your main agent but you still want every tool to work, a popular trick is a single source of truth: write AGENTS.md and symlink CLAUDE.md to it.
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.mdThis keeps the content in one place while serving all tools. The trade-off: you lose CLAUDE.md's hierarchical loading and imports - so if you rely heavily on @path imports, consider keeping CLAUDE.md as a real file instead of a symlink.
Before/after: from a long handbook to ~a dozen lines
Anyone who's used a Claude Code kit from the early days until now will notice: from one long CLAUDE.md, I've compressed it down to barely a dozen lines. Because this file should be project-specific - holding exactly the extra rules this project needs - not a generic catch-all that hoards everything.
The trimming rule: every line must answer "where does this change the agent's decision?" If it doesn't, it's overview padding - cut it, or push it to a lazy-loaded file. A lean CLAUDE.md template to copy lives in the CLAUDE.md guide.
Keep / cut checklist
| ✅ Keep | ❌ Cut (or lazy-load) |
|---|---|
| Test / build / run commands | Repository overview |
| Must-not-break rules | Long explanatory prose |
| Important paths / directories | Rarely-used workflows |
@path import to detail when needed | General knowledge the agent already has |
A kit with lean context built in (AgentKit)
If you'd rather not tune it yourself, kits like AgentKit (agentkit.best, ak CLI - different from OpenAI AgentKit) ship a lean CLAUDE.md convention plus a set of skills written progressive-disclosure style, so you skip hand-rolling a bloated handbook. For an overview, read the AgentKit review or see AgentKit (20% off via link).
Frequently asked questions (FAQ)
Are AGENTS.md and CLAUDE.md the same?
Same idea, different name per tool. CLAUDE.md is Claude Code's convention; AGENTS.md is the cross-tool standard read by many tools (Codex, Copilot CLI, Gemini CLI, Cursor, and Claude Code). CLAUDE.md still keeps a few extras like hierarchical loading and imports.
Does Claude Code read AGENTS.md?
As things stand, Claude Code can read AGENTS.md alongside CLAUDE.md - but this surface changes fast, so verify the live docs. If you rely on @path imports and hierarchical loading, CLAUDE.md is still the root file worth keeping.
Do context files actually help agents?
Per a 2026 study, they don't reliably improve task success (both LLM-generated and developer-written) and they raise cost by over 20%. Repository overviews specifically were unhelpful, while concrete instructions were followed. Lesson: keep actionable instructions, cut overviews.
How long should CLAUDE.md be?
As lean as possible - keep only the always-true core and push detail into lazy-loaded files via @path imports. Every line should change the agent's decision; if it doesn't, cut it.
What is "progressive disclosure" in CLAUDE.md?
It's splitting content into small files loaded on demand: "if doing A, read file X." When it's not relevant, the agent skips it and spends no context on it - the same way skills load instructions when the context matches.
What should you keep vs cut in AGENTS.md?
Keep: test/build/run commands, must-not-break rules, important paths, and imports to detail when needed. Cut: repository overviews, long prose, rarely-used workflows, and general knowledge the agent already has.
Conclusion
Context files work - when they're lean and written progressive-disclosure style. Writing them long is self-sabotage: 20%+ more cost with no better result. Cut the overviews, keep the actionable instructions, lazy-load the rest. See the CLAUDE.md guide for a template, and if you're also running autonomously, pair it with how to use /goal efficiently.