Custom Code Review rules for Codex

Shipping more code

Coding agents can take on larger changes and work over longer horizons, helping teams move more of their ideas into code. At OpenAI, weekly PR volume has more than doubled since Q4, and we’re seeing similar trends for many of our customers. More code is good: it helps teams ship new features and solve more problems. It also means more pull requests waiting for someone who knows what to look for, and code review can quickly become the bottleneck.

Review gets harder when several changes arrive at once. A diff can look completely reasonable and still break an older client or cross a boundary the author did not know about. Someone has to remember that context and share it while the author can still act on it.

The review bottleneck

When more pull requests land, reviewers have less time to work out what each change is trying to do and gather the relevant context before leaving feedback. Once an author moves on to something else, even a small revision can take longer. Fast feedback helps teams make the most of faster development without asking people to become the bottleneck.

Some issues are also hard to spot from the diff alone. Renaming a response field might look like routine cleanup, but it can break clients that still depend on the existing contract. An experienced reviewer may remember why that field needs to stay; a new contributor or an agent working in the service for the first time probably won’t.

Rules as an interface

So how do you give a coding agent the context your team normally picks up over time? The new repository-rules interface lets you put concise, scoped review guidance in AGENTS.md. Codex Code Review can apply the rules that matter to a change and cite them in a finding. Instead of repeating the same explanation in every pull request, you can keep it close to the code it applies to.

As coding models become more steerable, a short, well-scoped instruction can help focus a long review on the things your team actually cares about. The Codex repository itself keeps Code Review rules in AGENTS.md, covering concerns such as model-visible context and breaking changes.

Here’s a real example:

The Codex app-server emits an internal notification named rawResponseItem/completed. It is marked experimental, but Codex Cloud already consumes it. The repository’s breaking-change review rule explicitly calls out rawResponseItem/* as an integration surface that reviewers should preserve, even while experimental.

The existing wire name is defined in the app-server protocol. Imagine a cleanup changed one line:

RawResponseItemCompleted => "rawResponseItem/completed"
RawResponseItemCompleted => "rawResponseItem/done"

The change compiles, but clients listening for the existing notification would stop receiving it. The relevant repository-rule excerpt is concise:

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

For that illustrative diff, a Code Review finding could read:

Keep the existing rawResponseItem/completed notification. Codex Cloud consumers listen for this wire name, so renaming it will break them even though the event is experimental. Keep the existing name or add a backward-compatible event, as described in AGENTS.md.

The Codex team added this rule specifically to protect Codex Cloud consumers. Keep repository-wide rules at the root and service-specific rules in the relevant directory. During review, Codex can apply the guidance that covers the changed files and point authors to the relevant rule; an unrelated change does not need app-server context.

Rules sit alongside the other tools teams already rely on. Tests and linters work well for checks you can express deterministically; repository rules help capture the judgment that is harder to encode. Compatibility requirements and data boundaries are good places to start. Authors do not need to know every past incident or local convention before they make a change; the relevant guidance is already there.

Writing rules that hold up

We tested how well Code Review could use repository guidance with an eval suite that included known rule violations and safe counterexamples. In the primary suite, rule-guided variants recovered 98% of the required custom findings, compared with 58.3% in the baseline control.

We found the same pattern while using rules in internal repositories. Codex could find and cite local guidance that a default review might miss, but broad instructions could easily create noise. Small, scoped sets with an explicit safe path helped Codex focus on what was most useful without applying a rule to every nearby change.

Start with a consequential, non-obvious invariant. Encode a check reviewers repeatedly explain, such as a compatibility requirement or data boundary. If removing a rule would not change the review, leave it out.

Scope rules to the code they govern. Put repository-wide guidance at the root and service-specific guidance in a nested AGENTS.md. Narrow scope keeps unrelated instructions from competing for attention and makes ownership clear.

State the invariant and the safe path. The rawResponseItem/* rule identifies the compatibility risk. “Keep the existing name or add a backward-compatible event” gives authors a clear alternative.

Keep rules durable and current. Describe outcomes, not function names that may change. Review updates to the rules and narrow or remove guidance that repeatedly produces noise.

Keep formatting and other mechanical checks in CI. Save repository rules for the questions a reviewer would otherwise have to ask again.