name: codex-review description: Codex CLI（read-only）を用いて、レビュー→Claude Code修正→再レビュー（ok: true まで）を反復し収束させるレビューゲート。仕様書/SPEC/PRD/要件定義/設計、実装計画（PLANS.md等）の作成・更新直後、major step（>=5 files / 新規モジュール / 公開API / infra・config変更）完了後、および git commit / PR / merge / release 前に使用する。キーワード: Codexレビュー, codex review, レビューゲート.

Codex 反復レビュー

フロー

規模判定 → Codex 規模別レビュー → Claude Code 修正 → 再レビュー（ok: trueまで反復）

[規模判定] → small:  diff ──────────────────→ [修正ループ]
          → medium: arch → diff ───────────→ [修正ループ]
          → large:  arch → diff並列 → cross-check → [修正ループ]

• Codex: read-only でレビュー（監査役）
• Claude Code: 修正担当

規模判定

git diff <diff_range> --stat
git diff <diff_range> --name-status --find-renames

diff_range 省略時: HEAD を使用し、作業ツリーの未コミット変更（作業ツリー vs HEAD）を対象とする（staged/unstaged の区別はしない）。

large 時:

• 並列: 3-5 サブエージェント、各サブは担当ファイルのみ
• 分割: 1 呼び出しあたり最大 5 ファイル/300 行、ディレクトリ単位で分割（cross-cutting concerns は cross-check で検出）
• 統合はメイン（Claude Code）で実施

修正ループ

ok: falseの場合、max_iters回まで反復:

1. issues解析 → 修正計画
2. Claude Code が修正（最小差分のみ、仕様変更は未解決 issue に）
3. テスト/リンタ実行（可能なら）
4. Codex に再レビュー依頼

停止条件: ok: true / max_iters到達 / テスト 2 回連続失敗

Codex 実行

codex exec --sandbox read-only "<PROMPT>"

• PROMPT には（スキーマ含む）最終プロンプトを渡す
• 主要な関連ファイルパスは Claude Code が明示
• レビュー完了待ち（必須）: codex exec 実行中は次の工程に進まない（別タスク開始・推測での中断禁止）
  • 定期確認: 60 秒ごとに最大 20 回、poll i/20 と経過時間のみをログし、追加作業はしない
  • 20 回到達後も未完了なら: 「タイムアウト」扱いでエラー時ルールへ
  • 長時間無出力になり得るため、必要に応じて codex exec をバックグラウンド実行し、プロセス生存確認を poll として扱ってよい。

Codex 出力スキーマ

Codex に JSON1 つのみ出力させる。Claude Code はプロンプト末尾に以下のスキーマとフィールド説明を添付。

{
  "ok": true,
  "phase": "arch|diff|cross-check",
  "summary": "レビューの要約",
  "issues": [
    {
      "severity": "blocking",
      "category": "security",
      "file": "src/auth.py",
      "lines": "42-45",
      "problem": "問題の説明",
      "recommendation": "修正案"
    }
  ],
  "notes_for_next_review": "メモ"
}

フィールド説明:

• ok: blocking な issue が 0 件なら true、1 件以上なら false
• severity: 2 段階
  • blocking: 修正必須。1 件でもあればok: false
  • advisory: 推奨・警告。ok: trueでも出力可、レポートに記載のみ
• category: correctness / security / perf / maintainability / testing / style
• notes_for_next_review: Codex が残すメモ。再レビュー時に Claude Code がプロンプトに含める

プロンプトテンプレート

arch

以下の変更のアーキテクチャ整合性をレビューせよ。出力はJSON1つのみ。スキーマは末尾参照。

これはレビューゲートとして実行されている。blocking が1件でもあれば ok: false とし、修正→再レビューで収束させる前提で指摘せよ。

diff_range: {diff_range}
観点: 依存関係、責務分割、破壊的変更、セキュリティ設計
前回メモ: {notes_for_next_review}

diff

以下の変更をレビューせよ。出力はJSON1つのみ。スキーマは末尾参照。

これはレビューゲートとして実行されている。blocking が1件でもあれば ok: false とし、修正→再レビューで収束させる前提で指摘せよ。

diff_range: {diff_range}
対象: {target_files}
観点: {review_focus}
前回メモ: {notes_for_next_review}

cross-check

並列レビュー結果を統合し横断レビューせよ。出力はJSON1つのみ。スキーマは末尾参照。

これはレビューゲートとして実行されている。横断的な blocking（例: interface不整合、認可漏れ、API互換破壊）があれば ok: false とせよ。

全体stat: {stat_output}
各グループ結果: {group_jsons}
観点: interface整合、error handling一貫性、認可、API互換、テスト網羅

エラー時の共通ルール

Codex exec 失敗時（タイムアウト・API 障害・その他）:

1. 1 回リトライ（タイムアウトはファイル数を半分に分割して）
2. 再失敗 → 該当フェーズをスキップし、理由をレポートに記録
3. arch スキップ時は diff のみで続行、diff スキップ時はそのファイル群を「未レビュー」としてレポート

パラメータ

終了レポート例

## Codexレビュー結果
- 規模: large（12ファイル、620行）
- 並列: 3サブエージェント、4グループ
- 反復: 2/5 / ステータス: ✅ ok

### 修正履歴
- auth.py: 認可チェック追加

### Advisory（参考）
- main.py: 関数名がやや冗長、リファクタ推奨

### 未レビュー（エラー時のみ）
- utils/legacy.py: Codexタイムアウト、手動確認推奨

### 未解決（あれば）
- main.py: 内容、リスク、推奨アクション