Codex でコードレビューをしていると、何度も同じ指摘をすることがあります。従来の API 契約を守る、顧客データをログに残さない、別のサービスが動かなくなるような名前の変更を避ける、といった指摘です。いずれも重要な確認事項ですが、その背景を知っているレビュアーが数人しかいないと、見落としがちです。
Codex のコードレビューでは、AGENTS.md に記述したリポジトリ独自のルールに基づいてこうした問題を検出し、指摘の根拠となるルールを変更の作成者に示せるようになりました。すでに AGENTS.md にコーディングタスクの指示を書いている場合は、同じファイルをレビューにも活用できます。コントリビューターやコーディングエージェントが、これまでの経緯をよく知らないままリポジトリ内の不慣れな箇所を変更する際に、特に役立ちます。この記事では、リポジトリのルールがレビューで果たす役割と効果的な書き方を、検証で得られた知見とともに紹介します。
開発量の増加
コーディングエージェントは、より大きな変更や長期にわたる作業を担えるようになり、チームはより多くのアイデアをコードに落とし込めるようになりました。OpenAI では、週あたりの PR 件数が第 4 四半期の 2 倍を超えました。多くのお客様のもとでも同様の傾向が見られます。開発量が増えると、チームは新機能をリリースし、より多くの問題を解決できます。一方で、確認すべき点を知っている人のレビューを待つ pull requests も増え、コードレビューがたちまちボトルネックになりかねません。
複数の変更が同時に届くと、レビューは難しくなります。差分を見る限りまったく妥当な変更でも、古いクライアントが動かなくなったり、作成者が知らなかった境界を越えてしまったりすることがあります。誰かがその背景を覚えていて、作成者がまだ対応できるうちに伝える必要があります。
レビューがボトルネックになる理由
pull requests が増えると、レビュアーがフィードバックを返すまでに、個々の変更の意図を読み取り、必要なコンテキストを集める時間が減ります。作成者が別の作業に移った後では、小さな修正にも時間がかかりがちです。フィードバックを早く返せれば、レビュー待ちで人の手を止めることなく、開発速度の向上を活かせます。
差分だけでは見つけにくい問題もあります。たとえば、レスポンスのフィールド名を変更するだけなら、よくあるコード整理に見えます。しかし、既存の API 契約に依存するクライアントが動かなくなるおそれがあります。経験豊富なレビュアーなら、そのフィールドを残す理由を覚えているかもしれません。新しく参加したコントリビューターや、そのサービスを初めて扱うエージェントは、おそらくその理由を知りません。
ルールを通じたコンテキストの共有
チームのメンバーが時間をかけて学んできた背景知識を、コーディングエージェントにどう伝えればよいでしょうか。新しい仕組みでは、適用範囲を絞った簡潔なレビュー指針を、リポジトリのルールとして AGENTS.md に記述できます。Codex のコードレビューは、変更に関係するルールを適用し、指摘の根拠として引用できます。pull request のたびに同じ説明を繰り返さずに済むよう、対象のコードの近くにその説明を残しておけます。
コーディングモデルが指示にきめ細かく従えるようになるにつれ、短くても適用範囲が明確な指示があれば、長いレビューでもチームが重視する点に集中しやすくなります。Codex 自体のリポジトリでも、AGENTS.md にコードレビューのルールを記述しています。モデルから見えるコンテキストや破壊的変更などが対象です。
実際の例を見てみましょう。
Codex の app-server は、rawResponseItem/completed という内部通知を送信します。この通知は実験的な機能とされていますが、Codex Cloud がすでに利用しています。リポジトリの破壊的変更に関するレビュールールでは、rawResponseItem/* は外部との連携に使われるため、実験段階でも互換性を維持できるようレビュアーが確認すべきだと明記しています。
通信で使う既存の通知名は app-server のプロトコルで定義されています。コードの整理で次の 1 行を変更したとします。
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"変更後もコンパイルは通りますが、既存の名前で通知を待ち受けているクライアントには通知が届かなくなります。該当するリポジトリのルールは、次のように簡潔です。
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimentalこの差分に対するコードレビューの指摘は、たとえば次のようになります。
既存の
rawResponseItem/completed通知を維持してください。 Codex Cloud 側ではこの名前で通知を待ち受けています。実験段階のイベントであっても、名前を変えると受信できなくなります。AGENTS.mdに記載されているとおり、既存の名前を維持するか、後方互換性のあるイベントを追加してください。
Codex チームは、Codex Cloud 側で引き続き通知を受信できるよう、このルールを追加しました。リポジトリ全体に適用するルールはルートに、サービス固有のルールは該当するディレクトリに置きます。レビュー時に Codex は、変更されたファイルに適用される指針を使い、該当するルールを作成者に示せます。無関係な変更のレビューに app-server のコンテキストを持ち込む必要はありません。
ルールは、チームがすでに使っているツールと併用できます。結果を機械的に判定できるチェックにはテストやリンターが適しています。リポジトリのルールには、コードで表現しにくい判断基準を記録できます。まずは、互換性の要件や、データをどこまで渡してよいかといった境界を明文化するとよいでしょう。必要な指針があらかじめ用意されていれば、作成者は過去のインシデントやその箇所に固有の規約をすべて把握してから変更に取りかかる必要はありません。
実際のレビューで役立つルールの書き方
既知のルール違反と、違反に似ていても問題のない変更例を含む評価スイートを使い、コードレビューがリポジトリの指針をどれだけ活用できるかを検証しました。主要な評価スイートでは、カスタムルールに照らして指摘すべき問題のうち、ルールを与えた条件で 98% を検出できました。比較対象のベースラインでは 58.3% でした。
ルール違反を見つけることは、レビューの役割の一部にすぎません。複数のルールを同時に考慮する必要がある場合や、pull request にすでに多くの変更が含まれている場合にどうなるかも調べました。影響の大きい違反と、指摘が不要な変更の両方をテストし、次の 4 つの観点から結果を整理しました。
評価項目
検出の網羅性
差分が複雑で、複数のルールを考慮する必要がある場合でも、Codex は検出対象の違反を見つけられるか。
不要な指摘の抑制
問題のない変更や妥当な例外に対して、不要な指摘を避けられるか。
従来の検出能力の維持
コードレビューは、リポジトリのルールが対象としない一般的なバグも引き続き検出できるか。
対応のしやすさ
個々の指摘に、根拠となる指針、該当箇所、優先度が示されているか。
指針の書き方についても、短い箇条書きから、特定のチームが担当するセクションにまとめる方法まで、よく使われる形式を試しました。
社内リポジトリでルールを使った際にも、同じ傾向が見られました。Codex は、通常のレビューでは見落としがちな、その箇所に固有の指針を見つけて引用できました。一方で、指示の範囲が広いと不要な指摘が出やすくなりました。ルールの数と適用範囲を絞り、安全な変更方法を明示すると、Codex は周辺の変更すべてにルールを当てはめることなく、特に役立つ指摘に集中できました。
まずは、見落としやすく、違反すると影響が大きい条件を選びます。 互換性の要件やデータの境界など、レビュアーが繰り返し説明している確認事項をルールにします。そのルールがなくてもレビュー結果が変わらないなら、含める必要はありません。
ルールの適用範囲を対象のコードに合わせます。 リポジトリ全体の指針はルートに、サービス固有の指針は該当するサブディレクトリの AGENTS.md に置きます。適用範囲を絞ると、無関係な指示に注意を取られずに済み、誰がルールを管理するのかも明確になります。
守るべき条件と、安全な変更方法を明記します。 rawResponseItem/* のルールは、互換性が損なわれるリスクを示しています。「既存の名前を維持するか、後方互換性のあるイベントを追加する」と書けば、作成者はどのような変更なら安全かを判断できます。
長く使えるルールを書き、定期的に見直します。 変更される可能性のある関数名を挙げるよりも、どのような結果を維持すべきかを記述します。ルールの変更もレビューし、不要な指摘を繰り返す指針は適用範囲を絞るか削除します。
フォーマットなど、機械的に確認できる項目は CI でチェックします。リポジトリのルールには、レビュアーがその都度確認しなければならない事項を記述しましょう。
導入手順
リポジトリですでに Codex のコードレビューを有効にしている場合は、該当する AGENTS.md ファイルに 2～3 個のルールを追加し、典型的な変更を含む pull request を開きます。初めて利用する場合は、コードレビューのクイックスタートで、GitHub リポジトリで有効にする手順を確認できます。@codex review で直接レビューを依頼することもできます。
まずは、レビュアーが繰り返している説明や、見落とすと影響が大きいリポジトリ固有のミスを取り上げます。ルールに基づいて指摘すべき変更、それに似ていても安全な変更、ルールと無関係な変更を 1 つずつ試してください。最初の変更には役立つ指摘があり、残りの 2 つには不要な指摘がないことを確認し、結果をもとに指針を調整します。
Codex のコードレビューは、追加のレビュアーとして機能します。マージの条件を強制する役割は、引き続きテスト、ブランチ保護、必須の承認が担います。
変更を書くよりもレビューに時間がかかっているなら、チームが繰り返している確認事項を 1 つ選びましょう。それを AGENTS.md に追加し、次の pull request で Codex のコードレビューを試してみてください。