Codexサブエージェントの使い方｜並列化すべき作業・避けるべき作業

Codexのサブエージェントは、調査・テスト・レビューのように、互いに独立した読み取り中心の作業から使い始めるのが安全です。複数の担当へ同じリポジトリの実装を一斉に任せると、差分の衝突だけでなく、設計判断や生成物の食い違いも増えます。

実践しやすい型は、調査を並列化し、書き込みを単一担当へ集約し、最後の検証を再び並列化する流れです。本記事では、Codexでサブエージェントを使う方法と、並列化の可否を決める3つの判断軸を整理します。

3行まとめ

• コード探索、ログ分析、テスト、観点別レビューは、サブエージェントへ分けやすい作業です。
• 同一ファイル、DB migration（データベース構造の変更）、lockfile、コード生成物を同時に編集する作業は、原則として一人の書き手へ集約します。
• 依頼文には「担当範囲」「全担当の完了を待つこと」「返却形式」の3点を入れます。

Codexのサブエージェントとは

サブエージェントは、メインエージェントから特定の作業を委譲される担当です。それぞれが独立したエージェントスレッド（担当ごとの作業履歴）で調査やテストを進め、結果をメインエージェントへ返します。メインエージェントは、要件や設計判断を保ちながら複数の結果を統合します。

OpenAI公式のSubagentsドキュメントによると、現行のCodexではサブエージェントワークフローが既定で有効です。ChatGPTデスクトップアプリ、Codex CLI、IDE拡張で活動を確認できます。

役割の違いを整理すると、次のようになります。

サブエージェントの利点は、人数そのものではありません。探索ログやテスト出力を別スレッドへ分け、メインの会話を意思決定に集中させられる点にあります。

並列化すべき作業・避けるべき作業

公式ドキュメントは、探索、テスト、トリアージ、要約などのread-heavy（読み取り中心）な作業を出発点として勧めています。一方、複数担当が同時にコードを編集するwrite-heavy（書き込み中心）な作業では、競合と調整コストに注意が必要です。

実務でよくある作業を比較すると、次のように分けられます。

「別ファイルだから安全」とは限りません。たとえば、別々の機能実装でも共通の型、API、DB schema（データ構造の定義）を変更するなら、共有する書き込み面があります。ファイル名ではなく、変更が影響する契約まで見て分ける必要があります。

並列化前に答える3つの質問

1. 作業同士に依存関係があるか

担当Bが担当Aの設計や出力を待たないと始められないなら、同時に走らせても待ち時間は減りません。むしろ、前提が確定する前にBが推測で進めるリスクがあります。

一方、「認証処理を調べる」「テスト構成を調べる」「既存のエラーハンドリングを調べる」のように、同じ目的へ向かいながら個別に完結する探索は分けやすい作業です。

2. 共有する書き込み面があるか

次のいずれかを複数担当が触るなら、書き込みは一担当へ集約する方が安全です。

• 同一ファイルや近接するコード
• 共通のinterface（コンポーネント間の契約）や設定
• DB migrationとseedデータ
• 依存関係のlockfile
• コード生成物やビルド成果物
• 同じ画像、記事、ドキュメント

調査担当には「変更しない」と明記できます。必要な修正案をファイル位置とともに返してもらい、メインエージェントまたは一人のworkerがまとめて実装します。

3. 結果の返却形式をそろえられるか

担当ごとの結果が長い自由文だと、メインエージェントが比較する負担が増えます。次のように返却項目を先に決めておくと、統合しやすくなります。

• 結論
• 根拠となるファイルと行
• 影響範囲
• 推奨対応
• 未確認事項

公式ドキュメントも、よい依頼には分割方法、完了待ち、返却する要約や成果物を含めるよう案内しています。

安全な型：並列調査→単一実装→並列検証

複雑な変更では、次の流れから始めると役割が混ざりにくくなります。

1. 複数のexplorerへ、担当範囲を分けて読み取り調査を依頼する
2. メインエージェントが結果の矛盾と優先順位を整理する
3. 一人のworkerが実装する
4. セキュリティ、テスト、保守性などの観点別に検証する
5. メインエージェントが修正要否と完了条件を判断する

Codexへは、たとえば次のように依頼できます。

このブランチはまだ変更せず、3つの独立した調査を並列で進めてください。

- explorer 1: 認証処理の入口、データの流れ、関連テストを調べる
- explorer 2: エラー処理とログ出力の既存パターンを調べる
- explorer 3: 変更による影響範囲と不足テストを調べる

全担当の完了を待ってから、各結果を次の形式で統合してください。
1. 結論
2. 根拠となるファイルと行
3. 推奨する変更
4. 未確認事項

この段階ではファイルを編集しないでください。

調査結果を確認した後で、実装担当へ変更対象と完了条件を渡します。最初から「調査して、そのまま各自で直して」と依頼しないことがポイントです。

実行中のサブエージェントを確認する

基本操作は、使っているクライアントによって異なります。

実行中に一つの担当だけ前提がずれた場合は、Codexへ対象スレッドの修正または停止を依頼します。すべての担当を再実行する必要はありません。調査が長引く場合も、メイン側で先に実装へ進まず、必要な結果がそろうまで待つ条件を依頼文へ含めます。

トークン・権限・競合の注意点

並列化はトークンを節約する機能ではない

各サブエージェントは個別にモデルとツールを使うため、公式ドキュメントでは、同等の単一エージェント実行よりトークン消費が増えると説明されています。数分で終わる単純な検索を細かく分けすぎると、分担説明と統合の方が重くなります。

並列化する価値があるのは、時間短縮または観点分離の効果が、追加コストを上回る場合です。小さな修正を機械的に複数担当へ割り振る必要はありません。

sandboxとapprovalは親の設定を確認する

sandbox（ファイルやコマンドの実行範囲）とapproval（追加権限を人が承認する仕組み）は、原則として親ターンの設定をサブエージェントが継承します。委譲前にメイン側の権限モードを確認してください。カスタムエージェントを読み取り専用にするなど、個別設定で範囲を狭められる場合もあります。

Codexが書き込めない場合の原因切り分けは、Codexがファイルを編集できないときの対処法で詳しく扱っています。サブエージェント数を増やしても、親の書き込み範囲そのものは広がりません。

複数の書き込みが必要ならWorktreeも検討する

OpenAI公式のWorktreesドキュメントによると、Git worktree（同じリポジトリの別チェックアウト）を使うと、複数のチャットを別の作業ツリーで進められます。ローカルの作業を保ちながら、別ブランチの変更を並行させたい場合の選択肢です。

ただし、ファイル配置が分かれても、互換性のないAPI変更やDB設計を最後に統合する問題までは消えません。Worktreeは物理的な編集衝突を減らす仕組みであり、論理的な整合性を保証する仕組みではない、というのが筆者の判断です。

カスタムエージェントは必要になってから

Codexには、汎用のdefault、実装向けのworker、読み取り探索向けのexplorerが組み込まれています。最初はこれらを役割名とともに指定し、繰り返し使う制約が固まってからカスタム化すると管理対象を増やさずに済みます。

個人用のカスタムエージェントは~/.codex/agents/、プロジェクト用は.codex/agents/へTOMLファイルを置きます。たとえば、変更を行わず依存関係だけを確認する担当なら、次のような最小構成を検討できます。

name = "dependency_reviewer"
description = "依存関係と変更影響を読み取り専用で確認する"
sandbox_mode = "read-only"
developer_instructions = """
ファイルを変更せず、依存関係、互換性リスク、不足テストを確認する。
結論、根拠となるファイル、影響範囲、未確認事項を返す。
"""

2026年8月28日時点の必須項目はname、description、developer_instructionsです。公式はカスタムエージェントの形式が今後変わる可能性にも触れているため、古い設定例をそのままコピーせず、導入時にSubagents公式ドキュメントを確認してください。

Codexの個人設定を別ドライブで管理している場合は、Codexの保存場所をCドライブからDドライブへ変更する方法も参考になります。

失敗しやすい分け方

担当数だけを先に決める

「5人で並列化する」ことを先に決めると、独立していない作業まで無理に分割しがちです。担当数は、依存しない部分問題の数から決めます。

調査担当にそのまま修正させる

探索中の仮説は、他担当の結果で変わる可能性があります。すべての結果を比較する前に各自が書き始めると、矛盾した方針がコードへ残ります。

「いい感じにまとめて」で終える

返却形式がないと、ある担当は要約だけ、別の担当は大量のログを返します。ファイル位置、根拠、重要度、未確認事項など、統合に必要な項目を決めてください。

完了を待たずに次へ進む

速く終わった一担当の結論だけで実装を始めると、並列調査の価値が失われます。依頼文に「全担当の完了を待つ」と明記します。

依頼前チェックリスト

• [ ] 各担当は、他担当の出力を待たずに開始できる
• [ ] 同じファイル、契約、migration、lockfile、生成物を同時に編集しない
• [ ] 調査段階では変更禁止を明記した
• [ ] 各担当の範囲と完了条件が一文で説明できる
• [ ] 結論、根拠、影響範囲、未確認事項の返却形式を決めた
• [ ] 全担当の完了を待ってから統合するよう依頼した
• [ ] 追加トークンに見合う時間短縮または観点分離がある
• [ ] 親ターンのsandboxとapprovalを確認した

サブエージェントは、複雑な仕事を無条件に速くする機能ではありません。独立した読み取りを並列にし、意思決定と書き込みを絞ることで、初めてメインの文脈を保ったまま活用できます。

セッション自体の読み込みでfailed to resolve rollout pathが出る場合は、並列化より先にCodexのrollout pathエラーを安全に切り分ける方法を確認してください。

参考資料

• Subagents – OpenAI Docs（2026年8月28日確認）
• Worktrees – OpenAI Docs（2026年8月28日確認）