Codex CLIサブエージェント並列ワークフロー完全ガイド

⚡ 3秒でわかる！この記事のポイント

Codex CLIのサブエージェント機能で複数タスクを並列実行し、開発速度を2〜5倍に向上
PRレビューを5エージェントで分担（セキュリティ・品質・テスト・保守性・パフォーマンス）
カスタムエージェント定義（TOMLファイル）でチーム向けの再利用可能なワークフローを構築

「大規模なプルリクエストのレビューに何時間もかかる」「リファクタリングしたいファイルが多すぎて手が回らない」——こうした課題を抱えるエンジニアに、Codex CLIのサブエージェント機能が解決策を提供します。

結論から言えば、Codex CLIのサブエージェント並列ワークフローを使えば、従来1人で数時間かかっていた作業を複数エージェントに分担させ、大幅に効率化できます。

この記事はOpenAI Codex CLI完全攻略シリーズの第3回として、サブエージェント並列ワークフローの構築方法を実践的に解説します。

この記事でわかること

サブエージェントのアーキテクチャと基本操作
PRレビューの並列分担ワークフロー
大規模リファクタリングの並列分割手法
カスタムエージェント定義の書き方
MCP Server連携による高度なオーケストレーション

Codex CLIサブエージェントとは？

単一エージェントの限界と並列の利点

通常のCodex CLI操作では、1つのエージェントがタスクを順番に処理します。しかし大規模プロジェクトでは、以下の課題が発生します：

PRレビュー: 数百行の差分を1つの視点で見るため見落としが起きやすい
リファクタリング: 複数ファイルの変更を逐次処理すると時間がかかる
テスト生成: 多数のモジュールに対するテスト作成が遅い

サブエージェントはこれらの課題を並列処理で解決します。メインエージェントがタスクを分割し、複数のサブエージェントに同時に指示を出すことで、処理時間を1/Nに短縮できます。

サブエージェントのアーキテクチャ概要

メインエージェント（オーケストレーター）
  ├── サブエージェント #1: セキュリティレビュー
  ├── サブエージェント #2: コード品質チェック
  ├── サブエージェント #3: テストカバレッジ分析
  └── サブエージェント #4: パフォーマンス評価

各サブエージェントは独立したサンドボックス環境で動作し、結果をメインエージェントに返却します。メインエージェントが結果を統合し、最終的なレポートを生成する流れです。

Codex CLIの基本操作をまだ把握していない方は、Codex CLI入門ガイドを先にご覧ください。

サブエージェントの基本操作

`/agent` コマンドの使い方

Codex CLI内で /agent コマンドを使ってサブエージェントを起動します：

# 新しいサブエージェントを起動
/agent spawn "このPRのセキュリティ面をレビューして"

# 名前付きで起動
/agent spawn --name security-reviewer "OWASP Top 10の観点でコードをレビュー"

エージェントスレッドの管理（切替・停止・クローズ）

# アクティブなエージェント一覧
/agent list

# 特定のエージェントに切り替え
/agent switch security-reviewer

# エージェントを停止
/agent stop security-reviewer

# 全エージェントの結果を収集
/agent collect

`agents.max_threads` 等の設定項目

codex.toml で並列数やタイムアウトを設定できます：

[agents]
max_threads = 5          # 最大同時エージェント数
timeout_seconds = 300    # タイムアウト（秒）
sandbox_mode = "strict"  # サンドボックスモード

Codex CLIサブエージェント並列ワークフローのアーキテクチャ図

実践①：PRレビューを5エージェント並列で実行

セキュリティ・コード品質・テスト・保守性の分担

大規模PRを5つの観点から並列レビューする例です：

# メインエージェントからの指示
PR差分を5つの観点から並列レビューしてください：

1. セキュリティ: SQLインジェクション、XSS、認証認可の問題
2. コード品質: 命名規約、DRY原則、複雑度
3. テスト: テストカバレッジ、エッジケース、モックの適切性
4. パフォーマンス: N+1クエリ、メモリリーク、不要な再レンダリング
5. 保守性: ドキュメント、型定義、エラーハンドリング

Claude CodeのPRレビュー自動化に興味がある方は、Codex CLIコードレビューも参考になります。

結果の統合とサマリー生成

各エージェントの結果はメインエージェントが自動的に統合します：

## PRレビュー結果サマリー

### 🔴 Critical（即対応必要）
- [セキュリティ] user_controller.py:45 - SQLインジェクションの脆弱性

### 🟡 Warning（対応推奨）
- [パフォーマンス] order_service.py:120 - N+1クエリの可能性
- [テスト] auth_test.py - 異常系テストが不足

### 🟢 Info（参考情報）
- [保守性] README.mdの更新が必要
- [品質] utils/helper.ts の関数分割を検討

実践②：大規模リファクタリングの並列分割

ファイル群をエージェントごとに分担

100ファイルのリファクタリングを5エージェントに分担させる例：

# リファクタリング対象をディレクトリ単位で分割
/agent spawn --name refactor-api "src/api/ 配下のファイルをTypeScript strict modeに移行"
/agent spawn --name refactor-models "src/models/ 配下のクラスをinterface + factoryパターンに変更"
/agent spawn --name refactor-utils "src/utils/ 配下の関数にJSDoc型注釈を追加"
/agent spawn --name refactor-hooks "src/hooks/ 配下のカスタムフックを汎用化"
/agent spawn --name refactor-tests "tests/ 配下のテストをVitestの記法に統一"

コンフリクト回避のベストプラクティス

並列リファクタリングで最も注意すべきはファイルの競合です：

ディレクトリ単位で分割する（同じファイルを複数エージェントが触らない）
共有ファイルは最後に統合する（型定義ファイル、設定ファイルなど）
段階的にコミットする（エージェントごとにブランチを分けてマージ）

# エージェントごとにブランチを作成
/agent spawn --name refactor-api --branch refactor/api "..."
/agent spawn --name refactor-models --branch refactor/models "..."

カスタムエージェント定義（TOMLファイル）

プロジェクトスコープ vs パーソナルスコープ

カスタムエージェントはプロジェクト単位（.codex/agents/）またはユーザー単位（~/.config/codex/agents/）で定義できます。

# .codex/agents/security-reviewer.toml
[agent]
name = "security-reviewer"
description = "OWASP Top 10の観点でコードセキュリティをレビュー"

[agent.instructions]
system = """
あなたはセキュリティ専門のコードレビュアーです。
OWASP Top 10の各項目を基準にコードを評価し、
脆弱性の深刻度（Critical/High/Medium/Low）を判定してください。
"""

[agent.settings]
model = "o3-mini"
timeout_seconds = 180
sandbox = "strict"

モデル・指示・タイムアウトの設定

タスクの性質に応じてモデルを使い分けることで、コストと品質のバランスを最適化できます：

エージェント種別	推奨モデル	理由
セキュリティレビュー	o3	高精度な推論が必要
コード品質チェック	o3-mini	パターンマッチングが主
テスト生成	o3-mini	定型的な生成タスク
設計レビュー	o3	複雑な判断が必要

上級テクニックはCodex CLI上級テクニックでも解説しています。

MCP Server × Agents SDKで高度なオーケストレーション

Codex CLIのエージェント機能はMCP（Model Context Protocol）Serverと組み合わせることで、さらに高度なワークフローを構築できます。

# MCP Server経由で外部ツールと連携
/agent spawn --mcp-server github "GitHubのPR #123のレビューコメントを分析して改善案を提示"
/agent spawn --mcp-server sentry "直近24時間のエラーログから、今回のPRに関連する問題を特定"

Agents SDKを使えば、Pythonスクリプトからプログラマティックにエージェントをオーケストレーションすることも可能です：

from codex_sdk import Agent, AgentTeam

team = AgentTeam()
team.add(Agent("security", model="o3", instructions="セキュリティレビュー"))
team.add(Agent("quality", model="o3-mini", instructions="コード品質チェック"))
team.add(Agent("tests", model="o3-mini", instructions="テストカバレッジ分析"))

results = await team.run_parallel(context=pr_diff)
summary = await team.synthesize(results)