1つのAIエージェントから2つに移行するときに壊れるパターン — 役割分担・引き継ぎ文書・検証ゲート・実際の失敗事例。

1エージェントのユーザーが2つ以上を組み合わせ始めたときに最初に壊れるのは、コンテキストを共有しているという前提だ。人間は Slack・ミーティング・隣に座ることでギャップを埋める。エージェントにはそれができない。委任は約束としてではなく、コードで強制されるゲートとして 表現されなければならない。

このガイドは、Claude Code（メインエージェント）+ Codex CLI（サブエージェント） を1週間以上運用した中で得られたパターンをまとめたものだ。他の組み合わせ（Cursor + Claude Code、Aider + Claude Code など）にも同じパターンが適用できる。

TL;DR

役割分担 — 分析/計画/指示はOpus（メイン）; 実行はSonnet / Codex（サブ）。同じタスクを両方に渡すと結果が乖離する。
引き継ぎ文書を書く — Slackメッセージではなく。別のエージェントがそこから読んで作業を完結できる自己完結型のドキュメント。
検証ゲートをコードとして束ねる — npm run verify:{phase} スクリプト + CIチェック。ゲートなしではギャップが蓄積する。
エージェントごとに1タスク — サブの結果を盲目的に信頼しない。マージ前にメインが再実行する。

マルチエージェントを使う理由

多くのタスクには1つのエージェントで十分だ: 1ファイルの編集、短いリファクタリング、コードレビュー。マルチエージェントが勝るのは以下のケースだ:

並列化できる独立した作業 — フロントエンド + バックエンド + マイグレーションを同時進行
モデル別の分担 — 推論（Opus）と実行（Sonnet/GPT）をコスト/速度で分割
コンテキスト分離 — 大きなコードベースでメインエージェントのコンテキストウィンドウを保護
独立した検証 — 作成者と検証者を分けることで客観性が生まれる

逆に損になるケース:

作業が1つのファイルに集中する — マージコンフリクトで連携のメリットが消える
コンテキストが非常に小さい — 引き継ぎ文書を書く時間が作業時間を超える
仕様が曖昧 — 2つのエージェントが異なる解釈で乖離する

1. 役割分担 — 誰が何をするか

よくある間違いは「両方に同じ仕事をさせる」ことだ。結果が乖離し、誰も責任を持たなくなる。

推奨分担:

役割	モデル / ツール	担当
メイン（アーキテクト）	Claude Opus（Claude Code）	分析・計画・指示・引き継ぎレビュー・マージ判断・ドキュメント
サブ（ビルダー）	Claude Sonnet サブエージェントまたはCodex CLI	CLI実行・ビルド・テスト・繰り返し作業・Explore（ファイル検索）
レビュアー	（オプション）別のSonnetインスタンスまたは人間	結果の再現・差分レビュー・ゲート確認

1人が両方を動かす場合でも、セッションを分割してください。メインが自分のコンテキストで自分の結果を検証すると客観性が失われる。

メインだけがやること

計画 + トレードオフ評価 + 代替案の比較
意思決定の「なぜ」をドキュメント化
引き継ぎ文書を書く
マージ前にサブの結果を検証（再実行、ゲートのraw output確認）

サブだけがやること

明確に定義されたタスク — 入力/出力/受け入れ条件が引き継ぎで明示されている
繰り返しのCLI作業（ビルド、テスト、マイグレーション実行）
大きなコードベースのgrep/find — メインのコンテキストを保護

両方にさせてはいけないこと

「どうやるか考えて教えて」— 2つの異なる答えを調整することになる
「コードを書いて自分で検証して」— セルフレビューは盲点を見逃す

2. 引き継ぎ文書パターン

引き継ぎとは 別のエージェントがそこから読んで作業を完結できる自己完結型のドキュメント だ。Slack メッセージや短いプロンプトではない。

必須セクション

# Phase X — {タイトル}
 
## ゴール
{1文: 何が完成するか}
 
## コンテキスト
- 関連ファイル: `src/foo.ts:42`、`tests/foo.test.ts`
- 先行作業: PR #123マージ済み、RFC-005採用
- 外部依存: APIスペック `docs/api.md` v2
 
## スコープ
1. {ファイルA}の{関数B}のシグネチャを変更
2. {ファイルC}に新しい関数Dを追加
3. {ファイルE}の4つのテストを更新
 
## 非ゴール
- {魅力的な拡張}はしない（次のPhaseの作業）
- {リファクタリングの誘惑}はしない（別PR）
 
## 受け入れ条件
- [ ] `npm run verify:phase-X` が通る
- [ ] `npm run typecheck` がクリーン
- [ ] PR差分が300行未満（大きい場合は分割）
 
## 検証コマンド
\`\`\`bash
npm run verify:phase-X  # Phase固有のゲート
npm test src/foo        # ユニットテスト
\`\`\`
 
## 行き詰まったとき
- 同じエラーに3回当たったら報告（無限ループしない）
- 外部APIが想定と異なる場合は報告（フェイクレスポンスを作らない）
 
## 作成者 / 日付
csmarch · 2026-05-12

コア原則

自己完結 — 引き継ぎだけから作業できること。「Slackで話した件」は無効
スコープと非スコープの両方を明示 — 善意のスコープクリープをブロック
受け入れ条件はコードとして — 「動けばOK」を npm run verify:phase-X ゲートに置き換える
行き詰まり報告ルール — セルフデバッグ時間に明示的な制限を設ける

引き継ぎの長さはタスクの規模に比例する。1行の修正に100行の引き継ぎは無駄だ。5ファイル以上または新モジュール → 引き継ぎ必須; 1〜2ファイルのバグ修正 → 1行チャットでOK。

3. 検証ゲート — 約束をコードに

最も多く、最もコストの高い間違い: 「マージ後に検証する。」

サブが完了と報告すると、メインが信頼して次のPhaseへ進む。次のPhaseで何かが壊れると、遡って調査する。ギャップが蓄積して最終的に大きなキャッチアップとして爆発する。

原則: 検証スクリプトとマージゲートを引き継ぎと同じPRに束ねる。

3つのゲート

ローカル検証スクリプト — npm run verify:phase-X または npm run verify:auth、タスクごとのジョブ
CIゲート — GitHub Actions / GitLab CIが verify:phase-X を自動実行。失敗するとマージブロック
メインの再実行 — メインがサブの結果を自分の環境で再現。同じ結果 → マージ

例 — verify:phase-X スクリプト

// package.json
{
  "scripts": {
    "verify:phase-A": "tsc --noEmit && eslint src/phase-a && jest src/phase-a --coverage",
    "verify:phase-B": "...",
    "verify:assets": "node scripts/check-asset-sha256.mjs"
  }
}

GitHub Actions ゲートの例

# .github/workflows/ci.yml
name: CI
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
      - run: pnpm verify:assets   # Phaseの検証も同様のパターン

サブの完了報告フォーマット

サブがPhaseの完了を報告するとき、以下を添付する:

[Phase X 完了]
- 変更ファイル: 5件（src/foo.ts、...）
- verify raw output:
  $ npm run verify:phase-X
  ✓ tsc クリーン
  ✓ eslint クリーン
  ✓ jest 23件通過
- PR: #234

raw output なしの報告 → 再提出を求める。「動いている」というテキストは信頼しない。

4. エージェントごとに1タスク — 結果を盲目的に信頼しない

サブが完了と報告したらすぐ次に進まないこと。メインは3つのことをする:

再実行 — サブのverify raw outputを信頼せず、メインが同じコマンドをローカルで実行。異なる場合は調査（envの差異? 競合? キャッシュ?）
差分レビュー — 人間レベルのレビュー深度でPR差分を確認。スコープ外の変更・コメントの欠如・テストの欠如を監視
反例を試す — 受け入れ条件を超えて、「これが壊れていないか」を自分で1〜2ケース実行

これはサブの能力を疑っているのではなく — エージェントは根本的に 自分のコンテキストの盲点を見ることができない。人間も自分のコードのレビューで見落とすのと同じだ。

5. 実際の失敗から学んだ教訓

ケース — 引き継ぎはあったが、ゲートがなかった

状況: UIリデザインのPhase Dを委任。引き継ぎに8つの受け入れ項目があった。サブが「全て完了」と報告。メインがマージ。Phase Eを開始。

問題: Phase Dの受け入れ条件#4が実際には通っていなかった（サブが部分的な実装をOKと判断した）。Phase EがPhase Dの機能を使って壊れた。Phase EのデバッグにPhase Dへの遡及が必要だった。同じパターンがFでも繰り返された。

復旧: D〜Fをキャッチアップするための別Phaseで、verify:phase-D スクリプトを遡及的に作成。ゲートが最初からあれば、最初に失敗していたはずだった。

教訓: 検証スクリプトのない受け入れ条件は空約束になる。引き継ぎ + 検証スクリプト + CI ゲートを同じ PR に束ねる。

ケース — セルフ無限ループ

状況: サブに「壊れたテストを修正して」と依頼。サブが自分のコードに対して5つの異なる方法を試し、それぞれ新しいエラーを生む。1時間後: 「いろいろ試したが、動かない。」

問題: 行き詰まり報告ルールがなかった。サブにはいつ助けを求めるかの基準がなかった。

復旧: 引き継ぎテンプレートに「同じエラーに3回当たったらすぐ報告」を追加。メインがより広いコンテキストで別の仮説を提供。

教訓: 引き継ぎに行き詰まりルールを明記する。「試し続ける」→「同じエラーに3回当たったら報告」。

6. オンボーディングチェックリスト

マルチエージェントに移行する最初の1週間:

メインエージェントのペルソナ/ルールを定義 — CLAUDE.mdまたは同等のもの: 役割・自律性・禁止事項・コードスタイル
サブは1つから始める — Codex CLIまたは1つのSonnetサブエージェント。最初から3〜4つはNG
最初の引き継ぎは短く — 1〜2ファイルの作業、2〜3つの受け入れ条件、1つの検証スクリプト
GitHub Actionsに1つの検証ゲートを登録 — Phaseが増えるにつれて追加
行き詰まりルールを適用 — 3回失敗後に報告 + メインがレビュー
各Phase後にレトロ — 欠けていたものを1行メモ。引き継ぎテンプレートは進化する

トラブルシューティング

「引き継ぎが長すぎてやる気が出ない」

タスクが大きすぎる。Phaseを小さく切り分けてください。100行を超えるなら作業が1週間以上かかる。

「サブがスコープ外の作業をしてしまう」

「Non-goals」セクションが欠けているか曖昧だ。「リファクタリングしない」の代わりに「src/legacy/ に触れない」と具体的に書いてください。

「検証スクリプトを書く時間がない」

検証スクリプトはコードを書いた後ではなく、引き継ぎを書いたときに一緒に 書いてください。受け入れ条件の各項目が verify:phase-X の1つのアサーションに対応する。

「2つのエージェントが常に競合する」

コンテキスト分離が失敗している。スコープが重複している。引き継ぎの「スコープ — ファイルリスト」は明確に分離可能でなければならない。同じファイルを2人が編集するのも競合する。

「メインがボトルネックになる」

答えはサブに権限を委譲することではない。メインは検証 + マージ判断を保持する。代わりに、引き継ぎ/ゲートの自動化に投資して 作業量を減らしてください（スコープを小さく、計画をシンプルに）。

参考リンク

Claude Code セットアップ — メインエージェントを先にセットアップ
Anthropic — Claude Code subagents（サブエージェントベストプラクティス）
OpenAI Codex CLI — openai-codex GitHub

変更履歴

2026-05-12: 初版。1週間以上の運用経験を6セクション + 5つのトラブルシューティングにまとめた。

マルチエージェントワークフロー — Claude Code + Codex CLI 連携