Codex Code Review Gets Custom AGENTS.md Rules
CodexOpenAI now lets teams add a ## Code Review Rules section to their repository's AGENTS.md file, which Codex Code Review reads and applies when reviewing pull requests. The feature is aimed at repo-specific institutional knowledge — like preserving a deprecated API contract or keeping customer data out of logs — that reviewers previously had to explain by hand every time it came up. In OpenAI's internal testing, rule-guided reviews recovered 98% of intended findings versus 58.3% for baseline reviews, while staying restrained on unrelated changes.
Key Takeaways
- Custom review rules live in
AGENTS.md, the same file many teams already use to steer Codex's coding behavior — no new config file needed. - Rules can be scoped narrowly, with repository-wide guidance at the root and service-specific rules in nested
AGENTS.mdfiles closest to the code they protect. - OpenAI recommends starting small — one or two high-impact, non-obvious invariants rather than an exhaustive rulebook, leaving formatting/lint checks to CI.
- Internal testing showed a jump from 58.3% to 98% in recovered findings when reviews were guided by repository rules versus baseline Codex reviews.
- The feature targets tribal-knowledge gaps — constraints like preserving a deprecated API or keeping customer data out of logs that previously lived only with a handful of senior reviewers.
- It's especially useful for contributors and coding agents working in unfamiliar parts of a repo, where they wouldn't otherwise know a section's history or hidden constraints.
Codex Code Review Learns Repository-Specific Rules
OpenAI has extended Codex Code Review with support for custom rules defined directly inside a repository's AGENTS.md file, giving teams a way to encode the kind of institutional knowledge that used to live only in senior reviewers' heads. The feature addresses a problem that has grown more visible as coding agents accelerate pull request volume: reviewers increasingly have to explain the same repo-specific constraints over and over — preserving an old API contract, keeping customer data out of logs, or avoiding a rename that silently breaks another service — because that context rarely gets written down anywhere Codex can see it.
How It Works
Teams add a ## Code Review Rules section to the AGENTS.md file closest to the code the rules govern — repository-wide rules at the root, and service-specific rules in nested files (for example services/experiment_reporting/AGENTS.md). Codex Code Review reads whichever rules apply to the files touched in a pull request and references them directly in its findings, pointing authors back to the reasoning behind a flagged issue rather than just the issue itself. Because AGENTS.md is the same file many teams already use to steer Codex's coding behavior, adding review guidance requires no new configuration surface — the same document now guides both how Codex writes code and how it reviews it.
Writing Effective Rules
OpenAI's guidance for authoring rules emphasizes restraint: start with one or two consequential, non-obvious invariants that reviewers find themselves repeatedly explaining, rather than trying to enumerate every possible mistake. Good rules are scoped narrowly to the code section they protect, state both the risk and a safe alternative, and focus on outcomes rather than implementation minutiae. OpenAI recommends leaving purely mechanical checks — formatting, linting — to CI, reserving AGENTS.md rules for the judgment calls that actually require context.
Measured Impact
In OpenAI's own testing, rule-guided reviews recovered 98% of the issues they were designed to catch, compared with 58.3% for baseline reviews without repository-specific rules, while remaining restrained on unrelated code. The feature is particularly aimed at situations where contributors, or coding agents themselves, are working in an unfamiliar part of a codebase and have no way of knowing its history without asking.