Why it exists
Every coding agent started out with its own file name: Claude Code read
CLAUDE.md, Gemini CLI read GEMINI.md, Copilot read
.github/copilot-instructions.md, Cursor read its own rules folder. A project
used by several tools needed several copies of the same advice.
AGENTS.md is the shared name. It came out of OpenAI Codex, Amp, Google's Jules, Cursor and Factory working together, and is now looked after by the Agentic AI Foundation under the Linux Foundation. The AGENTS.md site lists the tools that read it.
What to put in it
Write down what you would otherwise explain again in every chat.
- Commands: install, build, test, lint, and how to run one test.
- Rules: code style, naming, the folder where each kind of file lives.
- Checks: what must pass before a change counts as done.
- Warnings: the mistakes an agent made before, and what to do instead.
- Boundaries: files or folders the agent should not touch.
Be concrete. "Run pnpm test before finishing" works better than "make sure
it works", because the agent can check it did what you asked.
Keep it short
Every line is read at the start of every task, so a long file costs time and crowds out the actual request. Claude Code's documentation suggests staying under about 200 lines per file. Codex reads at most 32 KiB of instruction files by default and stops adding files after that.
Leave out what the agent can find by reading the code, like a list of every folder. Keep what it cannot guess.
AGENTS.md, CLAUDE.md and GEMINI.md
| Tool | Reads |
|---|---|
| OpenAI Codex | AGENTS.md, or AGENTS.override.md if present |
| Claude Code | CLAUDE.md; AGENTS.md when there is no CLAUDE.md |
| GitHub Copilot | AGENTS.md, CLAUDE.md, GEMINI.md and its own files |
| Gemini CLI | GEMINI.md; other names when set in its settings |
| Cursor | AGENTS.md and its own rules |
Claude Code reads AGENTS.md on its own from version 2.1.277. If a project
has both files, it reads only CLAUDE.md unless you change its Project
instructions setting. Gemini CLI reads AGENTS.md once you add it to
context.fileName in its settings.
Use one file for every tool
Write the instructions once in AGENTS.md. For Claude Code, if you also need a
CLAUDE.md, make its first line an import of the shared file and add any
Claude specific notes under it:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.A symbolic link from CLAUDE.md to AGENTS.md also works, but Claude Code's
documentation advises the import for any project someone opens on Windows,
where a link can arrive as a one line text file.
One file per folder
A large project can have more than one. Agents read the AGENTS.md nearest to
the file they are changing, so a packages/api/AGENTS.md can hold rules that
only apply there. Codex joins the files from the top of the project down, so
the nearest one is read last and wins.
Common problems
- The agent ignores the file. Check the name and place. Claude Code skips AGENTS.md when a CLAUDE.md is present, and Gemini CLI needs it added to its settings.
- The agent follows some rules and not others. Two rules disagree, or a rule is too vague to check. Make each one something you could verify.
- The file keeps growing. Move rules that apply to one folder into an AGENTS.md in that folder.
Questions
What is the AGENTS.md file?
A Markdown file at the top of a code project that gives AI coding agents instructions: commands, code style and the checks to run.
What is the difference between AGENTS.md and CLAUDE.md?
They do the same job. AGENTS.md is the shared name many tools read. CLAUDE.md is the name Claude Code reads first; it also reads AGENTS.md when there is no CLAUDE.md.
Does AGENTS.md need a special format?
No. It is plain Markdown, with any headings you like.
Should AGENTS.md be committed to the repository?
Yes. It is meant to be shared, so everyone and every agent working on the project reads the same rules.