Codex Subagent初心者ガイド：並列処理で開発効率を向上させる実践的手法

Codex Subagentとは

CodexのSubagentは「子エージェント」とも呼ばれ、複雑なタスクを複数のサブエージェントに分割し並列処理させる機能だ。各サブエージェントは独立したスレッドで実行され、結論をメインスレッドに返す。

OpenAIのドキュメントでは、Subagent workflowは複数の並列エージェントを実行して結果を統合するプロセスと定義されている。Subagentは特定のタスクを担当するエージェントであり、Agent threadは各エージェントの実行スレッドで、CLIで確認・切り替えが可能だ。

この機能が解決する主な課題は以下の2つだ：

1. コンテキスト汚染の防止：テスト修正などのタスクでは、大量のファイル読み取りやコマンド実行、エラー解析が必要になる。これらすべてをメインスレッドで処理すると、判断が混乱しやすい。Subagentはサブスレッドで処理を完結させ、結論のみを返すことでメインスレッドをクリーンに保つ。

2. 並列処理による効率向上：PRレビューのようにセキュリティ・スタイル・テストカバレッジ・並行性・保守性など複数の視点が必要なタスクでは、一個のエージェントが順番に処理するよりも並列で処理した方が高速かつ漏れがない。

要するに、SubagentはCodexの使用パターンの一つだ。

適用場景と不適用場景

単純な判断基準は、タスクが相互に依存しない小さなブロックに分割可能かどうかだ。分割可能ならSubagentを利用し、不可能なら利用すべきでない。

不適切な場面は以下の通りだ：

• タスク自体が小さい場合
• サブタスクが密接に連携している場合
• 書き込み範囲が重複する場合
• 分割方法が明確でない場合

Subagentが有効な場面は主に以下の通りだ：

• 大規模コードベースの探索
• PRの多次元レビュー
• 複数のバグ原因の同時調査
• セキュリティ・パフォーマンス・テスト・保守性の個別評価
• 長文ドキュメント・ログ・複雑なエラーの分割分析
• あるエージェントが機能を実装し、別のエージェントが並行してリスクチェックを行う

公式の推奨としては、まずread-heavyなタスク（探索・テスト・トリアージ・要約など）から始めることだ。複数エージェントによるコード変更はwrite-heavyで、ファイル競合や調整コストが発生するリスクがある。

また、各サブエージェントがモデルとツールを独立して実行するため、トークン消費量は単一エージェントより増大する。プロジェクトが小さい場合は目立たないが、大規模になると顕著になる。

Subagentの起動方法

CodexはデフォルトではSubagentを自動起動しない。プロンプトで起動数と各タスクを明示する必要がある。よくある指定方法は以下の通りだ：

• "spawn two agents"
• "delegate this work in parallel"
• "use one agent per point"

日本語で指定する場合は、例えば「3つのSubagentを起動し、セキュリティ・テスト・保守性をそれぞれ検査する」という表現も有効だ。

以下は実践でよく使うテンプレート例だ：

並列Subagentで現在のブランチをレビューしてください。
3つのSubagentを起動：
1. セキュリティリスクを検査
2. テストの欠落を検査
3. コードの保守性を検査

すべてのSubagentの完了を待ってから結果を統合してください。
出力は重要度順にソートし、ファイルパスを付記すること。

PRレビューの具体例

新機能を実装した後のPRレビューでは、以下のようなプロンプトが有効だ：

現在のブランチをmainとの差分でレビューしてください。
1つのSubagentで潜在的なバグを検査し、
1つのSubagentでテストカバレッジを検査し、
1つのSubagentでコード品質と保守性を検査してください。

各Subagentは明確な問題点のみを出力し、詳細なプロセスは出力しないこと。
3つのSubagentがすべて完了後に以下を統合してください：
- 高リスク問題
- 中リスク問題
- 任意の最適化案
- 優先修正すべき点の推奨

このテンプレートのポイントは以下の通りだ：

• 各Subagentの役割を明確に分離し、重複を防止
• 「すべてのSubagentの完了を待ってから統合」を明示し、中間結果での判断を防止
• 出力形式を指定し、リスクレベル別に整理されたリストを提供
• 「優先修正点の推奨」を依頼することで、問題点の優先順位付けも委任可能

ShipReadyケーススタディ

実際のプロジェクト「ShipReady」（SaaSランディングページ監査のMVP）でのSubagent使用例を紹介する。プロジェクト規模は小さく、主要ファイルは以下の通りだ：

• バックエンドAPI：src/app.js
• 監査ルールとリライト：src/audit.js
• ストレージ：src/store.js
• フロントエンド：public/app.js

最初の直感ではSubagentにコード変更を指示しがちだが、プロジェクトが小さいほどエージェント間でファイル競合が発生しやすい。より安定した方法は、まずすべてのSubagentをread-onlyモードで実行することだ。

このプロジェクトでSubagentの使用を試みてください。
3つのread-only Subagentを起動：
1. runtime-risk-agent：潜在的バグ、非同期エラー、API状態フロー、本番環境リスクを検査
2. qa-coverage-agent：テストの欠落、不足ユースケース、回帰リスクを検査
3. architecture-agent：モジュール境界、重複ロジック、後方互換性を検査

すべてのSubagentでファイル変更は禁止。
すべて完了後、メインスレッドで結論を統合し、修正の要否を判断。

この分割方法の利点は以下の通りだ：

• 3つの方向が相互に依存せず、待機時間が発生しない
• すべて読み取り専用のため、ファイル競合が発生しない
• メインスレッドは結果待ちの間もプロジェクト構造の分析や独自の判断が可能

起動から3つの結論を得るまでの体感時間は数分レベルだ。プロジェクト自体が小さいため、節約されるのは「ファイル読み取りの絶対時間」ではなく、メインスレッドが3種類の問題（ランタイム障害、テスト不足、モジュール分割の要否）を同時に記憶する必要がなくなるという負荷軽減だ。この負荷軽減は数分のタスクでは強く感じないが、タスク規模が大きくなると顕著になる。

3つのSubagentの結論の中で、runtime-risk-agentが最も価値が高い。handleRequest内の非同期ルートでawaitが欠落していること、外側のtry/catchが非同期ハンドラーの例外を捕捉できていないことを発見した。この種のバグはハッピーパステストでは検出できず、発生するとリクエストがハングアップするか未処理の例外となる。さらに/api/rewriteではbriefの存在のみを判断し、品質チェックが欠落していることも指摘した。これらの発見は後の変更リストに直接反映された。

qa-coverage-agentが列挙した不足点も実用的だ：無効なJSON、未共有状態のshare、早すぎるフォローアップ、弱いbriefによるrewrite回避など、主にハッピーパス以外のAPI負のパスだ。これらすべてを即座に修正する必要はないが、問題点が一目瞭然となる。

architecture-agentは最も判断に迷わせる結果だった。src/app.jsの責任が多すぎること、src/audit.jsをpage-extract/checks/brief/rewriteの4つに分割すべきこと、フロントエンドとバックエンドでaudit labelとbrief readyの判断を重複管理していることを指摘した。判断は正しいが、当時のタスク（テスト作成+バグ修正）にとっては規模が大きすぎる。この段階でコアファイルを変更するとリスクが拡散するため、この提案は一切採用せず、次回の課題として記録した。

3つのSubagent間で直接的な矛盾はなかったが、優先順位が異なっていた：runtime-riskはサーバーサイドの修正、qa-coverageはテスト追加、architectureは境界整理を優先したかった。メインスレッドの役割は3票を平均化することではなく、確定性が高く変更範囲が小さくテストで固定できる問題を優先することだ。

最終的に実施した修正は以下の通りだ：

• 非同期ルート分岐にawaitを統一し、外側のエラーハンドリングを有効化
• /api/rewriteでbriefReady(record.brief)のチェックを必須化
• /api/brief/follow-upに「brief未提出」と「無効なフィールド」の2種類のバリデーション追加
• readJsonにbodyサイズ制限を追加し、無効なJSONには400エラーを返却
• node:testによる回帰テストを追加し、状態フローを固定

検証を実行：

npm run check
npm test

最も興味深い瞬間は、runtime-risk-agentが非同期ハンドラーのバグを報告すると同時に、qa-coverage-agentがAPI負のパステストの追加を提案したことだ。2つの結論を組み合わせることで、完全な修正方案が得られた。一方が問題点を指摘し、もう一方がその再発防止策を提示する形だ。メインスレッドはプロジェクト全体を再レビューする必要がなく、この問題を今修正する価値があるかを判断し、コード変更・テスト追加・検証を実行するだけで済んだ。

これがSubagentの本質的な役割だ。メインスレッドの代わりに判断を行うのではなく、複数の方向の結論を同時に提示し、メインスレッドの意思決定を高速化する。

実行後の管理方法

Codex CLIでは/agentコマンドでエージェントスレッドの表示・切り替えが可能だ。コマンドだけでなく、自然言語で特定のSubagentの停止や完了済みスレッドの閉鎖を指示することもできる。

初心者が覚えるべき基本コマンドは以下の通りだ：

/agent

エージェントスレッドの表示と切り替え。

パフォーマンス分析担当のSubagentを停止してください。

特定のサブタスクが逸脱した場合や不要になった場合に直接停止。

完了済みのエージェントスレッドを閉鎖してください。

完了したスレッドは不要なため、こまめに整理する。

初心者向け練習手順

最初から5つのエージェントでプロジェクト全体を変更するのは推奨しない。リスクの低い段階から練習を開始すべきだ：

1. 並列読み取り：複数のSubagentに異なるモジュールの理解を担当させ、最終的な統合は自身で行う
2. 並列レビュー：バグ/セキュリティ/テスト/保守性を分離して検査
3. 単一変更＋複数レビュー：メインエージェントまたは1つのワーカーがコードを変更し、他のSubagentがレビュー
4. 小規模な並列変更：モジュール境界が明確になったら、複数のワーカーに異なるモジュールを同時変更させる

次にCodexでPRレビューを行う際は、以下のテンプレートを試してみてほしい：

3つのSubagentで現在のPRを並列検査してください：
1つはバグを、1つはテストを、1つは保守性を確認。
すべて完了後にリスクレベル別に統合して報告してください。

このチュートリアルを読んだら、実際のプロジェクトで体験してみることをお勧めする。