Agent Teams 編：12 体のサブエージェント構成とマルチエージェント並列協調

🤝 AI 時代の開発は「シングル AI」では回らない

AI コーディングツールを「1 体の巨大 AI に全部任せる」使い方には明確な限界があります。

• コンテキストが重くなり、判断が雑になる
• 観点が重複し、同じ指摘が繰り返される
• すべての判断をメインが抱え、wall-clock が伸びる

解決策は、責務を分けた複数のサブエージェントを、並列・直列で組み合わせて協調させることです。シリーズ最終回となる本記事では、CTS-EC の 12 体のサブエージェント構成と並列起動パターンを解説します。

🧑‍🤝‍🧑 12 体のサブエージェント一覧

CTS-EC の .claude/agents/ には以下の 12 体が配備されています。役割ごとに model とツールを使い分けています。

モデル選定の指針

複雑度と速度・コストを天秤にかけ、「常に Opus」は選ばないのがポイントです。

📏 責務マトリクス：code-reviewer と implementation-validator の観点分離

2026-04-18 の責務分割改訂で、 code-reviewer と implementation-validator の観点重複を完全排除 しました。これで並列実行が可能になっています。

観点が重複しない = 並列実行可能 になり、wall-clock が約 1/2 に短縮されました。

🪢 並列起動パターン 5 種

CTS-EC では .claude/skills/parallel-execution/ で 5 つの並列起動パターンを定型化しています。

パターン 1: Review 並列

/pre-push の中核です。責務マトリクスに従い観点重複がないため、 同時起動 できます。

code-reviewer + implementation-validator を同じメッセージ内で起動
  → TDD/DDD/SOLID/ルール と 完全性/規約/セキュリティ を同時チェック
  → wall-clock 約 1/2

パターン 3: Research 並列（調査）

不確実なテーマを調査する際、1 Agent が 1 キーワードを担当します。

例: Yahoo API の仕様調査
  Agent A: context-preparer("Yahoo OAuth スコープ")
  Agent B: context-preparer("Yahoo 商品登録 API 制限")
  Agent C: context-preparer("Yahoo カテゴリ体系")

3 並列で 3 つの軸を同時に探索できます。

🔁 直列実行が必要なケース

以下の場合は 直列で実行します。並列化してはいけません。

💾 memory: project でエージェントに「学習」を持たせる

一部のエージェントは memory: project を宣言しています。プロジェクト単位でレビュー傾向や過去指摘を記憶します。

---
name: doc-reviewer
model: claude-sonnet-4-6
memory: project
---

memory を持つ 5 体

• code-reviewer
• doc-reviewer
• implementation-validator
• test-runner
• design-reviewer

同じ指摘を 2 回しない ためのしくみで、レビューの質が時間と共に向上します。記憶は .claude/agent-memory/[agent-name]/ に保存されます。

🧰 permissionMode の使い分け

エージェントによって permissionMode を変えています。

dontAsk は「破壊的操作をしない & 結果が要約で返る」エージェントにのみ許可します。並列起動時に毎回確認プロンプトが出ると並列性が台無しになるためです。

🎯 tools 制限で暴走を防ぐ

各エージェントに付与するツールは 最小限に絞ります。

code-reviewer に Write を与えないのが重要です。レビューは 指摘のみ を返し、修正はメインが行います。

🧱 /pre-push は「エージェント指揮官」

/pre-push は単独の検証ではなく、複数エージェントを統合指揮するコマンドです。

Step 1: ブランチ確認
   ↓
Step 2: 未コミット確認
   ↓
Step 3: test-runner（スタンプ最新ならスキップ）
   ↓
Step 3.5: ドキュメントのみ判定
   ↓
Step 4: code-reviewer     ┐
                          ├─ 観点重複なし → 並列起動可
Step 5: implementation-validator ┘
   ↓
Step 6: スタンプ発行

Step 4 / 5 は 2026-04 から並列起動に変更され、push 前ゲートの wall-clock が半減しました。

🕰️ ScheduleWakeup で長時間タスクを並列処理

mutation-tester のような長時間タスクは バックグラウンド実行 + ScheduleWakeup で扱います。

mutation-tester を run_in_background で起動
   ↓
ScheduleWakeup(delaySeconds: 1800)  ← 30 分後に戻る
   ↓
（その間にメインは別作業を進める）
   ↓
起床 → TaskOutput で結果確認

delaySeconds は 300 秒を避け、270 秒（5 分 TTL 内）か 1200〜1800 秒（cache 再構築を諦めて長く寝る）の二択が定石です。

🧑‍💻 Claude Code Agent Teams（実験的機能）

ここまでの 12 体は .claude/agents/ に定義し、メインが Agent ツールで呼び出す 「下請け型」のサブエージェント でした。Claude Code v2.1.50 以降では、さらに Agent Teams という実験的機能が追加されました。複数の Claude インスタンスを tmux split-pane で並列に走らせ、Teammate として協調 させる機能です。

🛡️ 前提：DevContainer + bypassPermissions は必ずセットで

Agent Teams を有効活用するには、各 Teammate に bypassPermissions（確認プロンプトの完全スキップ） を与えないと、Lead が承認待ちで止まるたびにチーム全体が停滞します。ただし bypassPermissions は 極めて危険 です。AI が無確認で rm -rf や git push --force を実行しかねません。

そのため CTS-EC では以下を徹底します。

• bypassPermissions は必ず DevContainer 環境でのみ有効化する（ホスト OS 直下で実行しない）
• DevContainer の workspaceMount を当該プロジェクトに限定し、ホスト全体を見えなくする
• .claude/settings.json の deny リスト（rm -rf /* / git push --force* / terraform destroy* など）は DevContainer 内でも残す
• git config --global --add safe.directory をプロジェクト限定にし、他リポジトリに波及しないようにする

「DevContainer の中だから壊れても捨てれば良い」という前提が bypassPermissions の安全性を支えます。

🖥️ VS Code 拡張は不安定。CLI（PowerShell）から入る

VS Code の Claude Code 拡張から Agent Teams を起動すると、 tmux の pane が拡張側のターミナルと競合して不安定 になります。CTS-EC の運用では、PowerShell から直接 DevContainer に入るフローを推奨しています。

# 1. PowerShell から DevContainer コンテナに入る
docker exec -it -u vscode cts-ec_devcontainer-devcontainer-1 bash

# 2. ロケールを UTF-8 に設定（日本語表示崩れ対策）
export LANG=ja_JP.UTF-8

# 3. tmux セッションを開始
tmux new -s claude

# 4. その中で Claude Code を起動（bypassPermissions 有効）
claude --dangerously-skip-permissions

VS Code から開いた統合ターミナルではなく、独立した PowerShell ウィンドウで実行するのがポイントです。

🚩 bypassPermissions を有効化するフラグ

claude の起動時に --dangerously-skip-permissions を付けると、セッション全体が bypassPermissions モード になり、Teammate も含めた全確認プロンプトがスキップされます。

CTS-EC では DevContainer の post-create.sh にエイリアスを仕込み、DevContainer 内だけ claude を bypass に寄せる運用にすると事故が減ります。

# post-create.sh（DevContainer 内でのみ反映）
echo "alias claude='claude --dangerously-skip-permissions'" >> ~/.bashrc

⚠️ ホスト OS の .bashrc / .zshrc にこのエイリアスを書いてはいけません。DevContainer の隔離が無意味になります。

⚙️ Agent Teams 有効化設定

~/.claude/settings.json に環境変数とモードを設定します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

DevContainer では devcontainer.json の customizations に同等の設定を追加します。

{
  "customizations": {
    "vscode": {
      "settings": {
        "claudeCode.env": {
          "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
        },
        "claudeCode.teammateMode": "tmux"
      }
    }
  }
}

tmux は post-create.sh でインストールしておきます。

# post-create.sh
echo "Installing tmux..."
sudo apt-get update \
  && sudo apt-get install -y tmux \
  && sudo rm -rf /var/lib/apt/lists/*

🖼️ 3 つの表示モード

本格的に使うなら Split-pane（teammateMode: "tmux"）が圧倒的に見やすく、Teammate ごとの pane で状況把握が容易になります。

⌨️ キーボード操作

In-process モード:

Split-pane モード（tmux）:

別ターミナルから Teammates の tmux セッションを覗くには、起動時に表示されるセッション ID を使います。

# 別ターミナルから（セッション ID は claude 起動時に表示）
tmux -L claude-swarm-XXXX a

💰 推奨構成とコスト

Claude Max プラン内で完結させるのがコスト最適解です。

Lead:        Sonnet 4.6（プラン内）
├─ Teammate A: Sonnet 4.6（プラン内）
├─ Teammate B: Sonnet 4.6（プラン内）
└─ Teammate C: Sonnet 4.6（プラン内）

• Sonnet 4.6 は Opus 4.5 相当の性能を持つ
• Opus 4.6 は複雑な設計・図生成時のみ使用（Extra Usage 発生に注意）
• 全員 Sonnet 4.6 なら Max プラン枠内に収まりやすい

📊 トークン消費の目安

wall-clock は大幅に短縮されますが、合計トークンは Teammate 数にほぼ比例 します。軽量タスクには過剰投資なので、L 規模のリファクタ・広域調査など wall-clock が効く場面を選びます。

💬 自然言語での指示例

このモノレポのテストカバレッジが低い。ec-api、ec-pwa、egazo-product-job の
ユニットテストをチームで分担して書いて。TDD 厳守。

この MR をセキュリティ、パフォーマンス、テストカバレッジの観点から
チームでレビューして。

Yahoo Shopping API 連携で在庫同期が時々失敗する。
原因を複数の仮説でチームで調査して。

🎛️ Delegate Mode（委譲モード）

Shift + Tab で有効化すると、 Lead は調整専用になり、実装作業を行わなくなります。

• Lead のコンテキスト消費を抑制
• Teammates に作業を完全委譲
• 大規模チーム（4 人以上）で特に有効

指示例：

ec-api、egazo-product-job、ec-pwa のリファクタリングをチームで分担して。
Delegate Mode で。TDD 厳守。

🌐 環境制限

Windows 環境では WSL + DevContainer + tmux のスタックが唯一安定するパターンです。

⚠️ 既知の制限

• セッション再開で Teammates は復元されない（都度 tmux new -s claude からやり直し）
• 同じファイルの同時編集にファイルロックはない（Teammate 間でコンフリクトしうる）
• Lead が実装を始めてしまう場合は Delegate Mode を使用
• 4 人以上のチームでは tmux コマンドが不安定になる場合あり

🔧 トラブルシューティング

tmux セッションが見つからない:

tmux ls                              # セッション確認
tmux -L claude-swarm-XXXX list-sessions  # 特定ソケットのセッション確認

no server running エラーは チームが正常終了した証拠 です。

Teammates が承認待ちで止まる:

Lead の pane に移動して y または Enter で承認。一括自動承認にしたい場合は Lead に直接指示します。

全ての Teammate のファイル編集を自動承認して

これを常態化するのは危険なので、DevContainer 前提かつ信頼できるタスク（テスト実装・ドキュメント整備など）に限定します。

tmux がインストール後に認識されない:

Claude Code を再起動してください。

exit              # claude 終了
tmux new -s claude
claude

🧭 Team 運用チェックリスト

• 12 体のエージェントに責務マトリクスが明記されている
• 観点が重複する 2 体を並列起動していない（責務分割を確認）
• dontAsk を与えているのは安全なエージェントのみ
• Write を持つエージェントは必要最小限
• memory: project は学習価値のあるエージェントに限定
• /pre-push に新しい検証を追加するときは、既存エージェントと観点が重複しないか確認
• 長時間タスクは ScheduleWakeup で wall-clock を短縮
• Agent Teams（tmux split-pane）は DevContainer 内 でのみ有効化
• bypassPermissions を使う場合、ホスト OS 直下では実行しない
• VS Code 統合ターミナルではなく PowerShell から docker exec で入る

⚠️ マルチエージェント運用でやってはいけないこと

• 観点が重複する 2 体を並列起動する（指摘が重複・矛盾する）
• すべてのエージェントに Opus 4.7 を割り当てる（コスト爆増）
• code-reviewer に Write を与える（レビューと修正が混ざる）
• 直列依存があるのに並列化する（前段の結果を後段が使えない）
• dontAsk を乱発する（誤操作時にユーザーが気づけない）
• 300 秒の ScheduleWakeup を選ぶ（5 分 TTL の cache が微妙に切れる）
• ホスト OS 直下で bypassPermissions を有効化する（DevContainer 必須）
• VS Code 統合ターミナルで tmux split-pane を使う（拡張と競合して不安定）
• Agent Teams でファイルロックに頼る（Teammate 間の同時編集はコンフリクトしうる）

📚 シリーズ記事

🔗 関連記事

• Claude Code ベストプラクティス — .claude/ 全体の運用
• 品質ゲート編 — エージェントが担う各品質ゲート
• Claude Code 7層ハーネスエンジニアリング — ハーネス視点からのエージェント協調

📖 関連用語

• tmux — Agent Teams の split-pane モードで使う端末多重化ツール
• コンテキストエンジニアリング — マルチエージェント運用の設計思想
• ハルシネーション — 並列起動時にレビュー観点で検出する失敗モード