Codex でコードレビューをしていると、同じ指摘が繰り返し出てくることがあります。以前の API 契約を維持すること、顧客データをログに残さないこと、別のサービスの動作を妨げる名前変更を避けることなどです。どれも重要な確認事項ですが、その背景を一部のレビュアーしか知らなければ、見落とされがちです。
Codex のコードレビューで、AGENTS.md に記述したリポジトリ独自のルールを使えるようになりました。こうした問題を検出し、指摘の根拠となるガイダンスを変更の作成者に示せます。すでにコーディングタスクの指示に AGENTS.md を使っている場合は、同じファイルをレビューにも活用できます。特に、コントリビューターやコーディングエージェントがリポジトリ内の不慣れな部分を扱い、その経緯をまだ知らない場合に役立ちます。この記事では、テストから得られた知見も交えながら、リポジトリルールの役割と効果的な書き方を紹介します。
より多くのコードのリリース
コーディングエージェントは、より大規模な変更を引き受け、長時間にわたって作業を進められるため、チームがより多くのアイデアをコードにする助けになります。OpenAI では、第 4 四半期以降、週あたりの PR 数が 2 倍を超えており、多くのお客様にも同様の傾向が見られます。コードをより多く書けることは、新機能をリリースし、より多くの問題を解決するうえでプラスです。一方で、確認すべき点を把握している人のレビューを待つ Pull Request も増えるため、コードレビューがすぐにボトルネックになりかねません。
複数の変更が一度に届くと、レビューは難しくなります。差分にまったく問題がないように見えても、古いクライアントが動かなくなったり、作成者が知らなかった境界を越えたりすることがあります。誰かがその背景を覚えていて、作成者がまだ対応できるうちに共有する必要があります。
レビューのボトルネック
Pull Request が増えるほど、レビュアーがフィードバックを返す前に各変更の意図を読み解き、関連する背景情報を集める時間は少なくなります。作成者が別の作業に移ってしまうと、小さな修正でも時間がかかりがちです。素早いフィードバックがあれば、人がボトルネックになることなく、開発の高速化をチームの成果につなげられます。
差分だけでは見つけにくい問題もあります。レスポンスのフィールド名の変更は、よくあるコードの整理に見えるかもしれませんが、既存の契約に依存するクライアントが動かなくなる可能性があります。経験豊富なレビュアーなら、そのフィールドを残す必要がある理由を覚えているかもしれません。しかし、新しいコントリビューターや、そのサービスを初めて扱うエージェントは、おそらく知りません。
インターフェースとしてのルール
では、チームが時間をかけて身につける背景知識を、コーディングエージェントにどう伝えればよいのでしょうか。新しいリポジトリルールのインターフェースでは、適用範囲を絞った簡潔なレビューガイダンスを 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 のコードレビューを試してみましょう。