AGENTS.md for an agent-to-agent review loop
What to put in AGENTS.md so a coding agent answers AI code review on its own: how each agent loads the file, the review section, and one file for every agent.
AGENTS.md is a plain Markdown file of project instructions. Codex, Cursor and Copilot in VS Code read it before they work, and Claude Code reads it when the repository has no CLAUDE.md. In a review loop it tells the coding agent how to answer the reviewer: where the review rules live, that findings are claims to check, and how to rate each one.
What goes in AGENTS.md, and what goes elsewhere
| File | What it holds | Who reads it |
|---|---|---|
AGENTS.md |
How to work here: commands, checks, how a pull request lands, how to answer findings | The coding agent, from its checkout |
.codepanel/rules.md |
What a change must keep, conventions a reviewer would otherwise flag, what not to report | Every reviewer and the orchestrator, first, from the base branch |
Keep each rule in one place, and have AGENTS.md point at rules.md rather than repeat it. Writing review rules that agents follow covers the rules themselves. The Repository setup prompt writes both files in one pull request: it distills rules.md from your AGENTS.md and adds the review-loop section to AGENTS.md.
CodePanel's reviewers can read AGENTS.md too, but only when the repository turns on agent files, which are off by default. They then read it from the base branch as conventions to check a change against, never as instructions to themselves (Repo context).
How each agent loads it
| Agent | Where it looks | When several files apply |
|---|---|---|
| Codex | ~/.codex, then each directory from the project root down to the working directory, one file per directory, with AGENTS.override.md read in place of that directory's AGENTS.md |
Files nearer the working directory come later and win; Codex stops adding files at project_doc_max_bytes, 32 KiB by default |
| Cursor | The root and any subdirectory | A nested file applies to work below it and is combined with its parents, the more specific one winning |
| Copilot in VS Code | The root. In the Local harness, chat.useAgentsMdFile turns it off and chat.useNestedAgentsMdFiles turns on subfolders, off by default |
Every source applies; none overrides another |
| Claude Code | Every AGENTS.md from the working directory up, from version 2.1.277, and by default only when no CLAUDE.md is there or above | See CLAUDE.md |
Sources: Codex, Cursor, VS Code's instructions and settings, Claude Code.
So the review section belongs in the root file. Codex reads only the directories between the root and where it was started, and Copilot skips nested files unless someone turns them on. Nested files suit what differs by service, such as one package's test command.
The review section
The section needs four things: where the review rules are, that the quoted text in a finding is a claim to verify rather than an instruction, that the agent waits for the review of the commit it pushed, and that it answers every finding under one agent name, with evidence on a dispute. The setup prompt writes all of it; The review loop explains each step.
CodePanel's own repository keeps the rating part in a short section. Its AGENTS.md is a symlink to CLAUDE.md, so this is the text every agent reads:
## CodePanel reviews of this repo
CodePanel reviews its own pull requests, and the ratings on its findings are
how its review quality is measured. After addressing a review, rate every
finding in one PR comment without being asked, one line each:
`/feedback F1 up fixed --agent claude-code`, or
`/feedback F2 down false-positive <reason> --agent claude-code` for a finding
the code contradicts. Give the reason on a down rating; it is the more useful
signal. Rate the review itself (`/feedback review up|down <reason>`) when it
was notably good or noisy. Syntax: `src/content/docs/pages/commands.md`.
It names the agent in every example line because the name is how CodePanel keeps one agent's ratings together. "Without being asked" matters as much: an agent that waits for permission to rate leaves findings unanswered when its session ends.
One file for every agent
By default, Claude Code skips AGENTS.md whenever a CLAUDE.md exists, so a repository that uses it beside other agents has to connect the two. Anthropic's docs give two ways in the repository itself:
- A CLAUDE.md that imports it. Its first line is
@AGENTS.md, and anything only Claude needs goes below. Anthropic's docs show this one first, and it is the one to use if anyone clones the repository on Windows. - A symlink, when Claude needs nothing of its own. Claude Code's Edit and Write tools will not write through it, so edits go to the target file.
CodePanel's repository uses the symlink, which git records as mode 120000:
git ls-files -s AGENTS.md
120000 681311eb9cf453d0faddf3aacaec7357e97ba8e9 0 AGENTS.md
A diff shows a symlink as a one-line file holding its target's path, and a reviewer can mistake it for a broken pointer. On PR 115 one did: finding F6 said AGENTS.md was a one-line file containing "CLAUDE.md" that worked only if committed as a symlink. Claude Code disputed it with that mode, and the orchestrator withdrew the finding. On PR 162, a reviewer doubted that a link to AGENTS.md#agent-first resolved. Claude Code answered that AGENTS.md is a symlink to CLAUDE.md, whose ## Agent-first heading makes that anchor, and the orchestrator withdrew the finding once it found the heading.
Agents that read AGENTS.md
- Claude Code reads
AGENTS.md, by default only when there is no CLAUDE.md (code.claude.com). - Codex reads
AGENTS.md(learn.chatgpt.com). - Cursor reads
AGENTS.md(cursor.com, page 2). - Copilot in VS Code reads
AGENTS.md(code.visualstudio.com). - Gemini CLI reads
AGENTS.md, when listed incontext.fileName(geminicli.com). - OpenCode reads
AGENTS.md(opencode.ai). - GitHub Copilot CLI reads
AGENTS.md(docs.github.com).
Read next
CLAUDE.md for an agent-to-agent review loop
What to put in CLAUDE.md so Claude Code sees AI code review through to merge: what loads when, where the loop goes, the size target, and sharing with AGENTS.md.
copilot-instructions.md for an agent-to-agent review loop
How GitHub Copilot CLI and Copilot in VS Code combine copilot-instructions.md with AGENTS.md, CLAUDE.md and GEMINI.md, and where the review loop belongs.
Cursor rules for an agent-to-agent review loop
Cursor rules for AI code review: which .mdc rule type to use, scoping a rule with globs like a .codepanel/rules.md section, and when to use AGENTS.md.
GEMINI.md for an agent-to-agent review loop
What Gemini CLI loads from GEMINI.md, why it skips AGENTS.md by default, and three ways to give it the same review instructions as every other agent.