Codex Code Review Rules: AGENTS.md Setup Guide

OpenAI added custom AGENTS.md repository rules to Codex Code Review on July 20, 2026. The useful change is not another style checker. Codex can apply team-specific guidance to the files changed by a pull request and point the author back to the relevant rule, while GitHub reviews remain focused on serious issues.

This guide uses first-party sources reviewed on July 21, 2026: OpenAI's launch article and live Codex documentation, the pinned openai/codex example linked from the launch, and the official OpenAI Developers announcement. AgentPedia did not run OpenAI's internal evaluation, so its reported results are labeled as vendor-run throughout.

What changed in Codex Code Review

Codex already used AGENTS.md as persistent repository context for coding tasks. OpenAI's launch extends that context into GitHub code review: a ## Code Review Rules section can describe non-obvious checks that Codex should apply while reviewing a pull request.

The practical difference is visible in the finding. Codex can connect a changed line to the repository-specific invariant behind it and explain the safe path. OpenAI's launch example protects the rawResponseItem/* event names used by Codex Cloud. The rule is visible in the launch-linked openai/codex AGENTS.md. A rename may compile cleanly but still break a consumer; the repository rule makes that integration contract explicit.

This article focuses on the review workflow. For the broader cross-tool purpose of instruction files, read the AgentPedia AGENTS.md guide. If instructions are not loading in an agent session, use the separate AGENTS.md troubleshooting guide.

How root and nested rules apply

Think about scope per changed file, not once for the pull request as a whole.

For each changed file:
  apply repository-wide review rules from the root AGENTS.md
  apply more-specific review rules from nested AGENTS.md files that cover its path
  ignore service rules from unrelated paths

OpenAI's current Code Review documentation says Codex applies the root guidance and the more-specific guidance that covers each changed file. It does not describe a nested AGENTS.md as erasing every root rule. Design the layers to work together: the root should hold invariants that truly apply everywhere, while a nested file adds the local constraints.

Consider this repository:

acme-platform/
├── AGENTS.md                         # repository-wide review rules
├── apps/
│   └── web/
│       └── src/checkout.ts
└── services/
    ├── payments/
    │   ├── AGENTS.md                 # payment-specific review rules
    │   └── src/refund.ts
    └── search/
        └── src/query.ts

The general Codex instruction loader also documents AGENTS.override.md and fallback filenames for interactive or CLI sessions. Code Review's public setup instructions specifically tell repositories to use AGENTS.md. Use that documented filename for review rules unless OpenAI publishes Code Review-specific support for the other discovery options.

Write review rules that are worth the model's attention

A useful rule contains four pieces:

1. A consequential invariant. State the behavior that must remain true, not a preference that can be enforced mechanically.
2. The evidence to inspect. Name the integration surface, data flow, or effect that reveals a violation without binding the rule to one temporary helper function.
3. Why the violation matters. Give enough repository context to distinguish a serious issue from an arbitrary convention.
4. A safe path or valid exception. Tell the author what preserves the invariant and when an apparent violation is acceptable.

OpenAI recommends concise, scoped sets and explicitly warns that broad instructions can create noise. Its guidance also says to prefer durable outcomes over implementation names and to keep formatting and lint checks in CI.

Here is the difference:

The stronger versions define observable behavior and an acceptable repair. They also leave room for context. A blanket “never rename a field” rule would incorrectly flag internal types and unreleased experiments; a public-contract rule targets the actual risk.

A copy-ready repository example

Start with a small root section. Adapt the nouns and safe paths to contracts that exist in your repository; do not paste generic policies that nobody owns.

# Repository instructions

## Code Review Rules

### Public API compatibility

- Flag removal or renaming of a public HTTP response field that may be used by
  a released client. Explain which route and field changed.
  Safe path: preserve the existing field during the documented deprecation
  window, or add a backward-compatible alias with a migration note.

### Sensitive data in logs

- Flag new logs that can include access tokens, session cookies, payment
  details, or unredacted request bodies.
  Safe path: log the stable request ID and an approved non-sensitive status;
  redact any allowlisted diagnostic field before it reaches the logger.

### Destructive data changes

- Flag a migration that drops or renames stored data before all deployed
  readers have stopped using it.
  Safe path: use expand–migrate–contract and remove the old shape in a later,
  separately reviewed release.

Then add local guidance only where the local consequence differs. For example:

# services/payments/AGENTS.md

## Code Review Rules

### Money movement state

- Flag code that marks a payment, refund, or payout successful before the
  provider result is durably recorded and reconciled.
  Safe path: persist the provider reference and terminal state atomically, or
  leave the operation pending for the reconciliation worker.

### Retry safety

- Flag a retryable money-movement request that lacks a stable idempotency key.
  Safe path: derive the key from the durable operation ID and reuse it for
  every attempt of the same operation.

These are templates, not claims about every API or payment system. Have the team that owns each invariant confirm the wording, exceptions, and remediation before committing the rule.

Enable and run Code Review on GitHub

The current GitHub workflow has three prerequisites: Codex cloud must be set up for the repository, your GitHub account must be connected with that repository selected, and you must have access to the Codex Code Review settings.

1. Connect the repository to Codex cloud and create its environment.
2. Open Codex settings and turn on Code review for the repository.
3. Commit the root AGENTS.md and any deliberately scoped nested files to the repository.
4. Open a representative pull request.
5. Leave the exact comment @codex review.
6. Wait for Codex to react and post a standard GitHub review.
7. Check whether each finding identifies the affected behavior, the applicable rule, and a workable safe path.

If every pull request should receive a pass, enable Automatic reviews in Codex settings. OpenAI says automatic review runs when someone opens a new pull request for review. Begin manually while tuning the rules; automatic noise is more expensive than one deliberate calibration PR.

Codex's GitHub review currently posts only P0 and P1 issues. That keeps comments focused, but it also means a lower-severity policy concern may not appear even if the instruction was available. Do not test discovery with a cosmetic convention and conclude the rule is broken when no comment appears.

For a one-off concern, put the focus in the pull-request comment instead of turning it into permanent repository policy:

@codex review for security regressions

After a finding appears, a follow-up such as @codex fix the P1 issue starts a cloud chat with the pull request as context. Codex can push a fix to the branch only when it has permission. Review the resulting diff and run the normal checks before accepting it.

Verify the rules without creating review noise

OpenAI's launch guidance proposes a compact three-case test: one change that should trigger the rule, one safe counterexample, and one unrelated change. A stronger rollout also checks that ordinary defect detection still works.

Keep the fixture in a disposable branch, not production behavior. Record the pull-request link, changed path, applicable rule, finding text, and false-positive result. Re-run the matrix after material rule edits. If a rule fires on the safe or unrelated case, narrow it before enabling automatic review.

When nothing happens, check the workflow before rewriting the prose:

• Code Review is enabled for the exact repository.
• Codex cloud has access to that repository.
• The comment is exactly @codex review.
• The relevant AGENTS.md is committed on the reviewed branch and covers the changed path.
• The scenario is consequential enough to pass the current P0/P1 output filter.
• The root and nested rules do not give incompatible safe paths.

What OpenAI's evaluation shows—and does not show

OpenAI reports that it built an evaluation suite with known rule violations and safe counterexamples. The team tested busy diffs, competing rules, clean changes, valid exceptions, ordinary bugs outside custom guidance, and whether findings identified the relevant guidance, location, and priority.

The 39.7-point difference supports a narrow conclusion: in OpenAI's primary internal suite, repository guidance substantially increased recovery of the custom findings the suite expected. It does not establish a general defect-detection rate, false-positive rate, production escape rate, or advantage over another review product.

The public launch material does not disclose the suite size, repository mix, model version, harness, number of runs, adjudication procedure, confidence intervals, or the separate results for restraint and ordinary-bug retention. Without those details, an external team cannot reproduce the result or estimate how it will transfer to a different codebase. Treat 98% as a reason to run the repository-specific matrix above, not as a reliability guarantee.

Limits and common failure modes

AGENTS.md rules supply context; they are not executable policy. Several failure modes follow from that boundary.

Review rules can also become stale policy. Assign an owner, review rule changes like code, and remove instructions that no longer change a review decision. If the team cannot name a realistic violating diff and a safe counterexample, the rule is probably not ready.

For teams building broader agent workflows around OpenAI tooling, the OpenAI Agents SDK guide covers orchestration and guardrails. If reviewers need to supervise Codex away from a workstation, the mobile coding-agent comparison explains what the Codex mobile surface can and cannot do.

Adoption checklist

• [ ] Codex cloud is connected only to the intended GitHub repositories.
• [ ] Code Review is enabled, and automatic reviews remain off during calibration.
• [ ] The root file contains no more than two or three initial review rules.
• [ ] Every rule names a consequential invariant and why it matters.
• [ ] Every rule includes a safe path or a valid exception.
• [ ] Service-specific rules live in a nested AGENTS.md near that service.
• [ ] Root and nested guidance are compatible for files where both apply.
• [ ] Formatting, lint, generated-file checks, and other deterministic policy stay in CI.
• [ ] A violation, safe counterexample, unrelated change, and ordinary serious bug have been reviewed in a test PR.
• [ ] Findings are checked for actionability and noise before automatic review is enabled.
• [ ] Tests, branch protections, code owners, and required approvals remain enforced.
• [ ] A named team owns each rule and periodically removes stale guidance.

The practical verdict

Use Codex Code Review rules when important repository knowledge is stable, consequential, hard to infer from a diff, and repeatedly explained by experienced reviewers. Large repositories with compatibility surfaces or service-specific data boundaries are the clearest fit.

Skip a rule and use CI instead when the requirement is deterministic: formatting, generated files, import boundaries, schema validation, or a forbidden string. A machine-checkable invariant is stronger as an executable test than as natural-language guidance.

Wait before enabling automatic review when the team has not tested safe counterexamples or cannot agree on the safe path. The highest-value configuration is a small reviewed rule set backed by ordinary engineering controls—not a policy handbook pasted into the model context.

Official sources

OpenAI product and setup documentation

• OpenAI Developers: Custom Code Review rules for Codex — launch details, rule-writing guidance, and the vendor-run evaluation summary
• Codex code review in GitHub — prerequisites, setup, manual and automatic triggers, P0/P1 output, scoped rules, and fix follow-ups
• Custom instructions with AGENTS.md — general instruction discovery plus the dedicated Code Review Rules guidance
• Codex cloud — GitHub connection, repository selection, environment setup, and cloud workflow

First-party implementation examples

• openai/codex root AGENTS.md at the launch-linked commit — model-context, breaking-change, test, and change-size review rules
• openai/codex PR #29086 — the change that documented the rawResponseItem/* compatibility surface used in OpenAI's example

Official social posts and media

• OpenAI Developers feature announcement
• OpenAI Developers Codex interface update and hero source