CLAUDE.md, AGENTS.md, GEMINI.md: who reads what
Someone told you to create a CLAUDE.md file. Elsewhere they mention AGENTS.md, elsewhere again GEMINI.md. You have no idea whether you need all three, or which one your tool actually reads. You make one at random, and you are never quite sure it does anything at all.
Every publisher first created its own instruction-file name: CLAUDE.md, GEMINI.md and others. A common format, AGENTS.md, appeared afterwards and is now read by more than twenty tools. The file goes at the root of the project and is re-read at every startup.
Why several names exist
The story is simple, and it explains today’s confusion.
Every publisher of an AI coding tool hit the same problem at the same moment: an AI starts from zero at every session, so there has to be somewhere to put what must survive. Each solved it on their own, and each picked their own file name.
Hence the situation now: CLAUDE.md for Claude Code, GEMINI.md for Google’s tool, and other formats again at Cursor, GitHub Copilot or Windsurf, each with its own convention.
Anyone switching tools therefore found themselves copying the same instructions under another name. Which eventually produced a shared answer.
The common format: AGENTS.md
This is the part many people have not yet taken in, and it simplifies everything.
AGENTS.md presents itself as a simple, open format for guiding coding agents — their equivalent of the introduction file that has sat at the root of projects forever.
It is not one publisher’s convention. The standard emerged from a collective effort, and it is now managed by the Agentic AI Foundation, itself under the Linux Foundation. In other words, it belongs to nobody in particular.
On adoption, which is what counts: more than twenty tools read it, among them OpenAI’s Codex, Google’s Jules, VS Code, Cursor, GitHub Copilot, Zed, Devin and Aider, across more than sixty thousand open projects.
Claude Code reads it too, while keeping CLAUDE.md as its own richer native format.
Where to put the file
At the root of the project. That is, in the main folder, at the same level as your other files — not in a subfolder, not tidied away in a corner.
That is the only placement rule that matters, and it is also the number one cause of files that “do not work”: they exist, they are well written, they are simply in the wrong place.
One special case is worth knowing: if your project is split into several distinct parts, each can have its own file. Tools then read the nearest one to where they are working. Useful later; no need to worry about it at the start.
What happens at startup
The mechanism is the same everywhere, and it fits in one sentence: the file is read when the tool opens, before you type anything.
That is what sets it radically apart from an instruction given in conversation. A sentence typed while chatting lives for the length of that conversation and then disappears. A sentence written in this file is re-read at every new session, without you having to think about it.
It is also why an instruction repeated three times in one day is a signal rather than a fate: it is not in the right place.
Length, and why it works against you
The natural instinct on discovering this file is to pour everything you know into it. That is counterproductive, and the official documentation says so.
The recommendation is to keep it short. The reason is mechanical and has nothing to do with discipline: this file takes up room in the tool’s working space, the same limited space that holds your conversation. The longer it is, the more it weighs, and the less it is followed.
A brief, sharp file is better respected than an exhaustive wall of text. Counterintuitive, and what the publishers observe.
The only test that counts
It takes ten seconds and replaces every assumption.
Close everything. Reopen. Ask the tool what your project does.
If it answers correctly without you re-explaining anything, the file is read, it is in the right place, and it works. If the tool asks you again, look no further: the file is misplaced or not being loaded, and that is what to fix before anything else.
Run this test again at every change of folder, machine or tool. Until you have, you are assuming.
What to take away
One file is enough to start. Take the common format, it covers the most tools. Only add a specific name if the tool you actually use demands it.
Placement matters as much as content. At the root, or nothing happens.
Short beats exhaustive. Not a matter of style, a matter of available room.
The test decides. Close, reopen, ask. Everything else is belief.
> pick the project back up, carry on with the pricing page