How to Add Custom Codex Code Review Rules in AGENTS.md

Add a ## Code Review Rules section to the AGENTS.md closest to the code you want Codex to review. Write two or three concise rules that name a consequential invariant, the change to flag, and a safe alternative. Then open a representative pull request, request @codex review, and test one violation, one safe counterexample, and one unrelated change.

That is the shortest useful setup. The rest of this guide gives you a copyable rule set, explains file scope and precedence, and shows how to tell a useful review rule from a check that belongs in CI.

Prerequisites

You need:

• a GitHub repository with Codex Code Review enabled;

• permission to edit the applicable AGENTS.md file;

• one recurring, repository-specific review concern;

• a small test pull request that is safe to close without merging.

If Codex Code Review is not enabled yet, follow OpenAI's Code Review setup guide. Custom rules do not replace branch protection, required approvals, tests, or security controls.

Step 1: Pick a Rule That Needs Reviewer Judgment

Start with a defect or risk that experienced reviewers repeatedly explain but that a generic model cannot infer from the diff alone. Good candidates include:

• a wire name or API field that older clients still consume;

• a data boundary that prevents customer information from reaching logs;

• a database rollout sequence needed for old and new application versions to overlap;

• a repository-specific security invariant;

• a change-size boundary that signals when work should be split.

Do not start with formatting, import order, generated files, or a check that can be expressed deterministically. Put those in a formatter, linter, test, or CI job. Repository rules guide review judgment; they are not hard enforcement.

Step 2: Add a Small Code Review Rules Section

At the repository root, add rules that apply everywhere:

## Code Review Rules

### Backward-compatible API changes

- Flag renamed or removed response fields used by existing clients.
  Safe path: keep the old field during an expand-and-contract rollout, or add a new field without changing the existing contract.

### Customer data in logs

- Flag logs that include request bodies, access tokens, email addresses, or other customer data.
  Safe path: log stable internal identifiers and structured error codes instead.

### Change size

- Flag non-mechanical changes over 800 changed lines.
  Safe path: identify the smallest independently testable stage and move follow-up work to a separate pull request

Each rule has three useful parts:

1. The invariant: what must remain true.

2. The trigger: what the reviewer should flag.

3. The safe path: what the author can do instead.

Avoid a vague rule such as "check for security issues." It gives Codex no repository-specific decision boundary and is likely to produce generic feedback.

Step 3: Put Service-Specific Rules Near the Service

Codex builds an instruction chain from the repository root toward the working directory. Guidance closer to the changed code appears later and can override broader guidance.

For a payments service, put local review context in services/payments/AGENTS.md:

## Code Review Rules

### Idempotent payment retries

- Flag payment creation or capture retries that do not reuse the original idempotency key.
  Safe path: persist the key before dispatch and reuse it for every retry of the same logical payment

Keep repository-wide checks in the root file and service-specific checks in the nearest nested file. Do not copy the same rule into both places. One rule should have one owner and one source of truth.

If the wrong instructions appear, check for AGENTS.override.md. Codex prefers that filename over AGENTS.md in the same directory. Start a new Codex run after editing instructions because the instruction chain is assembled at the start of a run.

Step 4: Test the Rule With Three Pull Request Cases

Create a focused test branch and make three small cases, either in sequence or as separate commits:

Push the test branch, open a draft pull request, and comment:

@codex review

Expected result: the violation produces an actionable finding that cites the relevant guidance, while the safe and unrelated cases remain quiet. OpenAI recommends exactly this violation, counterexample, and unrelated-change pattern when refining a rule.

If the violation is missed, make the trigger more concrete. If safe code is flagged, narrow the scope and add the allowed path or exception. Remove rules that repeatedly create noise or do not change review behavior.

Step 5: Keep Hard Gates Outside AGENTS.md

An AGENTS.md rule can focus an additional reviewer, but it cannot guarantee compliance. Use the right enforcement layer:

This distinction explains a common failure report: a rule can influence a review finding, but it is not a pre-commit hook or policy engine. If a requirement must block a merge, encode a deterministic check where possible and make that check required.

Common Failures

Codex Does Not Mention the Rule

Confirm the section heading is exactly ## Code Review Rules, the file is in scope for the changed path, and no AGENTS.override.md is replacing it. Start a new run, then retry with a smaller, representative diff.

Every Pull Request Gets the Same Warning

The rule is too broad or too far up the directory tree. Move it to the closest service-level AGENTS.md, name the precise trigger, and add the safe path.

The Rule Duplicates a Linter

Delete it from AGENTS.md and make the linter or CI job authoritative. Review attention is scarce; spend it on checks that require repository history or judgment.

A Serious Violation Still Merges

Codex Code Review is an additional reviewer. Add a required test, branch rule, approval, or code-level guard for anything that must be enforced. Keep the review rule as context only when human judgment is still useful.

The Instructions File Keeps Growing

Retire stale rules and move specialized guidance into nested files. A durable rule names an outcome or invariant, not a function name likely to change next week.

Run the Same Review From Your Coding Agent

Aident Loadout can give a coding agent a scoped way to discover Codex's local review action instead of hard-coding a command into every prompt. The current catalog exposes the read-oriented cli:codex:exec_review Action for reviewing the current repository.

Ask your coding agent:

Follow https://aident.ai/SETUP.md
Find the Codex Action that reviews the current repository. Review this branch
against main, verify every finding against the diff, and do not change files

Keep the first run read-only and measurable. Record the number of findings reported, confirmed, and fixed before merge. That tells you whether the new rule adds signal instead of merely adding comments.

For a bounded cross-model workflow, see How to Use Codex Inside Claude Code for Code Review. If your instruction files have drifted between tools, use How to Migrate from Claude Code to Codex Without Losing Your Setup.

Use Aident Loadout to run one scoped Codex review, compare reported findings with confirmed defects, and decide whether the rule deserves to stay.

Sources

• OpenAI: Custom Code Review rules for Codex

• OpenAI: Custom instructions with AGENTS.md

• OpenAI: Codex Code Review

• OpenAI Codex repository AGENTS.md

• AGENTS.md open format

Refresh this guide when Codex changes its review-rule heading, instruction discovery order, GitHub review command, or Code Review setup contract.