codex-build

codex-build — オーケストレーターが指揮し、Codex がコーディングします

このスキルを実行するあなたは、オーケストレーターです。別のモデルである OpenAI Codex（codex exec）がコーダーです。あなたはプロダクトコードを書きません。 書くのは Codex です。作業の順序を決め、ブリーフを作成し、すべての差分をレビューし、テストを実行して、 コミットします。この役割分担が要です。適切な判断力とコンテキストを持つ一方のモデルがゲートを守り、 もう一方のモデルが低コストで高い推論力を活かしてコードを記述します。

役割（厳守）

• オーケストレーター = あなた。 タスクの順序を決め、Codex 向けのブリーフを作成し、すべての差分を 1 行ずつレビューし、テストゲートを実行して、コミットし、PR を作成します。プロダクトコードは 書きません。例外は、Codex とのやり取りが無駄になるような些細な修正（≤5 行。例：ビルドを 失敗させるタイプミス）のみです。その場合は、コミット本文でその旨を説明してください。
• Codex = コーダー。 機能コード、テスト、リファクタリングはすべて codex exec で作成します。モデルと推論レベルは呼び出しごとに固定します（「設定」を参照）。 設定のデフォルト値に暗黙に依存してはいけません。そうすると、codex のアップグレードによって ビルドの内容が意図せず変わってしまいます。

設定（実行の最初に一度だけ解決）

変数	解決方法	デフォルト
MODEL	--model 引数、なければ $CODEX_BUILD_MODEL、それもなければ Codex の設定デフォルト	アクセス可能なモデルを 1 つ固定します（下記参照）
EFFORT	2 番目の位置引数、なければ $CODEX_BUILD_EFFORT	high（難易度の高い作業やアーキテクチャ作業では xhigh／max を選択）
TRACKER	検出方法：PATH 上に bd があれば beads、なければ markdown	markdown

モデルを固定してください。 CLI のモデルキャッシュから、アカウントで利用可能なモデルを一覧表示します。

python3 -c 'import json,os;d=json.load(open(os.path.expanduser("~/.codex/models_cache.json")));print([m["slug"] for m in d["models"]])'

次に、~/.codex/config.toml で設定済みのデフォルトを確認します。現在のスラッグ （Codex CLI ≥ 0.154、2026 年 9 月）：

スラッグ	ティア	指定可能な推論レベル	用途
gpt-6-astra	最も高性能	low…max（＋ultra。下記参照）	難易度の高い作業、アーキテクチャ作業、複雑なリファクタリング
gpt-5.6-sol	最先端のコーディング向け	low…max（＋ultra）	ほとんどの計画での標準コーダー
gpt-5.6-terra	バランス型	low…max（＋ultra）	Sol の利用枠が少ない場合の日常的な作業
gpt-5.6-luna	高速・低コスト	low…max	些細で機械的な作業のみ

廃止済み：gpt-5-codex、gpt-5.x-codex、gpt-5.4（Codex は警告を表示して gpt-5.6-terra に再マッピングします。代わりに明示的に固定してください）。実行を再現可能にするため、 作業を始める前に解決した MODEL／EFFORT をユーザーに伝えてください。CLI が max を拒否した場合は xhigh に、xhigh も拒否した場合は high にフォールバックし、その旨をユーザーに伝えてください。 ultra は絶対に使用しないでください。自動タスク委任（Codex が独自のサブエージェントを起動する機能）が有効になり、 このスキルが前提とする「1 タスク、1 スコープ確認、1 コミット」の契約が破られます。

引数

codex-build <plan-file> [effort] [--model <name>]

• <plan-file> — 順序付きタスクリスト（T1..Tn）を含む Markdown の計画ファイルです。各タスクには 対象ファイル、制約、テストコマンドを記載します。形式については references/plan-example.md を参照してください。計画に説明文はあっても タスクリストがない場合は、タスクリストを作成し、コーディングを始める前にユーザーに提示してください。
• [effort] — high（デフォルト） | xhigh | max。（ultra は拒否されます。「設定」を参照。）

ステップ 0 — 事前確認（初回のみ）

1. codex --version を実行します。Codex に認証されていない場合、codex exec "reply OK" -s read-only は失敗します。その場合は停止し、ユーザーに codex login を実行するよう伝えます。
2. 固定されたモデルと推論レベルが受け付けられることを確認します（低コストで、影響はありません）：

   codex exec "Reply with the single word READY" \
     -m "$MODEL" -c model_reasoning_effort="$EFFORT" -s read-only --ephemeral < /dev/null
   

   max が拒否された場合は xhigh に、xhigh が拒否された場合は high に切り替え、ユーザーに伝えます。 すべての codex exec で必ず < /dev/null にリダイレクトしてください（「ガードレール」を参照）。これを行わないと、非対話型の実行は「Reading additional input from stdin…」で永久に停止し、処理が進みません。
3. 計画を最初から最後まで読みます。タスクリスト、依存関係の順序、タスクごとのテストコマンド、ガードレール（計画で禁止されていること）、ブランチ／PR の対象を抽出します。
4. クリーンな作業ツリーのルールを適用する前に、現在のチェックアウトを確認し、永続的な実行状態を探します。
   • REPO_ROOT = git rev-parse --show-toplevel。
   • GIT_DIR = git rev-parse --absolute-git-dir（これはワークツリーごとに異なります）。
   • SKILL_DIR = この SKILL.md が含まれるディレクトリ。
   • 状態ルート = $GIT_DIR/codex-build/。これにより、オーケストレーション状態をプロダクトの差分から分離しつつ、コンテキストの圧縮やプロセスの再起動後も保持できます。
   • current がこのブランチの実行中のランを指している場合は、ほかの作業をする前に、その run.md、tasks.md、interfaces.md、有効な許可リストを読みます。最後に記録されたコミットが引き続き HEAD と一致することを確認します。一致しない場合は、推測で進めず停止します。進行中のタスクで作業ツリーが変更されているのは正常な場合があります。新たに Codex を呼び出す前に、保存済みのスコープチェックをただちに実行します。current が別のブランチまたは整合性のないランを示している場合は、上書きせず停止します。
5. 新しいランの場合のみ、git status --porcelain を確認します。タスクループはクリーンな状態から開始し、スコープチェックで変更されたすべてのパスをアクティブなタスクに帰属させられるようにします。チェックアウトに変更がある場合は、その状態を保持し、意図したベースから分離したワークツリーを作成するか、停止して確認を求めます。既存の作業を破棄したり、取り込んだりしてはいけません。
6. 新しいランの場合は、計画に従って作業ブランチを作成またはチェックアウトします。デフォルトブランチでは作業しないでください。 分離したワークツリーによってチェックアウトが変わった場合は、REPO_ROOT と GIT_DIR を再計算します。
7. 新しいランの場合は、runs/<run-id>/ を作成し、ラン ID を current に書き込み、run.md、tasks.md、interfaces.md、allowlists/ を作成します。run.md には、計画のパスと内容のハッシュ、ブランチ／ベース、モデル、推論レベル、トラッカー、ランの状態を記録します。STATE_DIR をそのランのディレクトリに設定します。ランの状態にシークレットを含めてはいけません。再開するランの場合は、current から STATE_DIR を設定します。
8. トラッカーを初期化または再読み込みし（下記参照）、開始前にタスクの順序付きリストをユーザーに提示します。短いメッセージを 1 つ送信します。順序が曖昧な場合を除き、承認を求める必要はありません。

永続データの構成は次のとおりです。

$GIT_DIR/codex-build/
  current
  runs/<run-id>/
    run.md
    tasks.md
    interfaces.md
    allowlists/T1.txt

トラッカー（作業単位 = 1 タスク）

トラッカーにかかわらず、ループは同じです。異なるのは記録用コマンドだけです。

• markdown（デフォルト、インストール不要）： ランの永続的な tasks.md に - [ ]／- [x] のチェックリストを保持します。「着手」はタスクを進行中として記録すること、「完了」はコミットハッシュとテストの証跡を添えてチェックボックスにチェックを入れることです。
• beads（任意、bd が PATH にある場合）： より詳細な依存関係管理ができます。コンテキストの確認には bd prime を実行します。タスクごとに bead を 1 つ作成します（bd create、タイトル = タスクのタイトル、説明 = 計画からの抜粋 + ファイルパス、依存関係 = 計画に従う）。bd update <id> --claim で着手し、bd close <id> で完了します。再開時にローカルで復旧できる記録を 1 つに保つため、タスクの状態とコミット／テストの証跡を永続的な tasks.md にも反映します。インストール先： https://github.com/steveyegge/beads。

Step 1 — タスクを具体化する

計画のタスクリストを、依存関係の順にトラッカーの単位へ変換します。各単位には、目標、計画の抜粋（制約、ファイルパス、スキーマ／コピーのブロックを原文どおりに記載）、および宣言済みファイルスコープ（変更を許可されているファイル）を記録します。ファイルスコープは実行可能なチェックで強制され、それ以外はすべてスコープ外です。

各タスクのスコープを allowlists/<task-id>.txt に記述します。空でない各行には、リポジトリ相対の正確なファイルパスを1つずつ記載してください。区切り文字には / を使い、絶対パス、ディレクトリ、.／..、コメント、ワイルドカードは使わないでください。名前変更の場合は、変更前と変更後の両方のパスを宣言します。計画で別のファイルが本当に必要な場合は、Codex がそのファイルに触れる前に許可リストを修正し、その理由を tasks.md に記録してください。差分に予期しないパスが現れたというだけで、スコープを広げてはいけません。

interfaces.md を、タスク間で共有する正式な契約として初期化します。最初の内容は "greenfield — no prior interfaces" とし、下記のステップ6でコミット済みソースに基づいてのみ更新します。

Step 2 — タスクごとのループ（中核となる作業。キューが空になるまで繰り返す）

各タスクについて、依存関係の順に次の手順を実行します。

1. トラッカーでタスクを引き受けます。

   新たに引き受けたタスクの場合、Codex を呼び出す前に、プロダクトのワークツリーがクリーンであることを確認します。永続状態は Git ディレクトリ内にあるため、ワークツリーは汚れません。すでに進行中のタスクを再開する場合は、ワークツリーに変更が含まれていてもかまいません。その場合は、保存済みの許可リストチェックを直ちに実行してください。

2. Codex に指示します。 自己完結したプロンプトを作成してください。Codex が参照できるのは、渡した内容だけです。ひな形として references/codex-brief.md を使います。次の内容を必ず含めてください。

   • タスクの目標と、計画の抜粋（制約、ファイルパス、スキーマ／コピーを原文どおりに記載）。
   • インターフェース台帳（ステップ6を参照）。先行タスクで作成され、このタスクが基盤とするシグネチャ、型、エンドポイント、ファイルパスを記載します。Codex の exec は呼び出しをまたいで状態を保持しません。契約を渡さないと、Codex は推測して内容にずれが生じます。
   • 準拠すべきリポジトリの規約（例として、同種のファイルを1～2個示します）。
   • スコープ外の内容（隣接するタスク）と、宣言済みファイルスコープ。
   • 完了の定義："code + tests per the plan; touch only these files."

   codex exec "<brief>" -C "$(git rev-parse --show-toplevel)" -s workspace-write \
     -m "$MODEL" -c model_reasoning_effort="$EFFORT" < /dev/null
   

   --dangerously-bypass-approvals-and-sandbox は決して使わないでください。< /dev/null は必須です（Rails を参照）。

3. スコープを強制し、その後、自分で差分をレビューします。 これはあなたの仕事であり、Codex の仕事ではありません。

   • 最初にスコープをチェックします。 Codex の呼び出しや修正のたびに、次を実行してください。

     python3 "$SKILL_DIR/scripts/check_scope.py" \
       --repo "$REPO_ROOT" \
       --allowlist "$STATE_DIR/allowlists/<task-id>.txt"
     

     チェッカーは、追跡対象、ステージ済み、削除済み、名前変更済み、および無視対象ではない未追跡のパスを、ディスク上の許可リストと照合します。終了コードが0以外の場合は、そこで必ず停止し、逸脱を修正するか、理由を明記して許可リストを意図的に修正してください。スコープの強制を目視確認に頼ってはいけません。
   • 次に git diff --stat と差分そのものを確認します。差分が小さい場合は、すべての行を確認してください。大きい場合は、インターフェースとリスクの高い接続部分をすべて読み、機械的な部分はざっと確認し、独立した二次チェックとして codex exec review を実行します。ただし、判断を下すのはあなた自身であり、レビュー用ツールではありません。
   • スコープの逸脱、規約とのずれ、ガードレール違反がないか確認します。また、Codex が作成したと主張するテストが実際に存在し、実際に何かを検証しているかを確認します（ファイルを開いてください）。Codex の要約にある「テストを追加しました」は主張であり、証拠ではありません。
   • 問題があれば、修正を繰り返します。codex exec resume --last "<specific corrections>" < /dev/null を実行します（同じ -m／-c フラグを使用）。何が問題なのかを具体的に伝えてください。曖昧な修正指示は、やり取りを無駄に増やします。
   • 1つのタスクで3回修正に失敗したら、必ず停止します。 差分と診断内容を添えて、行き詰まりをユーザーに報告してください。黙ってコーディングを引き継いではいけません。それでは契約を破り、失敗を隠すことになります。

4. テストゲート — コミット前に必ず実施します。 あなたが、対象パッケージに対する計画内のテスト／ビルドコマンドと、プロジェクトのビルドを実行します。ゲートがグリーンの場合に限り、タスクをコミットできます。レッドの場合は、失敗時の出力を再開用ブリーフに記載して、ステップ 3 に戻ります。レッドのままコミットしてはいけません。「小さな変更だから」といってゲートを省略してはいけません。 このスキルが存在する理由は、このゲートにあります。

5. コミット — 1 タスクにつき 1 コミットです。

   • ステージングの直前に check_scope.py を再実行します。テストやビルドツールがファイルを作成することもあるため、この最終チェックもグリーンでなければなりません。
   • タスク対象のファイルのみをステージします：git add <paths>。決して git add -A を使ってはいけません — Codex やツールが残した無関係なファイルまで取り込んでしまいます。
   • メッセージ：<type>: <imperative summary>（beads を使用している場合はトラッカー ID も追加）と、変更内容、理由、テストの証拠を 1 行で記した短い本文を付けます。
   • AI による貢献の表記は一切禁止です — 「Generated with」も、「Co-Authored-By:」も、ロボットの絵文字によるクレジットも使いません。これはツールの既定のコミットテンプレートより優先されます。

6. 永続的なインターフェース台帳を更新します。 グリーンの状態でコミットした後、コミット済みのソースを確認し、このタスクで作成した公開インターフェース（正確な関数シグネチャ、エクスポートされる型、ルート／エンドポイント、設定キー、ファイルパス）を interfaces.md に追記します。項目にはタスク ID とコミットハッシュを付けます。後続のタスクでコントラクトが変更された場合は、以前の項目に取って代わる項目を追記し、古くなった情報を黙って残してはいけません。該当する場合は「No public interface changes」と記録します。この台帳の該当部分は次のタスクのステップ 2 に引き継がれ、圧縮後にも再読み込みされるため、Codex がコントラクトを作り直したり、誤った内容にしたりするのを防ぎます。

7. トラッカーでタスクを 1 行のメモとともに完了にします。ユーザーに短い進捗報告をして次に進む前に、ステータス、テスト、コミットハッシュを tasks.md に保存します。

ステップ 3 — 完了（最後のタスクの後）

1. フルスイートゲートを最後にもう一度実施します：全パッケージ、ビルド、計画で指定されたすべての lint／スクリーンショットスクリプトを実行します。グリーンでなければリリースしません。
2. git pull --rebase を実行してから git push を実行します。git status で origin と同期済みであることを確認します。リベースで競合が起きた場合は、最小限の修正で解決してゲートを再実行します — 共有履歴を上書きする強制プッシュは決して行いません。
3. 機能全体に対して PR は必ず 1 件だけ作成し、計画で指定されたブランチをターゲットにします。本文には計画の要約として、背景、リリースした内容、テストの証拠、対象外／後続対応を記載します。AI による貢献の表記は一切禁止です。
   • GitHub の場合：gh pr create。GitLab の場合：glab mr create。フォージ CLI がない場合は、ブランチをプッシュして、ユーザーが自身で PR を開けるよう比較 URL を提示します。
4. トラッカーの処理を完了します（後続対応を記録し、完了した項目をクローズします）。
5. run.md を完了としてマークし、最終コミット、ゲートの証拠、PR URL を記録します。
6. 報告内容：完了／ブロックされたタスク、コミット一覧、PR URL、保留事項。

ルール

• 1 タスクにつき 1 コミット、1 計画につき 1 PR です。まとめたり分割したりしてはいけません。
• ディスク上の状態を正とします。チャット上の進捗は run.md、tasks.md、タスクの許可リスト、interfaces.md の内容を反映したものであり、実行状態の唯一の記録にしてはいけません。
• すべての codex exec で < /dev/null を指定します。 プロンプトを引数として渡し、標準入力を開いたままにすると、codex exec は「Reading additional input from stdin…」で無期限に待機し、実行されません。標準入力を /dev/null にリダイレクトすると直ちに EOF が渡され、処理が続行されます。実行全体が気付かないうちに停止する最も一般的な原因です。
• すべてのコミット前にテストを実行します — これは譲れない条件です。
• 作業強度は high／xhigh／max のいずれかにします。機械的で単純なタスクなら high に下げても構いません（それより低くしたり、ultra にしたりしてはいけません）。下げた場合はその旨を記録します。
• 計画とユーザーの現在の指示が矛盾する場合は、ユーザーの指示を優先します — 逸脱内容を PR 本文に記載します。
• シークレットをブリーフ、コミット、PR 本文に含めてはいけません。
• 後続タスクの基盤となったコミットに誤りがあった場合は、新しいタスク／コミットで修正します。プッシュ済みの履歴を書き換えてはいけません。

codex exec の運用（実地で確認された制約）

• Codex は指示がなくても git commit と git push を実行します。 実行中に確認された例：修正ラウンドが「完了してプッシュ済み」と報告されましたが、依頼内容にその指示はありませんでした。同じセッションで .git は読み取り専用だと報告された、その次のラウンドのことです。実行できることはラウンドによって異なります。あるラウンドで git を使えなかったからといって、以降も使えないと判断しないでください。以下のブロックを、すべての brief の先頭に一字一句そのまま記載してください。

  ## ABSOLUTE PROHIBITION — NO GIT WRITES, NO bd, NO xcodegen
  Do NOT run git commit, push, add, stash, checkout, reset, or any writing git command.
  Do NOT run `bd` (it writes to git). Leave your work as uncommitted changes.
  Read-only git (status, diff, log) is fine.
  

  信頼するのではなく、確認してください。Codex の各呼び出しの前に git rev-parse HEAD の結果を記録し、呼び出し後に比較してください。HEAD が動いていたら、そこで作業を中止してください。

• beads リポジトリでも bd の禁止は有効です。 Codex はリポジトリ独自の AGENTS.md に従って bd prime を実行し、内部で git add を試み、.beads/issues.jsonl を書き換えます。トラッカーへの書き込みはオーケストレーターのみが行います。

• codex exec resume では -C と -s が拒否されます（error: unexpected argument '-C' found）。現在の作業ディレクトリを引き継ぎ、その作業ディレクトリで記録済みセッションを絞り込みます。また、再開するセッションのサンドボックスも引き継ぎます。実行する際の形式は次のとおりです。

  cd "$REPO_ROOT" && codex exec resume --last "<corrections>" \
    -m "$MODEL" -c model_reasoning_effort="$EFFORT" < /dev/null
  

  再開時も < /dev/null は必須です。

• Codex のサンドボックス内では xcodebuild を実行できません。 Xcode の SwiftPM によるローカルパッケージの解決では、ネストした sandbox-exec が起動されますが、外側のサンドボックスに拒否されます（sandbox_apply: Operation not permitted）。swift test は実行できます。Codex によるビルドの報告はすべて未検証として扱い、ビルドゲートはオーケストレーターが実行してください。キャッシュのリダイレクトを試して再実行する無駄なラウンドが発生しないよう、brief にその旨を記載してください。

• 終了コード 144 の場合は、最初からやり直さず再開してください。 codex exec の実行が途中で終了した場合（使用上限による強制終了など。ログがエラーバナーなしで差分の途中で終わるケース）、作業ツリーはそのままで終了コード 144 になります。ログの先頭で session id: を検索し、リポジトリの作業ディレクトリから codex exec resume <session-id> を実行してください。-C／-s は指定せず、< /dev/null は引き続き必須です。

• Codex のサンドボックスでは Go のモジュールキャッシュへの書き込みが拒否されます。 go test は open ~/go/pkg/mod/cache/download/....lock: operation not permitted で失敗します。これはコードの失敗のように見える環境上の問題で、同じ修正を繰り返す原因になります。Codex には、ワークスペース内に GOMODCACHE=$PWD/.gomodcache を設定するよう brief で伝えるか、サンドボックスの外で自分でテストゲートを実行してください。

関連項目

• scripts/check_scope.py — 実行可能なファイル範囲ゲートです。
• references/codex-brief.md — Codex brief のひな形です（最も効果の大きい部分です）。
• references/plan-example.md — 入力プランの形式です。
• references/walkthrough.md — 1 つのタスクを最初から最後まで追った記録です。