codex-review

Codex CLI によるクロスモデルコードレビュー

codex バイナリを直接使ったクロスモデル検証です。Claude がコードを書き、Codex がレビューします。アーキテクチャもトレーニングデータの分布も異なるため、自己承認バイアスがありません。

核心となる考え方： 単一モデルによる自己レビューには、系統的なバイアスがあります。レビュアーは作成者とは根本的に異なる盲点を持つため、クロスモデルレビューでは異なる種類のバグを検出できます。

独立性の主張は正直に範囲を定めてください： 別のモデルを使えば自己レビューのバイアスは解消できますが、それ以外は解消できません。トレーニングデータに共通する古さの問題は検出できません（バージョン、SOTA、エコシステムに関する主張は、モデルが何台一致しても、最新の一次情報源で確認する必要があります）。また、依頼内容の解釈違いも引き継がれます（ユーザーの依頼をそのままプロンプトに含め、レビュアーに解釈への異議を求めてください）。

このスキルの読み方： 以下のパターンや判断表はガイドラインです。状況に合うものを選び、必要に応じて組み合わせてください。⚠️ のマークが付いたルールは別格です。手続き上の形式ではなく、実際の codex CLI の動作を示しています。スコープフラグを省略すると実際に呼び出しがハングし、tail にパイプすると実際に出力が失われます。⚠️ のルールはワークフローについての意見ではなく、ツールの仕様として扱ってください。

前提条件： codex CLI がインストールされ、認証済みである必要があります。codex --version で確認してください。ユーザーのデフォルト設定は ~/.codex/config.toml にあります。これを尊重してください。

Pi での使用： pi-nova xreview 拡張機能がインストールされている場合は、/xreview を優先してください。これは標準入力を閉じて codex exec --sandbox read-only を実行し、構造化された判定／指摘事項／修正キューを返します。Pi から手動で bash を呼び出す場合も、以下の⚠️ルールに従ってください。

方向： Claude → Codex のみです。双方向のスキル（Codex → Claude も扱い、yield_time_ms や可変長フラグに関する claude -p の注意点も含みます）を使う場合は、代わりに /hyperskills:cross-model-review を使用してください。

---

⚠️ 絶対に守るルール：codex review には必ずスコープフラグを渡す

スコープを指定しない codex review は、失敗の最大の原因です。ハングしたり、100KB を超える巨大な出力を生成したりします。必ずスコープフラグを1つだけ指定してください：

レビュー対象	コマンド
main 以降のブランチ	codex review --base main
単一のコミット	codex review --commit <SHA>
作業ツリー（ステージング前）	codex review --uncommitted

スコープを指定した codex review では、末尾の [PROMPT] 引数としてカスタム指示も指定できます（2026年7月時点：codex review --base main "focus on error handling"）。そのため、対象を絞ったレビューでも構造化レビューの動作が維持されます。成果物が差分ではない場合（仕様書、バージョン管理外の単一ファイル、自由形式の調査など）に限り、codex exec "PROMPT" を使用してください。スコープを指定しない codex review は決して使わないでください。

codex review の出力が約100KBを超える場合、差分が大きすぎて一度にレビューできません。コミットごとに分割するか、より狭いプロンプト（「エラーハンドリングのみレビュー」など）を指定して codex exec を使用してください。大規模な codex exec のトランスクリプトは別の問題です。「レビューがハングする場合」を参照してください。

レビュー範囲を固定し、対象を凍結してください。 変更が残っているブランチや複数の作業が並行しているブランチでは、ファイル一覧を明示するか、正確な差分を codex exec にパイプしてください。範囲を固定しないレビュアーは、差分をあちこち見て回ります。レビュー中に対象コードを編集しないでください。待ち時間には、レビュー対象の差分に影響しない読み取り専用の作業をしてください。判定後に編集すると、その判定は無効になります。差分だけを再レビューし、問題が解消されたことを確実に確認してください。

---

⚠️ 出力をファイルに保存する：tail にパイプしない

レビューを | tail -N にパイプしてはいけません。失敗する理由は3つあります。

1. パイプは EOF までバッファーします。 tail は出力を生成する前にストリーム全体を読み込むため、codex が終了するかタイムアウトするまで、レビュー中の進捗はエージェントにまったく表示されません。
2. レビューでは判定が末尾ではなく先頭付近に表示されます。 指摘事項は重大度順（BLOCKER が最初）に並ぶため、tail -300 ではまさに確認したい部分が切り落とされます。
3. ファイルなら、人が進捗をリアルタイムで確認できます。 別のターミナルで tail -f /tmp/review.txt を実行すれば、エージェントの呼び出しとは完全に独立して、レビューがリアルタイムで表示されます。

適切な方法： 他と重複しないファイル名を選び、リダイレクトしてから読み戻します。

# mktemp so parallel/repeat reviews don't clobber each other.
# Bake the scope into the slug so it's self-describing under tail -f.
out=$(mktemp -t codex-review-pre-pr.XXXXXX) && echo "$out"

codex review --base main > "$out" 2>&1
codex exec --sandbox read-only "PROMPT" > "$out" 2>&1

mktemp がすぐ使えない場合は、out=/tmp/codex-review-$$-$(date +%s).txt とします。人が tail -f で確認する場所が分かるよう、リダイレクトの前にパスを表示してください。終了後にファイルを Read（または cat）します。このファイルはターンをまたいで保持されるため、再実行せずに読み直してください。

関連するツールの注意点：--sandbox read-only では、Codex はプロンプトで要求されたレポートファイルを黙って書き込めなくなります。リダイレクトまたは --output-last-message で取得し、「X にレポートを書いて」と指示してはいけません。

---

レビューが停止した場合

スコープを正しく設定したレビューでも停止することがあります。これは現場で最もよく起きる運用上の失敗です。出力ファイルは稼働状況を確認するための手段です。経過時間ではなく、出力の増加とプロセスの状態で判断してください。出力が増え続けているなら、遅いことは品質の高さを示す場合があります。大規模な対象に対する素早いお墨付きは疑うべきです。

シグナル	対応
出力ファイルが増加している	待ち続けてください。処理は進行中です
ファイルは空、プロセスツリーは生存	もう1区間待ってから、変数を切り分けてください（2026年7月時点では、停止した MCP サーバーと起動フックが主な原因です）
ファイルは空、プロセスが停止	そのプロセスツリーだけを終了し、自由度を減らして1回だけ再試行します。標準入力で差分をそのまま渡す、対象ファイルを絞る、effort を下げる。同じ質問で、ペイロードを減らしてください
再試行も停止する	諦める条件をあらかじめ決め、レビューが失敗したことを正直に記録してください

レビュー担当のプロセスが動作中なのに、その横で重複するプロセスを起動してはいけません。実行中のものを終了してください。また、サイズだけで失敗と判断してはいけません。1MB を超える codex exec のトランスクリプトは、判定が末尾にある、深く掘り下げた調査の成功例かもしれません。トレース全体を出力するのではなく、判定と重大度のマーカーを grep してください。本当の失敗は、出力が増えないこと、または出力が増えても判定に近づかないことです。

---

Codex を呼び出す2つの方法

モード	コマンド	最適な用途
codex review	優先順位付きの指摘を含む、構造化された差分レビュー	PR 前のレビュー、コミットのレビュー、WIP チェック
codex exec	プロンプトを完全に制御できる、自由形式の非対話型の詳細調査	セキュリティ監査、アーキテクチャ、対象を絞った調査、仕様書

スコープ指定フラグ（codex review のみ）

フラグ	用途
--base <BRANCH>	ベースブランチとの差分
--commit <SHA>	特定のコミットをレビュー
--uncommitted	作業ツリーの変更をレビュー

サンドボックスと使いやすさのフラグ（両モード共通）

フラグ	使用する場面
--sandbox read-only	レビュー作業のデフォルト。書き込みは行いません
--sandbox workspace-write	レビューと、提案された修正の適用
--full-auto	--ask-for-approval never --sandbox workspace-write のエイリアス
--dangerously-bypass-approvals-and-sandbox	最終手段。ユーザーから明示的に依頼された場合のみ
-C <DIR> / --cd <DIR>	cd せずに別のワークツリーで実行
--skip-git-repo-check	/tmp または Git の信頼チェックに引っかかるリポジトリ以外のディレクトリから実行する場合
--add-dir <DIR>	別のパスへの読み取りアクセスを追加
--ephemeral	1 回限りのセッション。状態は保持されません
--json / --output-last-message <FILE>	構造化された出力をファイルに保存
-c model_reasoning_effort="xhigh"	仕様書／RFC のレビューのみ（「Effort Policy」を参照）

Effort のオーバーライドポリシー

レビュー対象	Effort フラグ
コード（コミット／差分／PR／WIP）	なし。~/.codex/config.toml の設定に従います
仕様書／RFC／設計ドキュメント	-c model_reasoning_effort="xhigh"

仕様書は差分よりもリスクが高く、微妙なアーキテクチャ上の誤りが、その後の実装全体に波及します。コードの差分は範囲が小さいため、ユーザーが設定した Effort で十分です。

Effort よりも先にスコープを定めてください。 Effort はスコープの内容を増幅します。xhigh のオーバーライドは、すでに範囲を絞った仕様書レビューに適用してください。範囲を絞らずに xhigh で「すべて検証」するよう指示すると、掘り下げるのではなく発散します（実例：トランスクリプトが 8 万行に達しても、結論が出ませんでした）。レビューを確実に収束させるには、スコープを絞り、Effort を上げるのではなく下げることも検討し、プロンプトに明示的な収束の予算を設けてください（「要点に絞り、結論を出してください」）。

モデル自体をオーバーライドするために --model、-m、-c model= を指定してはいけません。ユーザー設定が優先されます。このゲートの価値は、単発の API 呼び出しではなく、リポジトリにアクセスできる完全なエージェント型 Codex にあります。

---

レビューパターン

パターン 1：PR 前のフルレビュー（デフォルト）

PR を作成する前に行う標準的なレビューです。重要な変更にはすべて使用してください。

Step 1, structured review (catches correctness + general issues):
  codex review --base main

Step 2, security deep-dive (if code touches auth, input handling, or APIs):
  codex exec "<security prompt from references/prompts.md>"

Step 3, fix findings, then re-review carrying the ledger (see Pattern 5):
  codex review --base main

同じ形式は、コミットごと（codex review --commit <SHA>）や、開発途中の作業ツリー（codex review --uncommitted）にも使えます。

パターン 2：焦点を絞った調査

特定の懸念事項（エラー処理、並行処理、データフローなど）を重点的に掘り下げます。

codex exec --sandbox read-only \
  "You are a senior <DOMAIN> engineer. Analyze <CONCERN> in the changes
   between main and HEAD. For each issue: cite file and line, explain the
   risk, suggest a concrete fix. Confidence threshold: 0.7."

パターン 3：仕様書／RFC のレビュー

コードを書く前に、文章（Markdown の設計ドキュメント）をレビューします。

codex exec -c model_reasoning_effort="xhigh" --sandbox read-only \
  "You are a senior staff engineer doing a candid pre-implementation review of
   <PATH>. The author wants sharp, unsentimental analysis. For each finding:
   severity (BLOCKER / HIGH / MEDIUM / LOW), confidence (>= 0.7 only), location
   (file path + section heading), the issue, a concrete fix.
   End with a one-paragraph go/no-go verdict."

パターン 4：単一ファイル／対象パスのレビュー

差分全体ではなく、1 つのファイルまたはディレクトリをレビューします。

codex exec --sandbox read-only \
  "Review only <PATH> for <CONCERN>. Skip style and ergonomics.
   Return PASS if no real issues; otherwise concise FAIL findings with
   file:line evidence."

パターン 5：Ralph ループ（実装 → レビュー → 修正）

反復による品質の担保です。第 1 ラウンドは、広範囲を対象とし、厳しい視点でレビューします。以降の各ラウンドでは、過去のラウンドでの指摘を原文のまま列挙し、主張された修正内容とともに記録して、レビュー担当者に（a）各修正を証拠を添えて検証する、（b）修正によって生じたバグを探す、（c）決着済みのトレードオフを蒸し返さない、ように依頼します。ラウンドごとに対象範囲を狭めます。広範囲 → ブロッカーのみ → 1 行の契約（「PASS / NEEDS_CHANGES：<一文>」）による収束確認、という流れです。仕様の場合は、成果物の「Review History」セクションに各ラウンドを記録します。ループの状態はチャットのやり取りではなく、成果物に保持します。再レビュー用テンプレートは references/prompts.md にあります。

予算は回数ではなく、収束によって決まります。 各ラウンドで新たに確認された指摘が見つかるか、修正が検証される間は反復を続けます。ラウンド間で結論が行き来したり、同じ議論が蒸し返されたりしたら終了します。3 ラウンドは標準的な目安であり、上限ではありません。実際のバグを見つける第 5 ラウンドは問題ありませんが、第 3 ラウンドで第 1 ラウンドの議論を繰り返すのは、すでに予算超過です。この予算は、あなたが進行するループに適用されます。外部から届くボットや人間のフィードバックは、毎ラウンド新たにトリアージし、回数の上限を設けません。

修正ループは、対象範囲を段階的に絞り込む仕組みです。 ラウンド後にコードを変更する前に、ブロッカーとフォローアップをトリアージし、「テストで必要にならない限り、対象は 3 ファイルまで」のようにファイル数の上限を事前に宣言します。また、不在に関する指摘には、変更しない理由を文書化することも正当な対応として扱います。ブロッカーには、変更した行との因果関係が必要です。提案では、関連するリスクを扱ってもかまいません。既存の技術的負債はループ内で修正せず、フォローアップタスクにします。際限のないレビュー対応を続けると、ループは 120 ファイルの編集にまで膨れ上がります。

---

複数パス戦略

漠然とした 1 回のレビューよりも、焦点を絞った複数のパスでレビューするほうが、徹底したレビューにつながります。1 回のパスでは、複数の観点に注意が分散し、それぞれの指摘が浅くなります。各パスでは、特定のペルソナと対象領域を設定します。

パス	焦点	モード
正確性	バグ、ロジック、エッジケース、競合状態	codex review
セキュリティ	OWASP Top 10:2025、インジェクション、認証、シークレット	セキュリティ用プロンプトを使った codex exec
アーキテクチャ	結合度、抽象化、API の一貫性	アーキテクチャ用プロンプトを使った codex exec
パフォーマンス	O(n²)、N+1 クエリ、メモリリーク	パフォーマンス用プロンプトを使った codex exec

レビュー中に差分が変化している場合は、パスを順番に実行し、各パスの間に重大な指摘を修正します。成果物が凍結されている場合は、それぞれの観点に限定した並列パスを実行すると、重複のない補完的な指摘が得られ、より早く完了できます。各パスでは、担当する懸念事項を 1 つに絞り、明示的に対象外の事項を指定してください。

行数はあくまで大まかな目安です。数値ではなく、リスクと対象範囲に応じてパスを調整します。

変更規模	戦略
50 行未満、単一の懸念事項	単一の codex review
50～300 行、機能開発	codex review ＋ セキュリティパス
300 行以上、またはアーキテクチャの変更	4 パスすべて
セキュリティ上重要（認証、決済、暗号）	常にセキュリティパスを含める

指摘への対応

レビュアーの出力は入力であり、命令ではありません。変更を加える前に、コード、Git の履歴、実際のデータなど、信頼できる情報と照合して各指摘を再検証してください。対応は必ず次の 3 つに分類して報告します。すぐに修正する／理由を明示して意図的に維持する／検証できないため、人間に確認を求める。「検証した結果、コード変更なし」も正当な結論です。あるセッションでは、4 件中 3 件の指摘が誤りだと判明し、何も変更しませんでした。誤った指摘は、根拠を示して反論してください。黙って無視してはいけません。独立して依頼を受けた 2 人のレビュアーが同じバグを指摘した場合は、確定した問題として扱います。

まず確認すべき、Codex によく見られる見落とし：

失敗の種類	確認事項
時間的な範囲	指摘が対象とするコミット時点の状態をレビューしましたか？
類似名の取り違え	引用された対象は、実際に変更されたものですか？
架空のフラグ／API	提案されたフラグや関数は実在しますか？--help を実行してください
修正時点ですでに解消	レビュー時点では妥当だった指摘が、現在は解消されていますか？

両方向からフィードバックを反映してください。不具合の種類を修正したら、その内容をリポジトリの標準レビュープロンプトまたは CI ゲートに反映し、次のレビュアーにも引き継がれるようにします。レビュアーが同じ幻の問題を繰り返しでっち上げる場合は、レビュアーが取り込む情報を修正してください。繰り返し読み込まれている古いドキュメントを取り除きます。また、記憶にある過去の注意点を次のレビューにあらかじめ渡してください。鋭い仮説リストの作成に役立ちます。

---

プロンプト設計のヒューリスティック

レビューのシグナル品質を確実に高める、ひと目ではわかりにくい工夫：

1. 対象外を指定します。「フォーマット、命名スタイル、軽微なドキュメントの不足は対象外にする」と伝えると、些細な議論を避けられます
2. 確信度スコアを求め、 0.7 以上の指摘だけに対応します
3. **1 回のレビューにつき 1 つの領域に絞ります。**セキュリティのみ、アーキテクチャのみ、など
4. 明確な判定を求めます。「判定：パッチは正しい／誤っている」または「進める／進めない」

完全なブリーフの構成要素（依頼文そのもの、要となる主張、検証済みと仮定する根拠、迎合防止、記憶を使わない旨の一文）と、そのまま使えるテンプレートは references/prompts.md にあります。

---

アンチパターン

アンチパターン	失敗する理由	対処方法
スコープフラグなしの codex review	ハングするか、大量の出力を生成します	スコープフラグは必ず1つ指定します — ⚠️ スコープルールを参照
レビュー出力を tail -N にパイプする	EOF までバッファーされ、判定が途切れます	ファイルにリダイレクトします — ⚠️ 出力取得ルールを参照
timeout 30 codex review	レビューには正当に30秒〜5分かかることがあります	タイムアウトを設定しないか、最低でも timeout 300 を指定します
トランスクリプトのサイズを失敗の兆候と見なす	1MB以上の codex exec トランスクリプトでも、深い調査が成功している場合があります	成長と判定への収束で判断します（レビューがハングする場合）
「このコードをレビューして」（具体性なし）	曖昧で、些細な議論を招きます	ペルソナを設定した、対象領域を明確にしたプロンプトを使用します
すべてを1回で済ませる	コンテキストが分散し、どの観点も浅くなります	1回につき1つの懸念事項に絞り、複数回に分けて実施します
自己レビュー（ClaudeがClaudeのコードをレビューする）	体系的な偏りが生じ、モデルが自分自身のパターンを承認します	モデルを分けます：Claudeが作成し、Codexがレビューします
信頼度のしきい値を設けない	ノイズが重要な情報を埋もれさせ、信頼度0.3の指摘に時間を浪費します	信頼度が0.7以上の場合のみ対応します
レビューでスタイルを指摘する	LLMは些細な議論をしがちです	「書式、命名、軽微なドキュメントは対象外」と指定します
ラウンドをまたいで決着済みの指摘を蒸し返す	ラウンド数に関係なく、予算を超過します	予算は収束で決まります — 回数ではなく、ラウンド間で結論が揺れ始めたら停止します
プロジェクトのコンテキストなしでレビューする	コードベースに結びつかない一般論になります	リポジトリのルートから実行します
レビュアーによる幻覚が繰り返し発生する	多くの場合、レビュアーが取り込むドキュメントに原因があります	古くなったドキュメントを修正し、ラウンドごとに再議論するのは避けます
codex を MCP でラップする	CLI バイナリの呼び出しに不要な間接層が加わります	Bash から codex を直接呼び出します
--model / -m / -c model= をハードコードする	ユーザー設定を上書きし、古いモデル名が残ります	~/.codex/config.toml の設定に従います
通常のコードレビューで推論の労力を上書きする	トークンを浪費し、ユーザーのデフォルト設定を無視します	-c model_reasoning_effort="xhigh" は仕様レビュー専用です
純粋なレビューで --full-auto を使う	レビューに不要な書き込みアクセス権を付与します	レビューには --sandbox read-only を使用し、修正を適用する場合のみ --full-auto を使用します

---

Codexを実行できない場合

このゲートは代替できません。実行できない場合（クォータ制限、CLIの停止、MCPの障害）は、保証が弱くなることを明示したうえで、段階的に代替手段へ移行してください。新しいコンテキストでの同一モデルによるレビューが最低限の基準であり、異なるモデルファミリーによるレビューは上位の選択肢です。代替したことをまとめとPR本文で開示し、続行するかどうかは人間が判断できるようにしてください。レビュー経路が遮断されている場合、PASSを出してはいけません。

---

このスキルが対象としないこと

• 人間によるレビューの代わりではありません。 複数のモデルによるレビューでバグは見つけられますが、製品の方向性や UX は評価できません。
• リンターではありません。 フォーマットやスタイルの確認に Codex のレビューを使わないでください。
• 情報の古さを確認するものではありません。 バージョンや SOTA に関する主張は、モデルがいくつ一致していても、最新の一次情報源で確認する必要があります。
• 完全無欠ではありません。 誤検出率は 5～15％が通常です。指摘事項は選別してください（「指摘事項の利用」を参照）。
• 自己承認のためのものではありません。 目的は、異なるモデルによる検証です。Claude のコードを Claude でレビューしないでください。

参考資料

すぐに使えるプロンプトのテンプレートについては、references/prompts.md を参照してください。