7月22日、OpenAIが「Custom Code Review rules for Codex」と題した記事を公開した。この記事では、AGENTS.mdにカスタムルールを記述することでCodexのコードレビューをプロジェクト固有の知識に対応させる方法について詳しく紹介されている。
PRが増えるほど、レビューがボトルネックになる
OpenAI社内では、コーディングエージェントの活用が進んだ結果、週次のPR件数がQ4比で2倍以上に増加した。同様のトレンドは多くの顧客でも確認されているという。
コードが増えることは良いことだが、問題はレビュー側だ。複数のPRが一度に届くと、レビュアーが個々の変更の意図を把握し、必要なコンテキストを集める時間は削られる。そして、コードの差分だけを見ていると見逃しやすい問題がある。
たとえば、レスポンスフィールドのリネームは「ただの整理」に見えるが、既存のAPIコントラクトに依存しているクライアントを壊す可能性がある。経験豊富なレビュアーなら「このフィールドは変えてはいけない」と知っているが、新しいコントリビューターやエージェントはその経緯を知らない。
AGENTS.mdにルールを書くだけ
AGENTS.mdは、OpenAI Codexのコーディングエージェントに対してリポジトリ固有の指示を与えるための設定ファイルだ。コーディングタスクの誘導に使われてきたが、今回のアップデートによりCodex Code Reviewのカスタムルール定義にも活用できるようになった。コーディングタスクの誘導にすでにAGENTS.mdを使っているチームであれば、同じファイルをレビュー用途にも流用できる。
実際の例を見ると分かりやすい。Codexのapp-serverはrawResponseItem/completedという内部通知を送出する。experimentalとマークされているが、Codex Cloudはすでにこれを購読している。ここで、以下のような「cleanup」が行われたとする。
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"
コンパイルは通る。しかし、既存の通知名を購読しているクライアントは通知を受け取れなくなる。AGENTS.mdには以下のルールが記述されている。
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimental
このルールに基づき、Codex Code Reviewは次のような指摘を生成する。
Keep the existing
rawResponseItem/completednotification. 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 inAGENTS.md.
ルールの参照先（AGENTS.mdの該当箇所）まで指摘に含まれるため、著者はなぜその指摘がなされたのかを即座に理解できる。Codexリポジトリ自体もこの仕組みを実運用で使っており、モデルへの公開コンテキストや破壊的変更に関するルールが記述されている。
効果の検証と、ルールの書き方
OpenAIはevalスイートを使って精度を測定した。ルールありの構成では既知の違反を98%検出し、ルールなしのベースラインの58.3%を大きく上回った。
ただし、違反を見つけることだけがゴールではない。「関係ないPRに誤ってルールが適用されないか（ノイズの排除）」「通常のバグ検出能力が損なわれていないか」「各指摘が著者にとって実行可能か」という3つの観点でも評価している。
内部リポジトリでの運用から得た知見として、記事では以下の書き方を推奨している。
- 重大かつ非自明な不変条件から始める。レビュアーが繰り返し説明している互換性要件やデータ境界を最初にエンコードする。ルールを削除してもレビュー結果が変わらないなら、そのルールは不要。
- ルールのスコープをそのコードに限定する。リポジトリ全体に適用するルールはルートの
AGENTS.mdに、サービス固有のルールはそのディレクトリ配下のAGENTS.mdに置く。 - 不変条件と安全なパスを両方書く。「変えてはいけない」だけでなく、「では何をすべきか」（後方互換なイベントを追加する、など）を明示する。
- 関数名ではなく、結果を記述する。関数名は変わるが、達成すべきことは変わらない。
- フォーマットチェックなどの機械的な検証はCIに任せる。
AGENTS.mdのルールは、決定論的にエンコードしにくい判断のために使う。
始め方
リポジトリにすでにCodex Code Reviewが有効になっていれば、すぐに試せる。手順は以下の通りだ。
- 対象の
AGENTS.mdに2〜3のルールを追加する - 代表的なPRを開き、
@codex reviewとコメントしてレビューをリクエストする - ルールを発火させるべき変更・発火させてはいけないクリーンな変更・関係ない変更の3種類を用意し、それぞれの結果を確認してからルールを調整する
まだCodex Code Reviewを有効にしていない場合は、Code Review quickstartでGitHubリポジトリへの設定手順が確認できる。
Codex Code Reviewはあくまで追加のレビュアーという位置付けであり、テスト・ブランチ保護・必須承認といった既存の仕組みは引き続き機能する。
詳細はCustom Code Review rules for Codexを参照していただきたい。
