Three AI code reviewers, one file. That shift happened faster than most teams noticed.
AGENTS.md was formalized in August 2025 as a shared config format co-promoted by OpenAI, Google, Sourcegraph, Cursor, Factory, and others. By September 2026, Claude Code v2.1.277 shipped native AGENTS.md support — if no CLAUDE.md is present, Claude Code falls back to AGENTS.md. GitHub Copilot CLI reads it. Cursor reads it. The spec at agents.md is now the closest thing to a universal standard for AI coding agents.
If one file configures three review tools, the question becomes: what should actually be in it for code review?
Why "review" belongs in AGENTS.md, not in a separate .review.md
The temptation is to split. One file for "how the agent writes code" (AGENTS.md), another for "how the agent reviews code." Resist it. Two files drift: the reviewer ends up approving patterns the writer config told the agent never to produce, and nobody notices until a bug ships.
The agent that writes the code is the agent that reviews the next PR. CodeRabbit reviews what Codex just generated. Claude Code reviews what Copilot just committed. The same set of conventions needs to be enforced on both sides of the slash. Splitting them into two files means they drift, and when they drift, your reviewer approves what your writer is told to avoid.
So AGENTS.md needs a Review Policy block alongside the code-writing block. Four sections are enough.
Section 1: Review Policy — the Conventional Comments labels
The first section defines the comment vocabulary. Without it, every reviewer invents their own.
## Code Quality
### Review Policy
Code review uses Conventional Comments labels:
- `issue:` must-fix (Approve blocked until resolved)
- `suggestion:` improvement (optional, reviewee's call)
- `nitpick:` small polish (optional, address if time)
- `question:` ask, not an attack
- `praise:` call out good code (don't skip this)
Why five labels and not three: the gradient between issue and nitpick is where review threads get stuck. If every comment is either "block this merge" or "do whatever you want," your senior reviewers end up relitigating style on every PR. The middle three labels (suggestion, nitpick, question) absorb the arguments that are not worth blocking a merge over.
What each tool does with this: CodeRabbit will parrot the label scheme if you reference it from .coderabbit.yaml. Copilot CLI will adopt the vocabulary if the review prompt references AGENTS.md. Claude Code picks it up automatically once AGENTS.md is in the repo root.
Section 2: Approval Criteria — the four conditions
The second section says what "ship it" means.
### Approval Criteria
Approve when all four hold. Don't chase perfection:
1. Functional requirements are satisfied
2. Tests exist (happy path + failure modes)
3. No type errors
4. Design aligns with the team's direction
The reason to write this down is that AI reviewers over-flag. CodeRabbit will raise a style issue on a two-line fix. Codex will ask for more test coverage on a hotfix. Without an Approval Criteria section, the reviewer has no stopping condition. Every PR gets more comments until someone manually overrides them.
Four conditions are enough. The fourth one (team direction) is deliberately subjective. That is what Section 3 is for.
Section 3: Code Direction — the patterns with reference paths
This is the section that makes AGENTS.md load-bearing instead of decorative.
### Code Direction
**Patterns to increase:**
- Repository Pattern for data access
→ See `src/repositories/user-repository.ts`
- Result-type error handling
→ See `src/types/result.ts`
- Pure functions for business logic (no side effects)
**Patterns to decrease:**
- Business logic in controller layer
- `any` type (use `unknown` instead)
- Direct DB queries (go through the ORM)
- Files over 1000 lines (split responsibilities)
The reference-path convention is the whole point. Abstract rules like "use Repository Pattern" don't survive contact with an AI agent. Ask three agents to "use Repository Pattern" with no reference path and you can get three different ideas of what a repository is. A path to an actual implementation (src/repositories/user-repository.ts) collapses the interpretation to one.
Compare:
| Rule style | What the agent does |
|---|---|
Use Repository Pattern |
Generates something it calls a repository. Could be anything. |
Use Repository Pattern → see src/repositories/user-repository.ts |
Reads the file. Copies the structure. |
Every bullet in Code Direction should have a → see <path> if a reference implementation exists. If no reference exists yet, the first time someone implements the pattern, their file becomes the reference. That is how the section ratchets up without you writing a style guide.
Section 4: PR Guidelines — the mechanical rules
The fourth section is the smallest and the most skipped.
### PR Guidelines
- Target 300 lines or fewer per PR
- Separate refactors from feature changes (different PRs)
- PR description: what changed, and why
The 300-line target is where review quality collapses in practice. Above it, the reviewer scans. Below it, the reviewer reads. The "refactor separate from feature" rule is the one that pays for itself fastest: when a bug ships, you can bisect by PR without having to untangle a renamed function from a changed behavior.
Wiring AGENTS.md into CodeRabbit (.coderabbit.yaml)
AGENTS.md on its own gets read by Claude Code and Copilot CLI. CodeRabbit needs one more step. Point it at the Code Direction section explicitly.
# .coderabbit.yaml
reviews:
path_instructions:
- path: "**"
instructions: |
Reference the "Code Direction" section in AGENTS.md.
Code that drifts from "patterns to increase": comment with `suggestion:`.
Code that matches "patterns to decrease": comment with `issue:`.
Always use Conventional Comments labels.
With this in place, CodeRabbit comments arrive pre-labeled, matched against your real patterns, and quoting the AGENTS.md rules by reference. The maintenance cost of CodeRabbit drops to editing one file.
The feedback loop that AGENTS.md unlocks
The reason to put review policy in AGENTS.md and not in a separate review-config file is that it closes the loop:
- A review surfaces a new pattern (say, you decide to use
Result<T, E>everywhere). - The pattern gets added to Code Direction with a reference path.
- The next PR Claude Code or Codex generates follows the new pattern.
- CodeRabbit flags any drift from the pattern on later PRs.
That is a four-step feedback loop operating across three AI tools. No single-tool config file can do that. The moment the config fragments, the loop breaks.
When one AGENTS.md isn't enough
A monorepo with a frontend subfolder and a backend subfolder will outgrow a single root AGENTS.md within weeks. The spec supports nesting. An AGENTS.md inside packages/frontend/ overrides the root for that subtree. Claude Code and Codex walk the tree down from the root; Copilot CLI only picks up AGENTS.md on the path from the current working directory up to the git root (nested-subtree discovery is tracked in copilot-cli#3051), so run it from the subfolder you want to scope.
Scope the Review Policy section to the repository root. Scope the Code Direction section to each sub-folder. Frontend and backend will have different "patterns to increase" lists, and that is exactly what the subfolder files are for.
The 4-section layout above is drawn from Chapter 6 of the Zenn book harness-code-review. The full book covers the three-layer review harness: pre-commit hooks, CodeRabbit tuning, GitHub Actions review pipelines, and PR metrics that make a review culture quantifiable.
Top comments (0)