codex-lead

name	codex-lead
version	2.2.0
description	タスク着手時に codex にリードしてもらうワークフロー。codex に設計/方針を主導（リード）させ、その方針に沿って Claude が実装し、実装後は codex でレビューする。余っている codex トークンを積極的に消費したい時に使う。「codexにリードしてもらって」「設計から codex に任せて」「タスクを codex 主導で」「codex-lead」「/codex-lead」で発火。

Codex Lead（codex に設計をリードさせる）

タスク着手時に codex に設計・方針をリード（主導）してもらい、その方針に沿って Claude が実装し、実装後に codex でレビューするワークフロー。

Claude が先に設計を決めるのではなく、最初に codex に「どう設計・実装すべきか」を主導させるのがこのスキルの本質。codex の方針を土台に実装を進める。

このスキルの狙い（codex を積極的に使う）

余っている codex トークンを使い切りたい時の選択肢として、codex を節約せず積極的に回すことを前提とする。

• codex の呼び出し回数を減らそうとしない。方針が固まるまでの往復、確認質問への応答、深掘りレビューは惜しまない
• 設計リードは 1 回で終わらせる必要はない。観点を変えて複数回投げたり、出てきた方針をさらに codex に詰めさせてもよい
• 「codex を呼ぶコストが高いから自前で済ませる」という判断はしない。判断に迷ったら codex に通す側に倒す
• ただしトークン消費が目的化して結論の出ない往復を延々と続けない。各ラウンドで設計が良くなっているかは確認する

引数

$ARGUMENTS は自由テキスト。これから着手するタスクの説明、関連ファイル、制約を含められる。

/codex-lead SyncEngine の競合解決を直したい
/codex-lead issues/042-sync-conflict.md に着手する
/codex-lead                → 直前の会話で決まっているタスクを対象にする

全体の流れ

[Phase 1] 設計リード   … codex に設計/方針を主導させる（合意できるまで往復）
   ↓ 合意 → 設計コントラクトを確定（設計が薄いタスクなら省略）
[Phase 2] 実装         … codex の方針（コントラクト）に沿って Claude が実装する
   ↓
[Phase 3] 実装レビュー  … 観点の異なる 2 パスで codex に通す（設計が薄ければ Pass A は省略）
   ├ Pass A 設計適合レビュー  … 設計コントラクトを重点観点に注入（high-altitude）
   └ Pass B 実装正当性レビュー … codex-review に委譲（line-level）
      ↓ 指摘がなくなるまでループ（再レビューは合計最大 3 回）

Claude が先に設計を固めて実装に走らないこと。 まず codex にリードさせ、その方針を土台にする。

設計レビューと実装レビューは観点が別物である（設計適合＝不変条件・責務分担・失敗モード吸収・設計意図からの逸脱という high-altitude な観点／実装正当性＝バグ・リグレッション・仕様逸脱・テスト不足という line-level な観点）。Phase 1 で codex 自身が立てた設計が Phase 3 のレビューまで貫通するよう、両観点を分けて検証する。

---

Phase 1: 設計リード（codex 主導）

1-1. codex に渡すタスクコンテキストをまとめる

codex がリードできるよう、タスクの前提を ./tmp に書き出す。codex は read-only でリポジトリを読めるが、何を達成したいか・既知の制約は明示する。

mkdir -p ./tmp
stamp="$(date +%Y%m%d-%H%M%S).$$"
task_out="./tmp/task-context.$stamp.md"        # 入力。合意後に使い捨て
lead_out="./tmp/design-lead.$stamp.md"          # codex の自由記述。蒸留後に使い捨て
contract_out="./tmp/design-contract.$stamp.md"  # 設計コントラクト。Phase 3 まで生存させる（1-5 で蒸留）

$task_out に以下を書く:

• やりたいこと: 解決したい不具合 / 追加したい機能
• 背景・制約: 守るべき不変条件、触れない領域、既存の方針
• 関連箇所: 起点になりそうなファイル/機能（分かる範囲で。codex が自分で探すので網羅でなくてよい）

$ARGUMENTS に issue ファイルや要件があればそれを使う。/tmp は使わず ./tmp を使う。

1-2. codex に設計をリードさせる

差分はまだないので codex exec -s read-only を使い、codex に設計・実装方針を主導させる。Claude の案をレビューさせるのではなく、codex 自身に方針を立てさせる。

# `</dev/null` 必須（理由は下記「ルール」参照）。codex 本体の stdin を即 EOF にする。
# ※ ここの `</dev/null` は codex 用。引数内の `<<'EOF'` は `cat` 用のヒアドキュメントで別物。
command codex exec -s read-only -m gpt-5.6-luna -c model_reasoning_effort="low" \
  --ephemeral -o "$lead_out" </dev/null \
  "$(cat <<'EOF'
このタスクの設計・実装方針をあなたにリードしてほしい。リポジトリの現状コードを読んだ上で、どう設計・実装すべきかの方針を主導して提案して。

## 出してほしいもの
- 推奨アプローチ（どのレイヤーに何を追加/変更するか、責務の分担）
- 守るべき不変条件（壊してはいけない契約）
- 失敗モード（順序競合・再送・二重実行・部分失敗・再起動）とその吸収方法
- 触るべきファイルと既存実装との整合（重複を作らないか）
- 想定される落とし穴・先に潰しておくべき設計判断
- 代替案があれば、採否の理由つきで

## 方針
- 場当たり的な条件分岐やワークアラウンドではなく、中長期的に改修を続けられる構造的な設計を優先する
- 症状への対処ではなく根本原因を潰す設計にする
- 不明点や前提が足りない箇所があれば、確認すべき質問として挙げる

## タスク

EOF
)
$(cat "$task_out")"

• command プレフィックス必須（zsh の関数オーバーライドを回避）
• 常に --ephemeral -o "$lead_out" を付与する（--full-auto は付けない。理由は「ルール」参照）
• コマンド実行ツールのタイムアウトは 900000ms（15分）に設定する

1-3. codex の方針を読み、ユーザーに提示する

1. まず "$lead_out" を読む。空なら codex コマンドの stdout / stderr を確認する。どちらにも方針が出力されていない（codex が非ゼロ終了・タイムアウトした場合を含む）なら、blind リトライはせず、stderr を添えて失敗をユーザーに報告し Phase 2 に進まない
2. codex が出した設計方針をそのままユーザーに提示する（要約しすぎない）
3. codex が確認質問を挙げていれば、ユーザーに確認する
4. Claude として懸念や補足があれば添える（ただし codex の方針を土台にする。勝手に別案へ差し替えない）
5. $lead_out / $contract_out の実パスをこの報告時に会話へ明記しておく。 Claude Code の Bash ツールはシェル変数を呼び出し間で保持しないため、Phase 3 では変数 $contract_out ではなく、ここで記録した正確なパスで参照する（最新 glob を無確認に拾うと別タスクの残骸を誤って掴むため。3-1 参照）

1-4. 合意を取る

codex の方針をベースに、実装に進んでよいか確認する。

• ユーザーが方針を修正したい場合は、修正点を反映して 1-2 を再実行し、codex に方針を更新させる（往復は 3 ラウンドを目安とし、それでも合意に至らない場合は残る論点を列挙してユーザーに判断を仰ぐ）
• ユーザーの承認なしに Phase 2 へ進まない

1-5. 設計コントラクトの確定（Phase 3 の適合レビュー用）

合意が取れたら、codex の方針（$lead_out）から「実装後に検証すべき設計約束」だけを抽出し、$contract_out に固定フォーマットで確定する。$lead_out の自由記述全文ではなく、検証可能な約束だけを構造化する（抽出元は codex の出力。Claude の新規創作を混ぜない。蒸留結果は main agent が一度確認する）。

軽量ゲート（先に判定する）: 『守るべき不変条件』『失敗モードと吸収方法』『責務分担』『採用アプローチ』のうち、実装後に検証する価値のある設計約束が合計 2 つ以上抽出できるか（失敗モードが少ない UI / 構成 / リファクタ系でも、責務分担や採用アプローチの逸脱が主リスクなら適合レビューの価値がある）。抽出できない（typo・数行 fix・設定値変更・機械的置換など、codex が確認質問なし・推奨アプローチ一行・代替案なしで即終わった薄いタスク）なら、$contract_out を作らず Phase 3 は Pass B（実装正当性レビュー）のみで実施する。判定は行数でなく検証価値で行う（迷ったらコントラクトを作る側に倒してよい。これは余剰トークン消費を狙うスキルなので）。

2 つ以上あれば次のフォーマットで Write する:

# 設計コントラクト（このタスクで守る約束）

## 採用アプローチ
- <どのレイヤーに何を追加/変更するか・1〜3行>

## 守るべき不変条件
- <壊してはいけない契約。実装後に 1 つずつ検証する>

## 失敗モードと吸収方法
| 失敗モード | 実装での吸収方法 |
|---|---|
| <順序競合 / 再送 / 二重実行 / 部分失敗 / 再起動 など> | <どう設計で吸収するか> |

## 責務分担
- <ファイル / レイヤー>: <担う責務>

1-6. 一時ファイルの削除

合意が取れた直後に、入力・自由記述の使い捨て 2 ファイル（$task_out / $lead_out）を削除する。$contract_out は Phase 3 の適合レビューで使うため、ここでは削除しない（削除は Phase 3-4）。

rm -f "$task_out" "$lead_out"   # contract_out は消さない

• 削除対象は使い捨ての 2 ファイルのみ。$contract_out と ./tmp/*.md の一括削除はしない
• $contract_out を作らなかった薄いタスクでは、削除する使い捨てファイルのみ消す
• ユーザーが「残しといて」と明示した場合のみスキップ

---

Phase 2: 実装

codex がリードした方針に沿って Claude が実装する。

• $contract_out（設計コントラクト）があれば実装の指針にする。各不変条件・失敗モードを実装が満たしているか、責務分担どおりに配置されているかを意識して書く
• Phase 1 で codex が挙げた不変条件・失敗モード・落とし穴は実装でも守る
• 実装中に codex の方針では解けないと分かったら、勝手に方針を変えず Phase 1 に戻り、codex に方針を見直させてユーザーに再合意を取る（方針が変わったらコントラクトも更新する）
• ~/.claude/CLAUDE.md の共通ルール（God クラス回避、重複コードの抽出、構造的修正優先など）に従う

---

Phase 3: 実装レビュー（実装後）

実装した差分を codex に通す。観点の異なる 2 パスに分けて独立に codex を呼ぶ（精度優先・codex を節約しない方針）。フレッシュ起動の codex に「長い設計コントラクト＋全 line-level バグ網羅」を 1 プロンプトで詰めると、high-altitude な設計適合観点が大量の file:line 指摘に埋もれて精度が落ちるため、束ねない。

• Pass A 設計適合レビュー: Phase 1 で確定した設計コントラクトに実装が適合しているかを high-altitude に検証する
• Pass B 実装正当性レビュー: バグ・リグレッション・仕様逸脱・テスト不足を line-level に検証する（従来どおり codex-review に委譲）

実行順は Pass A → Pass B（設計逸脱は実装細部より先に正すと手戻りが少ない）。$contract_out が無い薄いタスクでは Pass A を省略し Pass B のみ実施する。

3-1. 設計コンテキストの復元と Pass A の要否判定

Bash ツールはシェル変数を呼び出し間で保持しないため、$contract_out を変数で参照できない場合がある。まず Phase 1-3 で会話に明記した正確なパスを使う（今回のタスクで作ったファイルを確実に指す。最新 glob を無確認に拾わない）。

• そのパスのファイルが存在する → Pass A を実行（3-2 へ）
• そのパスのファイルが存在しない（薄いタスクで未生成、または会話からパスを復元できない） → 原則 Pass A をスキップし Pass B（3-3）のみ実行。ユーザーに「設計コンテキストが薄い／コントラクト未確認のため設計適合レビュー（Pass A）は省略し、実装レビューのみ行う」と一言告げる（黙ってスキップしない）
• 会話から正確なパスを復元できないが Pass A を行いたい場合に限り、ls -t ./tmp/design-contract.*.md で候補を提示し、今回のタスクのものか確認を取ってから使う（head -1 で最新を無確認に採用しない。別タスクの残骸コントラクトを誤って拾うため）
• Claude が薄いと判断しても、ユーザーが設計レビューも明示的に求めた場合は Pass A を実行する

3-2. Pass A: 設計適合レビュー

コントラクト本文を**重点観点（カスタム指示）**として注入し、合意済み設計に実装が適合しているかを codex に検証させる。

渡し方は codex-review スキルのモード選択（手順 1）に従う: 未コミット変更なら selector なしのプロンプト付きモード（codex exec review に下の注入プロンプトを渡す）、特定 commit / base を対象にする場合は selector とプロンプトを併用できないため fallback モード（codex exec -s read-only + 対象 diff をプロンプト内で名指し）になる。どちらを使うかは codex-lead 固有の判断ではなく、codex-review の既存分岐がそのまま処理する（「fallback が必須」と決め打ちしない）。

実行コマンドの組み立て（command プレフィックス・</dev/null・--ephemeral -o・タイムアウト・--full-auto 禁止）と、Pass A 用の一時出力（./tmp/codex-review.$stamp.md 相当を別途作る）・読み取り・空時の stdout/stderr fallback・削除は codex-review スキルの手順が正本（ここでは再記述しない）。codex-lead 側で書くのは、下の codex-lead 固有の注入プロンプトだけ。

注入プロンプト（モード共通の本文。未コミットのプロンプト付きモード、または commit / base 併用時の fallback、どちらに渡してもよい。対象に合わせて該当する分岐を選び、{sha} / {base} を実際の値に差し替える）:

対象の差分（未コミット変更 / commit {sha} / {base}..HEAD のいずれか）が、着手前に合意した設計コントラクトに適合しているかをレビューして。最初に対象差分を確認すること（未コミットは `git diff --stat`、commit は `git show --stat --oneline {sha}`、基点付き差分は `git diff --stat {base}..HEAD`）。

## 見てほしい観点（high-altitude。file:line の網羅より構造を優先）
- 守るべき不変条件が実装で破られていないか（破っている箇所と、なぜ破れるか）
- 列挙された失敗モードが実装で吸収されているか（吸収されていないモードはどれか）
- 責務分担どおりに実装されているか
- 採用アプローチから逸脱していないか。特に「場当たり的な条件分岐・特定ケースだけ救うワークアラウンド」への退行がないか

問題があるものだけ重要度順（P1/P2/P3）に。各項目に file:line と「コントラクトのどの項目に反するか」、最小の構造的修正案を書く。バグの網羅的指摘は別パスで行うので、ここでは設計適合に集中して。要約・称賛は不要。

## 合意済み設計コントラクト
<3-1 で復元した $contract_out の全文をここに貼る>

3-3. Pass B: 実装正当性レビュー

~/.claude/skills/codex-review/SKILL.md を Read し、その手順に従って実装差分を line-level でレビューする（バグ・リグレッション・仕様逸脱・テスト不足）。

• 未コミット変更なら codex exec review --uncommitted（デフォルトの selector モード。追加プロンプトは渡さない）
• このパスは設計適合（Pass A）とは別観点なので、コントラクトは渡さない（2 観点の混線を防ぐ）。別途 line-level で重点的に見たい観点があるときだけ codex-review のプロンプト付き / --strict モードを使う
• 出力の読み取り・空時の stdout / stderr fallback・一時ファイル削除は codex-review スキルの手順に従う

3-4. 指摘への対応とクリーンアップ

Pass A（設計適合）と Pass B（実装正当性）の指摘を観点ごとの見出しに分けて 1 つの報告に統合し、ユーザーに提示する（要約しすぎない）。

• P1/P2: コードを修正する。特に Pass A の設計逸脱は局所パッチでなく構造的に直す（場当たり的条件分岐への退行は Pass A の指摘趣旨に反するので採らない）
• P3: 取り込むか、issue 化するか、認識のみかを判断する
• 修正したら再レビューする。設計に関わる修正なら Pass A から、実装局所の修正なら Pass B から再実行する。P1/P2 の指摘がゼロになったら終了。再レビューは Pass 合計で最大 3 回とし、超えても残る場合は指摘を列挙してユーザーに判断を仰ぐ
• 報告と対応が終わったら、3-1 で復元したコントラクトを削除する: rm -f ./tmp/design-contract.<該当 stamp>.md。削除対象は今回のコントラクト 1 ファイルのみ（./tmp/*.md の一括削除はしない）。codex-review が作るレビュー出力ファイルは codex-review スキル側で削除されるため触らない。$contract_out を作らなかった薄いタスクではこのステップは不要。ユーザーが「残しといて」と明示した場合はスキップ

---

ルール

• Phase 1（codex の設計リード）を必ず先に通す。 Claude が先に設計を固めて実装に走らない。codex に方針を主導させ、合意を取ってから Phase 2 に進む
• Phase 3 は観点の異なる 2 パスに分けて独立に codex を呼ぶ: Pass A（設計適合・コントラクトを重点観点に注入）と Pass B（実装正当性・codex-review 委譲）。フレッシュ起動の codex では 1 プロンプトに束ねると high-altitude 観点が line-level 指摘に埋もれ精度が落ちるため束ねない。ただし設計コンテキストが薄いタスク（検証可能な設計約束＝不変条件・失敗モード・責務分担・採用アプローチが実質ゼロ）では Pass A を省略し over-engineering を避ける（判定は 1-5 / 3-1）
• 設計コントラクト（$contract_out）は Phase 1 で確定し Phase 3 完了まで生存させる: Phase 1-6 では削除せず Phase 3-4 で削除する。Bash ツールはシェル変数を呼び出し間で保持しないため、Phase 3 では変数でなく Phase 1-3 で会話に記録したパスで参照する（最新 glob を無確認に拾わない。3-1 参照）。Pass A の渡し方（未コミットは selector なしプロンプトモード、commit/base 併用時のみ fallback -s read-only）とコマンドの作法は codex-review スキルのモード選択が正本であり、「fallback が必須」と決め打ちしない
• 設計リードも実装レビューも codex はレビュー用途で使い、codex にコードを変更させない（設計リードは codex exec -s read-only、実装レビューは原則 codex exec review 系。selector とカスタム指示を併用する Pass A の fallback 時のみ codex exec -s read-only）
• codex exec 呼び出しの共通制約は codex-review スキルのルールが正本（各制約の理由・実測根拠・codex issue 番号はそちら参照。ここでは再記述しない）: command codex プレフィックス（zsh 関数オーバーライド回避）／全 codex exec 呼び出しに </dev/null 必須（stdin が EOF 待ちでハングするのを防ぐ）／--full-auto を付けず --ephemeral -o "$lead_out" を使う（-s read-only を上書きさせない）。Phase 1-2 のようにヒアドキュメントで prompt を組む場合の </dev/null 位置の注意は 1-2 のコメントに記載済み
• 設計リードは差分がないため codex exec -s read-only を使う（selector は使わない）
• 設計リードのモデルはスキル側で明示する: -m gpt-5.6-luna -c model_reasoning_effort="low"。省略すると ~/.codex/config.toml の既定（対話 TUI 側の都合で変わる）を拾い、実行ごとにモデルが変わる。Phase 3 のレビューが codex exec review に委譲される部分は codex-review スキル側のモデル指定に従う
• まず -o の出力ファイルを読み、空なら stdout / stderr を fallback として使う
• レビュー・方針はそのままユーザーに見せる（要約しすぎない）
• /tmp は使わず、出力ファイルは必ず ./tmp に置く。報告後、各フェーズで書き出したファイルだけを rm -f で削除する（$task_out / $lead_out は Phase 1-6、$contract_out は Phase 3-4）
• コマンド実行ツールのタイムアウトは 900000ms（15分）に設定する
• 構造的修正優先: 設計リード・実装レビューいずれでも、中長期的に改修を続けることを前提とした構造的な方針を優先する。場当たり的な条件分岐やワークアラウンドを提示しない
• 実装レビュー（Pass B）の詳細手順と、Pass A で使う fallback コマンドの組み立ては codex-review スキルに委ねる（このスキルでは設計リード・設計コントラクト・2 パスの全体フロー管理に集中する）
• codex を節約しない: 余剰トークンの消費を狙うスキルなので、codex の呼び出し回数を減らす最適化はしない。迷ったら codex に通す（ただし結論の出ない往復は避ける）

関連スキル

• ~/.claude/skills/codex-review/SKILL.md — Phase 3 の Pass B（実装正当性レビュー）の委譲先、および Pass A で使う fallback コマンドの正本
• ~/.claude/skills/cross-review/SKILL.md — 有識者エージェント + codex の複数視点レビュー（2 パスでも足りず、さらに多視点でレビューを厚くしたい場合）
• ~/.claude/skills/review-loop/SKILL.md — GitHub PR 上で codex と往復レビューするループ