Codex code review in GitHub 実践ガイド - @codex review と AGENTS.md の設計

Codex を GitHub PR のレビューに入れたいが、どの PR で呼ぶべきか、何を見てもらうべきか、指摘をそのまま修正依頼してよいのかで迷いやすいです。

特にチーム運用では、「AI レビューを増やせば品質が上がる」とは限りません。人間が見る前のノイズが増えるだけなら、レビュー時間はむしろ伸びます。逆に、差分の危険面、テスト不足、仕様変更の見落としに絞れば、Codex code review はかなり実用的な二段目の目になります。

この記事では、2026年6月1日時点の OpenAI 公式ドキュメントを前提に、GitHub 上の @codex review、自動レビュー、AGENTS.md の Review guidelines をどう設計するかに絞ります。Codex cloud の環境再現性は Codex cloud environment 設計ガイド、sandbox / approval の権限境界は Codex sandbox / approvals 設計ガイド、複数エージェントや worktree 分離は Codex cloud / 複数エージェントの使い方に分けています。

先に結論: Codex review は「merge 前の高リスク確認」に寄せる

私なら、Codex code review を最初から全 PR に自動投入しません。まずは次のような PR に限定します。

PR の種類	Codex review を呼ぶ理由
auth / permission まわり	認可漏れ、guard の抜け、権限昇格を見落としやすい
dependency 追加	supply chain、license、初期化コードの副作用を確認したい
database migration	rollback、nullable、既存データ影響を確認したい
payment / billing	金額、idempotency、監査ログの抜けが痛い
大きめの refactor	仕様変更していないつもりの回帰を拾いたい
test 追加なしの実装 PR	何を検証すべきかを洗い出したい

逆に、誤字修正、画像差し替え、軽い CSS 調整、既に人間が十分にレビューした小変更に毎回入れると、指摘の価値より待ち時間と通知の方が目立ちます。

Codex review は「人間レビューの代替」ではなく、人間が見る前に危険面を先に浮かせるフィルタとして使う方が安定します。

何が既存 Codex 記事と違うのか

このサイトには、すでに Codex の運用記事がいくつかあります。この記事の役割は、そこからさらに GitHub PR レビューへ絞ることです。

記事	扱う範囲
Codex Automations	定期実行、background work、inbox review
Codex 複数エージェント	worktree 分離、並列作業、cloud / local の使い分け
Codex cloud environment	setup script、secrets、cache、internet access
Codex sandbox / approvals	workspace-write、approval、network allowlist
この記事	`@codex review`、自動 PR review、Review guidelines

つまり、この記事は「Codex に作業させる」話ではなく、Codex にレビューさせるときの運用設計です。

`@codex review` で始める

OpenAI の Codex GitHub integration docs では、PR コメントに @codex review と書くと Codex review を要求できると説明されています。Codex は PR diff を読み、リポジトリ内の指示に従い、GitHub の code review として結果を投稿します。

最初の導入では、私は自動レビューではなく手動コメントから始めます。

@codex review for security regressions, missing tests, and risky behavior changes.

この prompt は短いですが、見るべき面を3つに絞っています。

security regressions
missing tests
risky behavior changes

最初から「全部レビューして」では広すぎます。AI レビューで本当に欲しいのは、スタイル指摘ではなく、見落としたら痛い変更です。

AGENTS.md に Review guidelines を置く

Codex review をチーム運用に入れるなら、毎回 PR コメントで細かく指示するより、AGENTS.md に Review guidelines を置く方が安定します。OpenAI docs でも、Codex はリポジトリ内の AGENTS.md を探し、変更ファイルに近い指示を参照すると説明されています。

たとえば、最初はこの程度で十分です。

## Review guidelines

- Prioritize P0/P1 findings only.
- Flag missing tests when behavior changes.
- Flag auth, permission, payment, and migration regressions.
- Do not block on wording, style, or minor refactors unless they change behavior.
- If the diff touches secrets, tokens, logging, or external network calls, explain the data exposure risk.

ここで大事なのは、何を見ないかも書くことです。

「誤字も全部拾う」「命名も全部見る」「設計改善も全部見る」と書くと、Codex review は人間レビュー前のノイズ源になります。最初は P0/P1 相当の重大指摘に寄せるべきです。OpenAI docs でも GitHub 上では高優先度の issue に絞る趣旨が示されています。

P0/P1 の意味をチームで固定する

Codex review のコメントを受け取る側が困るのは、「これは直すべきなのか、参考意見なのか」が曖昧な状態です。だから、PR 運用では優先度の意味を先に固定します。

私は次のように分けます。

優先度	扱い	例
P0	merge blocker	認可抜け、秘密情報露出、データ破壊、支払い事故
P1	原則 merge 前に対応	test 不足、migration の rollback 不備、明確な回帰
P2	follow-up issue 可	境界ケース、リファクタ余地、軽い設計改善
P3	レビュー対象外	文体、好み、命名の揺れ

Codex にもこの基準を渡します。

## Review guidelines

- Treat auth bypass, data loss, secret exposure, and payment mistakes as P0.
- Treat missing tests for behavior changes as P1.
- Treat style-only comments as out of scope unless they hide a bug.

このくらい明確にすると、レビューコメントの扱いが揃います。

自動レビューは repo 全体ではなく対象を選ぶ

OpenAI docs では、Codex code review を自動で全 PR に走らせる設定も用意されています。ただし、導入初日から全 repository / 全 PR に入れるのは勧めません。

最初は次の順で広げる方が現実的です。

手動 @codex review で 5〜10 本の PR を見る
良い指摘とノイズを分類する
AGENTS.md の Review guidelines を直す
auth / billing / API など高リスク package だけ深い guidelines を置く
重要 repo だけ automatic reviews を有効化する

特定 package にだけ深いルールを置きたいなら、近い階層に AGENTS.md を置きます。

AGENTS.md
apps/web/AGENTS.md
packages/billing/AGENTS.md
packages/auth/AGENTS.md

packages/billing/AGENTS.md には idempotency、currency、rounding、監査ログの観点を書く。packages/auth/AGENTS.md には middleware、role check、session invalidation の観点を書く。こうすると、リポジトリ全体の AGENTS.md を太らせずに済みます。

指摘を直させる前に、人間が分類する

Codex review の後に @codex fix it のような follow-up を投げると、Codex は PR を文脈に cloud task を開始し、権限があれば branch を更新できます。

これは便利ですが、私は次の順番を守ります。

Codex review の指摘を P0/P1/P2 に分類する
本当に PR 内で直すべきか判断する
直すなら scope を1つに絞って依頼する
修正後に CI と人間レビューを通す

悪い例はこれです。

@codex fix all review comments

この依頼は範囲が広すぎます。レビューコメントには「即修正」「別 PR」「仕様判断」「無視」が混ざるからです。

良い依頼はこうです。

@codex fix the P1 missing test for the authorization fallback only. Do not refactor unrelated code.

修正対象を狭めると、差分もレビューしやすくなります。

Codex Security と code review を混ぜない

2026年時点では、Codex Security という別の導線もあります。これは GitHub repository に接続し、脅威モデルを作り、脆弱性を探索・検証し、修正案を出す research preview です。

一方で、Codex code review in GitHub は PR diff を見て、回帰、missing tests、危険な変更をレビューする機能です。似ていますが、目的が違います。

使う場面	向いているもの
PR の差分を merge 前に見る	Codex code review
repo 全体の脅威モデルを作る	Codex Security
脆弱性の再現と修正案まで欲しい	Codex Security
通常の開発 PR の review signal が欲しい	Codex code review

この2つを混ぜると、PR review に脆弱性診断の深さを期待しすぎたり、Security 側に通常の style review を期待したりします。運用上は別物として扱うべきです。

導入時の最小チェックリスト

最初に決めるべきことは多くありません。

Codex cloud が対象 repository で使えるか
code review 設定を誰が有効化するか
手動 @codex review から始めるか、自動レビューも有効にするか
AGENTS.md の Review guidelines をどこに置くか
P0/P1 の意味をチームでどう扱うか
@codex fix を誰が許可するか
修正後に必ず実行する検証コマンドは何か

このうち 6 と 7 は特に大事です。レビュー指摘を修正させる段階では、Codex は単なる reviewer ではなく contributor になります。ここからは AIコーディングツールの社内ガイドラインと同じく、入力境界、実行境界、レビュー境界を明確にした方がよいです。

よくある失敗

1. スタイルレビューまで全部任せる

AI に細かい style comment を出させると、レビュー体験は悪くなります。formatter や lint で落とせるものは CI に任せます。Codex review は、formatter が見ないリスクへ寄せます。

2. AGENTS.md が抽象的すぎる

「品質を高めてください」「安全性を確認してください」では弱いです。どの領域で何を P0/P1 とするかを書きます。

3. 自動レビューを広げすぎる

全 PR に入れてノイズが増えると、チームは Codex review を読まなくなります。最初は risky PR だけに寄せる方が定着します。

4. fix 依頼が広すぎる

fix all は避けます。1コメント、1論点、1差分に切った方がレビュー可能です。

5. 人間レビューを省略する

Codex が P0/P1 を出さなかったことは「安全」の証明ではありません。人間レビューの前段として使い、merge 判断は人間と CI に残します。

まとめ

Codex code review in GitHub は、PR レビューを丸ごと置き換える機能ではありません。実務では、人間レビュー前に危険な差分を浮かせる高シグナルな補助線として扱うのが一番強いです。

最初は @codex review を手動で呼び、指摘の質を見ながら AGENTS.md の Review guidelines を育てる。P0/P1 の意味を固定し、style comment を避け、必要なときだけ狭い @codex fix を投げる。

この順番なら、Codex review は通知を増やすだけの AI 機能ではなく、PR merge 前の安全運用を支えるレビュー層になります。