What is AGENTS.md, and which coding agents read it?
AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work in that codebase: how to build and test, what conventions to follow, what never to do. It is read by OpenAI Codex, Cursor, GitHub Copilot’s coding agent and code review, and Claude Code, and it has no required structure, which is both its strength and the reason it drifts.
Which agents read it
Section titled “Which agents read it”Each tool’s own documentation, as of October 2026:
| Agent | Reads AGENTS.md? |
Its own file | What happens when both exist |
|---|---|---|---|
| OpenAI Codex | Yes, it introduced the format | none | n/a |
| Cursor | Yes, in the root and in subdirectories | .cursor/rules/*.mdc |
Both apply; .mdc rules can be scoped to file globs, AGENTS.md cannot |
| GitHub Copilot (coding agent, code review) | Yes, the nearest file in the directory tree | .github/copilot-instructions.md, .github/instructions/*.instructions.md |
Both apply |
| Claude Code (2.1.277 and later) | Yes, when no CLAUDE.md exists in the working directory or above it |
CLAUDE.md |
CLAUDE.md wins, unless it imports AGENTS.md with a line @AGENTS.md, in which case both load |
| Gemini CLI, Windsurf, others | Varies by tool and version | GEMINI.md, .windsurfrules |
Check the tool’s documentation |
Two consequences follow. A team on Codex and Cursor can keep one file. A team that also uses Claude Code needs a CLAUDE.md that imports AGENTS.md, or Claude will read a different set of instructions from everyone else; see CLAUDE.md, Cursor rules and Copilot instructions: one source.
What belongs in it
Section titled “What belongs in it”The file is loaded into the agent’s context on every task, so every line costs attention. The things that earn their place:
- How to build, test and run: the commands, in fenced blocks, so the agent runs them rather than guessing.
- Conventions the agent cannot infer from the code: the HTTP client to use, where handlers live, which layer may import which.
- Rules with a reason: “never commit
.envfiles; commit.env.examplewith placeholders” is followed more reliably than “no secrets”. - What to do before finishing: run the tests, run the check, keep changes small.
What does not belong: architecture essays, history, anything the agent can read from the code itself, and anything you are not willing to keep current. Claude Code’s documentation recommends staying under about 200 lines; Codex caps the file at 32 KiB by default.
Why it drifts
Section titled “Why it drifts”AGENTS.md is hand-written, it is one of several files saying the same thing, and nothing checks it. Three months in, the Cursor rules say one thing, AGENTS.md says another, the wiki says a third, and the agents follow whichever they read. The fix is not a better template. It is one source that the files are generated from, and a check that runs on every change so a rule the agent ignored is caught before merge.
That is what Groundrule does with the file: npx @groundrule/cli sync writes a managed block into AGENTS.md from the standards in .groundrule/, and leaves everything you wrote by hand in place. The same standards produce CLAUDE.md, the Cursor rules and the Copilot instructions, so the four files cannot disagree. Agent instruction files shows exactly what is written and where.
Related
Section titled “Related”- CLAUDE.md, Cursor rules and Copilot instructions: one source
- Agent instruction files, what
groundrule syncwrites - How a coding agent is kept to the rules