AGENTS.md is a text file in your repository with instructions for coding agents: how to install, how to run the tests and which conventions to follow. It is an open format read by many tools, such as Codex, Cursor and GitHub Copilot. The idea is to keep a single rules file, no matter which agent opens the project.
A question from the app. Pick an answer.
You use two agents and each reads a different rules file. How do you keep them in sync?
It works on day one. Then you change a rule in one file and forget the other.
You keep a single source: the second file imports or links to the first, so every change counts for both.
They take up room in every message and depend on you remembering. The file exists so you do not repeat them.
A README explains the project to a person; AGENTS.md explains it to a coding agent. It holds what the agent cannot guess: the command that runs the tests, the naming convention, the folder nobody should touch. There are no required fields: it is plain Markdown, with whatever headings you like.
In a repo with several parts, each folder can have its own, and the agent uses the one closest to the file it is working on. Whatever the file says goes into the model's prompt and takes room in its context window every session, so keep it short. As of October 2026, the format is stewarded by the Agentic AI Foundation, part of the Linux Foundation.
As of October 2026, Codex, Cursor, GitHub Copilot, Gemini CLI and many others read AGENTS.md. Claude Code started out reading its own CLAUDE.md, and recent versions read AGENTS.md too, with one condition: by default, only if the project has no CLAUDE.md. If both are there, it reads CLAUDE.md and leaves AGENTS.md out, unless you change that option in its settings.
The other way around is similar: Codex does not read CLAUDE.md unless you set it up. So if your team uses several tools, having both files is not enough: you have to decide which one is in charge.
The simplest setup: the rules live in AGENTS.md and CLAUDE.md just imports it with a single line: @AGENTS.md. Claude Code reads the imported file first and then whatever you add below, which is for Claude only rules. You change a rule in one place and it counts for every tool.
Another option is making CLAUDE.md a symbolic link to AGENTS.md. It works, but if someone on the team uses Windows the link can arrive as a one line file. And if a long instruction is only for one task, like shipping a release, it usually fits better in a skill, which loads when needed.
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/."If I have both files, Claude reads both." Not by default: it reads CLAUDE.md. "I write 'also read AGENTS.md' in CLAUDE.md and that is that." Then the agent opens it only if it decides to; the @ import always loads it. "I copy the rules into both." It works until the day you change one and forget the other.