Skip to main content

Drop AGENTS.md and CLAUDE.md

Agent instructions are project documentation, and project documentation belongs in the README.

Every coding tool reads its own instruction file, and AGENTS.md turned seven of them into one. What goes in that file is setup commands and conventions, which is contributor documentation. An ETH Zurich study found context files don’t generally improve task success and raise inference cost by over 20%. Put the content in the README and symlink AGENTS.md to it.
AI agents
coding agents
documentation
developer tools
LLMs
Author

Michael Green

Published

November 15, 2026

Introduction

If you’re like me you probably dabbled around with AGENTS.md, CLAUDE.md, BRAIN.md etc. etc. and for a few months it made sense to me to have all these files around. Each harness get’s its own kind of introductory text. Well, nowadays I don’t think that makes sense. I quickly settled on only using AGENTS.md because most harnesses actually did read that file. Even Claude Code reads it if you don’t have a CLAUDE.md present. Now this could have been the end of it if I didn’t have another realization.

What if we don’t need AGENTS.md?

Before we answer that question, some history is prudent.

How every tool got its own file

Cursor read .cursorrules. GitHub Copilot read .github/copilot-instructions.md. Claude Code read CLAUDE.md, Gemini CLI read GEMINI.md, Windsurf read .windsurfrules, Cline read .clinerules, and Amp read AGENT.md (singular). If your team used three tools, you kept three copies of the same paragraph about how to run the tests.

The industry’s fix was AGENTS.md, a format that came out of OpenAI Codex, Amp, Jules from Google, Cursor and Factory. Since December 2025 it has been stewarded by the Agentic AI Foundation under the Linux Foundation, and the site says it’s used by over 60k open-source projects. Claude Code held out for a long time. Since version 2.1.277 it reads AGENTS.md too when a project has no CLAUDE.md.

So seven special files became one special file. It reminds me of xkcd 927.

Figure 1: Caption: How standards proliferate (see: A/C chargers, character encodings, instant messaging, etc.). Situation: there are 14 competing standards. One person says “14?! Ridiculous! We need to develop one universal standard that covers everyone’s use cases.” The other says “Yeah!” Soon: Situation: there are 15 competing standards. “Standards” by Randall Munroe, xkcd 927, CC BY-NC 2.5. Recoloured to match the site theme.

What’s in these files

The agents.md site shows an example file with two sections. “Setup commands” lists pnpm install, pnpm dev and pnpm test. “Code style” says TypeScript strict mode, single quotes, no semicolons, and functional patterns where possible.

Would a developer who joined your team this morning find that useful? Of course they would. How do I install this, how do I run the tests and what’s the house style are the day one questions of every new hire. In a small project that content is the “Development” section of the README. In a larger one it’s CONTRIBUTING.md, which GitHub has linked from its issue and pull request forms since 2012.

What does the format add on top? The FAQ on the site says there are no required fields. It’s plain Markdown with whatever headings you like. So the standard is a filename, plus a rule that the nearest file wins when a repo has several.

“README.md files are for humans”

That’s a quote from the agents.md site, and it’s the entire case for a separate file. AGENTS.md, it says, holds the build steps, tests and conventions that might clutter a README or that don’t matter to human contributors.

Well, I call bullshit. Which build steps don’t matter to human contributors? I can’t think of one. If a person can’t build the project from the README, then the README is broken and should be fixed.

We give these models write access to the repository. We let them open pull requests, and plenty of people let them merge. The whole pitch is that the thing works like a competent engineer. Then we turn around and say it needs its own onboarding document, because the one we wrote for engineers is “for humans”. If a model is good enough to change my code, it’s good enough to read my README. And if it can’t work out how to run the tests from the document a junior developer uses, I’d like to know that before it touches anything.

I see the same mistake whenever people describe agents as a new kind of colleague with a job title and a persona. A coding agent is a language model in a loop with some tools, and what it gets from AGENTS.md is text placed in its prompt. A README is written for anyone new to the repository who needs to get work done, and a language model reads Markdown just fine. Whether you think of it as a colleague or as a text predictor, the file it should get is the same.

Two descriptions of the same build process also drift apart. The README says npm test, AGENTS.md says pnpm test, and now the person and the model disagree about how the project works.

What could go wrong? :)

What the science says

Gloaguen and colleagues at ETH Zurich and LogicStar.ai tested these files in February 2026 (Gloaguen et al. 2026). They ran four setups (Claude Code with Sonnet 4.5, Codex with GPT-5.2 and with GPT-5.1 mini, Qwen Code with Qwen3-30B-coder) on real GitHub issues, with and without a context file. Their abstract says that providing context files “does not generally improve task success rates” while “increasing inference cost by over 20% on average”. With LLM-generated files the resolution rate dropped by 0.5% on SWE-bench Lite and by 2% on their own benchmark. Files committed by developers beat the generated ones by 7% on average.

The agents with no context file at all solved about as many issues as the ones that had one. The README, the docs and the code were enough for them to find out how the project builds and tests.

The authors recommend that a human-written context file only include instructions “not already present in the README”. Repository overviews, which are popular and recommended by the model providers, turned out to be no help. What did help was a description of non-standard coding practices, and in my book that’s the conventions section of a contributing guide.

The paper compares a context file against no context file, so it says nothing about conventions kept in the README.

What is specific to the tool

In the few cases where I use AGENTS.md it typically have rules about agent “behaviour” and have rules like “only commit when Mike asks” and specific stuff like that.

Then there’s real tool configuration, i.e., permissions, hooks and which commands may run without asking. That lives in the tool’s settings files the way editor settings live in ~/.config/somecooleditor/config.json.

The tools do load AGENTS.md into the context automatically on every session, and a README written for users can be long. That’s a property of the tool, which could load README.md just as easily. Codex caps project docs at 32 KiB by default and the Claude Code documentation says to target under 200 lines per instruction file. A README that exceeds those limits is too long for a person as well. The fix has always been to move the detail into CONTRIBUTING.md and docs/ and link to it.

What I do now

In my repos AGENTS.md is a symbolic link to the README.md.

# after moving anything worth keeping into README.md
git rm AGENTS.md CLAUDE.md
ln -s README.md AGENTS.md
git add AGENTS.md

Every tool that looks for AGENTS.md gets the README, and so does Claude Code from 2.1.277 as long as there’s no CLAUDE.md in the way. The symlink is a compatibility shim for tools that hard-code the filename. One caveat from the Claude Code documentation is that its edit tools refuse to write through a symlink, so the model has to edit README.md under its real name.

If you don’t want the symlink, most tools let you choose the file. A CLAUDE.md can import other files, and the example in Anthropic’s own documentation is this one.

See @README for project overview and @package.json for available npm commands for this project.

Codex takes fallback filenames in ~/.codex/config.toml.

project_doc_fallback_filenames = ["README.md"]

Aider (read: in .aider.conf.yml) and Gemini CLI (context.fileName in .gemini/settings.json) have the same kind of setting.

Conclusion

We already have a file whose job is to tell a newcomer how to work on the project. When the setup commands and the conventions go there, the next person on the team gets the documentation we’ve been writing for the models, and there’s one description of the build to keep correct.

I’ve done this in two repos and I haven’t measured anything. If the models start getting the build wrong in those two, I’ll write that up.

If the tools read README.md and CONTRIBUTING.md by default, I could delete the symlinks as well.

References

Gloaguen, Thibaud, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev, and Martin Vechev. 2026. “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” https://arxiv.org/abs/2602.11988.