最新バージョン：Codex の自動レビューおよび修正ループ機能が非常に便利

1---
2name: codex-review
3description: "Codex read-onlyレビューで、レビュー→修正→再レビューをok=trueまで反復するレビューゲート。使う場面: SPEC/PRD/設計/PLANS.mdの作成・更新後、中〜大規模実装やリファクタ完了後、5 files以上・新規モジュール・公開API・infra/config変更後、commit/PR/merge/release前。"
4---
5
6# Codex反復レビュー
7
8## 目的
9- blocking が1件でもあれば `ok=false` とするレビューゲートを維持する。
10- 実装者と監査者を分離し、修正と再レビューを反復して収束させる。
11- `ok=true` はレビューゲート通過のみを意味する。push、merge、release、タスク完了などの外部完了状態を代替しない。
12- レビュー結果と実際の完了証跡は分けて扱う。
13- 未レビュー範囲が残る場合は `ok=true` にしない。
14
15## 役割
16- **Implementer**: 修正担当（Codex または Claude Code）。
17- **Reviewer**: 監査担当（Codex read-only）。
18- Implementer と Reviewer は必ず分離する。
19
20## 実行優先順
211. JSON gate + Codexサブエージェント（既定）
222. JSON gate + read-only CLI review
233. `/review` フォールバック
24
25原則:
26- Codexアプリ/ローカルCodexで `spawn_agent` が使える場合、Reviewer は必ずサブエージェントとして起動する。
27- サブエージェントが利用不能な場合のみ、試行証跡を残して read-only CLI review にフォールバックする。
28- Reviewer は read-only 前提で、ファイル編集・コマンドによる変更・VCS操作を行わない。
29- Implementer と Reviewer の分離を守るため、Implementer 自身がレビュー結果を「自分で代替生成」して ok 判定しない。
30
31## フロー
32規模判定 → Codex規模別レビュー → Implementer修正 → 再レビュー（`ok: true`まで反復）
33
34 text
35[規模判定]
36small  -> diff(1 run) ------------------------------------> [修正ループ]
37medium -> arch -> diff(1 run) ----------------------------> [修正ループ]
38large  -> arch -> diff(run1..runN in parallel) -> cross-check -> [修正ループ]
39
40## 規模判定
41
42変更ファイル数、差分量、変更リスクを見て small / medium / large を決める。確認方法は repo の VCS と作業環境に合わせる。
43
44| 規模 | 基準 | 戦略 |
45|-----|------|-----|
46| small | ≤3ファイル、≤100行 | diff 1 run |
47| medium | 4-10ファイル、100-500行 | arch → diff 1 run |
48| large | >10ファイル、>500行 | arch → diff（複数run並列）→ cross-check |
49
50数値は目安。セキュリティ、公開API、infra/config、データ削除、課金、外部副作用を含む変更は規模を1段上げて扱う。
51
52large運用:
53- 同一依頼内で複数 review run が必要な場合にのみ、3〜5 subagent を目安に並列実行。
54- 分割はディレクトリ単位を優先し、cross-cutting concerns は cross-check で検出。
55- 全体を `ok=true` にできるのは、全 run が `ok=true` で、未レビュー範囲と Reviewer 不成立がない場合だけ。
56- 各 Reviewer JSON は担当範囲ごとに並べ、blocking と未レビュー範囲をそのまま終了レポートに出す。
57- Implementer は修正計画と修正を担当するが、blocking を独断で棄却して `ok=true` にしない。棄却が必要な場合は、仕様根拠を示して Reviewer に再レビューさせる。
58
59## JSON gate
60
61### A-1 入力準備
62- 変更概要（ファイル数、差分量、追加/削除/rename の有無）
63- レビュー対象の patch / diff、または同等の変更内容
64- 主要関連ファイルパス
65- 前回レビューから引き継ぐ `notes_for_next_review`
66
67### A-2 Reviewer 実行
68- サブエージェント既定: `spawn_agent` で read-only Reviewer を起動し、主要関連ファイルパスを明示して依頼。
69- サブエージェント依頼文には「read-onlyレビュー」「編集禁止」「JSON 1オブジェクトのみ」「A-5 出力形式準拠」「blocking が1件でもあれば `ok: false`」を必ず含める。
70- フォールバック: サブエージェント試行の証跡がある場合だけ、read-only の CLI review に A-4 の本文と A-5 出力形式を渡す。
71- 禁止: `spawn_agent` が使えるか確認せず、またはサブエージェントを試行せずに、最初から CLI review を実行すること。
72
73### A-3 完了待ちルール
74- レビュー完了前に次工程へ進まない。
75- タイムアウト、未完了、未レビュー範囲が1件でも残る場合は終了レポートに記録し、最終判定を `ok=false` とする。未レビューは advisory ではなく gate-blocking として扱う。
76
77### A-4 Reviewer prompt contract
78- 目的: merge / release / handoff 前に P0/P1 相当の blocking risk を検出する。観点例は correctness、security、compatibility、testing などで、これに限定しない。軽微な style は扱わない。
79- 探索範囲: 与えられた diff と明示された関連ファイルを優先する。diff だけで判断できない場合は、呼び出し元、型定義、設定、テストを read-only で確認してよい。推測で埋めず、不足は `lines: "?"` と `notes_for_next_review` に残す。
80- 出力は JSON 1つのみ（A-5 出力形式準拠）。blocking が1件でもあれば `ok: false`。
81- 指摘には、根拠、該当箇所、影響、修正案、修正後の確認方法を含める。根拠不足なら blocking と断定せず、追加確認として記録する。
82- blocking / advisory / 追加確認を分類したら完了する。表現改善だけのために追加探索しない。
83
84Phase focus:
85- `arch`: 依存関係、責務分割、破壊的変更、セキュリティ設計
86- `diff`: 対象diff、関連ファイル、重点観点、前回メモ
87- `cross-check`: interface整合、error handling、認可、API互換、テスト網羅
88
89### A-5 Codex出力形式
90
91json
92{
93  "ok": false,
94  "phase": "arch|diff|cross-check",
95  "summary": "レビューの要約",
96  "issues": [
97    {
98      "severity": "blocking|advisory",
99      "category": "correctness|security|perf|compatibility|maintainability|testing|style",
100      "file": "src/auth.py",
101      "lines": "42-45",
102      "problem": "問題の説明",
103      "recommendation": "修正案",
104      "verification": "修正後の確認方法"
105    }
106  ],
107  "notes_for_next_review": "メモ"
108}
109
110## 修正ループ
111`ok=false` の場合、`max_iters` 回まで反復。既定は `max_iters=5`。
112
1131. `issues` を解析して修正計画を作る。
1142. Implementer が最小差分で修正する（仕様変更は未解決 issue として残す）。
1153. 変更リスクに応じたテスト、リンタ、または代替検証を実行する。未実行の場合は理由を残し、critical path の未検証なら blocking とする。
1164. 同じモードで再レビューする。
117
118停止条件:
119- `ok=true`: gate pass
120- `max_iters` 到達: gate fail
121- テスト2回連続失敗: gate fail
122- Reviewer 不成立 / JSON parse失敗 / 出力形式不備 / 未レビュー範囲あり: gate fail
123
124gate fail で停止する場合は、残存 blocking、未レビュー、失敗検証を未解決として終了レポートに出す。
125
126## `/review` フォールバック
127JSON gate が失敗した場合のみ `/review` を使う。`/review` は発見補助であり、出力をそのまま `ok=true` の根拠にしない。
128
129## エラー時ルール
130- Reviewer が成立しない場合は、失敗理由、試行した reviewer path、未レビュー範囲を終了レポートへ記録する。
131- Reviewer の read-only 制約は緩和しない。
132- 入力過大やタイムアウト時は、範囲縮小または分割で再試行してよい。
133
134## 終了レポート例
135これは未レビューが残った場合の事例であり、網羅テンプレートではない。
136
137 text
138## Codexレビュー結果
139- mode: JSON gate or /review
140- review_scope: branch diff
141- 規模: large（12ファイル、620行）
142- 並列: 3サブエージェント
143- reviewer path: spawn_agent first
144- fallback evidence: none
145- 反復: 2/5
146- レビューゲート: ok=false
147- reason: unreviewed_scope is non-empty
148- 完了証跡: push/merge/release/タスク完了 等は別途確認
149
150### 修正履歴
151- auth.py: 認可チェック追加
152
153### 未レビュー
154- utils/legacy.py: Codexタイムアウト、再レビュー必須
155
156### 未解決
157- main.py: 内容、リスク、推奨アクション