codex-plan-review

Codex-Plan-Review — 敵対的な計画レビューの反復

2つのモデル、1つの計画、制限付きの議論です。Claude が構築とオーケストレーションを担います。Codex は読み取り専用の批評役で、リポジトリと計画は読めますが、ファイルには一切触れられません。両者は PLAN_FILE と、ラウンドをまたいで保持される Codex セッションのみを介して厳密にやり取りします。人間が参加するのは、キックオフと最終承認のちょうど2回です。

これは慎重に使うべき、重要度の高いツールです。認証、データモデル、並行処理、マイグレーション、決済など、間違えるとコストが高くつく作業に使ってください。明白で低コストな作業では使わないでください。

前提条件（一度だけ、すぐに確認）

• Codex CLI がインストールされ、最新であること：codex --version（≥ 0.130 が必要です。デフォルトの gpt-5.5 モデルは古い CLI ではエラーになります）。
• Codex の認証が済んでいること：事前に codex login を実行してください（ChatGPT アカウントで問題ありません）。実行時に認証エラーやモデルエラーが返された場合は、ユーザーに伝えてください。黙って再試行しないでください。
• ユーザーから求められない限り、-m を固定しないでください。ユーザーの ~/.codex/config.toml に設定されたデフォルトモデルが使われます。ChatGPT アカウント認証では、gpt-5.x-codex 系モデルを固定すると失敗します。
• ラウンド1の前に、アクティブなモデルを伝えてください。~/.codex/config.toml の model 行を読み取り（記載がない場合は「CLI default」）、解決済みの調整可能な値とともに提示します。ユーザーが異議を唱えた場合は、ラウンドを消費する前に停止してください。
• 2つのコマンドではサンドボックスフラグが異なります。 codex exec は -s read-only を受け付けます。codex exec resume は受け付けず、-s を指定すると「unexpected argument」として拒否します。resume では、必ず -c sandbox_mode="read-only" を使って読み取り専用にしてください。config.toml のデフォルトが sandbox_mode を danger-full-access（および approval_policy="never"）にしている可能性があり、その場合、Codex が反復の途中でファイルを書き込めてしまうためです。このスキルで最も重要な安全上の注意点です。2026-06-04 にエンドツーエンドで検証済みです。

調整可能な変数（スキルの引数から読み取り、なければデフォルトを使用）

Var	デフォルト	意味
MAX_ROUNDS	5	レビューラウンドの上限です。反復は必ずここで終了します。
PLAN_FILE	PLAN.md	変化していく計画を保存する場所です。デフォルトはリポジトリのルートです。計画の配置規約があるリポジトリでは、作業ごとのパスを指定してください。
LOG_FILE	PLAN-REVIEW-LOG.md	議論の追記専用トランスクリプトです（各ラウンドの批評と変更内容をすべて記録します）。成果物です。

ユーザーが rounds=3 のような引数でスキルを呼び出した場合は、その値を MAX_ROUNDS に使用します。開始前に、解決済みの値をユーザーに伝えてください。

何かを書き込んだりレビューしたりする前に、PLAN_FILE / LOG_FILE を解決し、両方をログのヘッダーに記録してください。また、以下のすべてのプロンプトで、プレースホルダーを解決済みのパスに置き換えてください。<PLAN_FILE> のようなプレースホルダーは必ず置換してください。文字列のまま送ってはいけません。オーバーライドを指定したのに、レビュアー向けプロンプトに PLAN.md がそのまま残っていると、Codex はそのパスにある古いファイルをレビューし、誤った文書に対して VERDICT: APPROVED を返す可能性があります。

フロー

ステップ0 — キックオフ（人間のゲート #1）

呼び出し自体がキックオフです。何を計画するのか、範囲を1行で確認してください。ユーザーがタスクを提示していない場合は、質問を1つしてください。その後は続行し、ラウンドごとに承認を求めないでください。承認は最後に行います。

ステップ1 — Claude が計画

実際に計画してください。関連コードを読み、アプローチを検討し、判断事項やトレードオフを明らかにします。その後、次の構成で計画を PLAN_FILE に書き込みます。

# Plan: <task>
_Round 0 — initial draft by Claude_

## Goal
<one paragraph>

## Approach
<numbered steps, concrete>

## Key decisions & tradeoffs
<the contestable choices — name them explicitly so Codex has something to bite>

## Risks / open questions
<what you're unsure about>

## Out of scope
<bounds>

LOG_FILE を初期化します。

# Plan Review Log: <task>
Started <stamp the user's local time if known, else "session start">. MAX_ROUNDS=<n>.

計画をユーザーにそのまま提示し、敵対的レビューのため Codex に送ることを伝えてください。

Step 2 — ループ

ROUND（1から開始）とTHREAD_ID（round 1の応答が返るまでは空）を維持します。

各ラウンドでCodexに送るレビュー用プロンプト（タスク行を調整します）：

あなたは実装計画の敵対的レビュー担当者です。懐疑的かつ具体的にレビューしてください。あなたの役目は同意することではなく、問題を見つけることです。<PLAN_FILE>にある計画（および必要なリポジトリファイル。読み取り専用です）を読み、具体的な欠陥を特定してください。セキュリティ上の穴、競合状態、考慮されていないエッジケース、スキーマの矛盾、誤った前提、可観測性の不足、よりシンプルな代替案などです。それぞれについて、1行で修正案を示してください。ファイルは変更しないでください。返信の最後に、計画が実装できるほど十分に妥当であればVERDICT: APPROVED、重大な問題が残っていればVERDICT: REVISEという行を、正確に1行だけ記載してください。

Round 1（セッションを作成します。thread_idを取得してください）：

codex exec -s read-only --json \
  -o /tmp/codex-verdict.txt \
  "$(cat REVIEW_PROMPT)" \
  < /dev/null 2>/dev/null | grep '"type":"thread.started"'

{"type":"thread.started","thread_id":"..."}の行からthread_idを解析し、それをTHREAD_IDに設定します。批評文は/tmp/codex-verdict.txt（Codexの最後のメッセージ）に出力されます。そのファイルを読みます。

注：環境によってはstderrに見た目だけのMCP／認証関連のノイズが出るため、2>/dev/nullを意図的に指定しています。判定ファイルが存在し、thread.started行があることを確認して成功を判定してください。どちらも見つからない場合は実行失敗（認証／モデル）です。停止してユーザーに伝えてください。

< /dev/nullは必須です： codex execはプロンプト引数に加えてstdinも読み取るため、非対話型の実行環境（Claude CodeのBashツール、CI、TTYでないパイプラインなど）では、stdinのEOFを待って永久に停止します。これはCPU使用率がほぼ0％のまま静かにハングする状態です。このリダイレクトにより、すぐにEOFを渡せます。下記の再開呼び出しでも必須です。

タイムアウトガード： 今後ハングしても静かに停止し続けず、明確に失敗するよう、すべてのcodex exec／codex exec resumeに10分の上限を設定して実行してください。Claude CodeのBashツールでは、ツール呼び出しにtimeout: 600000を指定してください（既定の2分のツールタイムアウトは、実際のレビューには短すぎて実行途中で終了してしまいます）。通常のシェルでは、コマンドの先頭にtimeout 600（Linux／Git Bash）またはgtimeout 600（coreutilsを使うmacOS。標準のmacOSにはtimeoutがありません）を付けてください。上限に達した場合は実行失敗として扱い、むやみに再試行せず停止してユーザーに伝えてください。下記の再開呼び出しにも適用します。

Rounds 2..MAX（同じセッションを再開します。Codexは以前の批評を覚えているため、解決済みの点を再び議論しません）：

# NOTE: resume rejects -s. Force read-only via -c sandbox_mode, or Codex
# inherits config.toml (possibly danger-full-access) and could write files.
codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
  -o /tmp/codex-verdict.txt \
  "I revised the plan. Re-review <PLAN_FILE>. Same rules. End with VERDICT: APPROVED or VERDICT: REVISE." \
  < /dev/null 2>/dev/null >/dev/null

codex execとcodex exec resumeはいずれも--json（ストリームから出力し、初回にthread_idを解析）と-o/--output-last-message（判定を取得）に対応しています。

各ラウンドでCodexの応答が返った後：

1. /tmp/codex-verdict.txtを読みます。## Round <n> — Codexと批評全文をLOG_FILEに追記します。
2. 最終行を検索して判定トークンを確認します。
   • VERDICT: APPROVED → ループを抜け、Step 3（収束）に進みます。
   • VERDICT: REVISE → Claudeが批評を読み、実際に対応する価値があるものを判断します（最終判断はClaudeが行います。Codexは助言するだけで、命令はしません）。PLAN_FILEを修正します。変更した内容と却下した内容、その理由を### Claude's responseとしてLOG_FILEに追記します。ROUNDをインクリメントします。
3. ROUND > MAX_ROUNDSの場合 → Step 3に進みます（デッドロック）。

Step 3 — 解決（人間による承認ゲート #2）

APPROVEDの場合： 最終版のPLAN_FILE、議論を通じて改善された点を3つの箇条書きでまとめたもの、ラウンド数をユーザーに提示します。次のように尋ねます。「計画はCodexとのNラウンドを経て承認されました。今すぐ実装しますか？Codexに実装させる（/codex-build）、Claudeに実装させる、それともここで終了しますか？」 はいと回答された場合のみ、コードを書きます。ループ中にコードは書きません。 ユーザーがCodexを選んだ場合は、SPEC_FILE=<PLAN_FILE>と同じLOG_FILEを指定してcodex-buildスキルを呼び出します。役割が逆転し（Codexが記述し、Claudeが差分をレビューします）、実装ラウンドは同じログに追記されます。

APPROVEDにならないままMAX_ROUNDSに達した場合（デッドロック）： 収束したように装ってはいけません。未解決の意見の相違を明示して提示します。Codexが依然として指摘している各点と、Claudeの反対意見を列挙してください。判断は人間に委ねます。これは正当で有益な結果です。誤った「承認」より、意見の相違が明示されているほうが適切です。

厳守事項

• Codex は毎回読み取り専用です。最初の呼び出しでは -s read-only を、再開のたびに -c sandbox_mode="read-only" を指定してください（再開時に -s はありません）。書き込みは決して行いません。書き込み権限を与えたくなったら、そこでやめてください。それは別のスキルです。
• ループは必ず MAX_ROUNDS で終了します。無制限の再帰は禁止です。
• すべての REVISE で最終判断を下すのは Claude です。妥当な批評は反映し、妥当でないものは理由をログに記録したうえで却下してください。Codex の意見すべてに従ってはいけません（クロスモデルチェックの意味がなくなります）。一方で、意見を無視してもいけません（目的を果たせなくなります）。
• コードを扱うのは、2 回目の人間によるゲートを通過した後だけです。
• 納品物は LOG_FILE です。議論の経緯がすべてわかるように、完全な状態に保ってください。

やってはいけないこと

• 既存コードのレビューにこれを使わないでください。それには /codex-code-review または /codex:review を使ってください。
• ChatGPT アカウント認証で -codex モデルバリアントを指定しないでください。400 エラーになります。
• ログを省略しないでください。議論の記録は最も価値のある成果物です。
• Codex にファイルを編集させないでください。常に読み取り専用です。