Agent Teamスキルを3つ作って見えた「収束型マルチエージェント」の設計原則

「仮説を1つずつ潰す」が遅すぎる問題

複雑なバグ調査やコード監査を単一エージェントに任せると、仮説を逐次検証するしかない。仮説Aがハズレ → Bを検証 → ハズレ → C...。しかも調査中に「この挙動、別の仮説の方が怪しいぞ」と気づいても、方向転換が難しい。

• 探索空間が広いバグほど、逐次調査のコストが膨らむ
• セキュリティとパフォーマンスを1回のレビューで全部見るのは無理がある
• インシデント対応で「1つずつ」は致命的に遅い

worktree並列開発のような「パイプライン型」は各タスクが独立していることが前提。でも調査系の問題は途中の発見が他の調査ラインに影響する。ここに「収束型」パターンの出番がある。

Agent Teamの仕組みと「なぜこれを選んだか」

Claude CodeのAgent Teamは3つのツールで構成される。

ツール	役割
TeamCreate	チーム編成・メンバー起動
SendMessage	メンバー間のリアルタイム通信
TaskList	共有タスクボードの参照

Taskサブエージェントとの違いはSendMessageにある。タスクツールは親→子の一方通行で、結果を受け取ってから次を起動する。Agent Teamはメンバー間で自由にDMできるので、「ログでDB遅延を発見」→「コード担当、その前後のデプロイ差分を確認して」というリアルタイムの方向転換ができる。

自分がTaskツールではなくAgent Teamを選んだ判断基準はシンプルで、「途中の発見が他のタスクに影響するか？」。Yesなら収束型一択。

bug-hunt: 並列仮説検証の実装

最初に作ったAgent Teamスキルが/bug-hunt。チーム構成はこう。

hunt-lead（リーダー）
├── investigator-1（調査員1）
├── investigator-2（調査員2）
└── fix-proposer（修正担当）

ワークフローは4フェーズ。hunt-leadが仮説を3〜5個生成し、investigatorが並列で検証。investigator-1が「nullチェック抜け」を発見したら、SendMessageでhunt-leadに報告。hunt-leadは「investigator-2は同じパターンが他にもないか確認して」と方向転換を指示する。

状態管理はシェルスクリプトで仮説をJSONに永続化する。

# 仮説を追加
hunt-state.sh add-hypothesis \
  --id "h1" \
  --description "認証トークンの有効期限切れ" \
  --assignee "investigator-1"

# 仮説を確定
hunt-state.sh update-hypothesis \
  --id "h3" \
  --status "confirmed" \
  --evidence "キャッシュのTTL設定が本番だけ0秒になっていた"

auto-compactが走ってもcat state.jsonで復帰できる。SendMessageの内容は揮発するが、重要な発見は状態ファイルに残る設計にした。

なぜこう書くか

状態管理をJSONファイルにした理由は、Agent Teamのコンテキストが揮発するから。SendMessageで伝えた情報はcompact後に消える。だからDBやRedisではなくファイルに永続化して、cat一発で復帰できるようにした。

もう一つの判断として、fix-proposerは原因確定まで起動しない。4エージェント常時稼働は、1メーターのタクシーに1万円渡すようなもの。hunt-leadが複雑さを判定して、単純なら1エージェント、複雑なら2エージェントと段階的に投入する。

3つ作って見えた4つの設計原則

bug-hunt、code-audit-team、incident-responseの3スキルを作る中で、共通する原則が見えてきた。

1. リーダーは判断に専念する — リーダーは自分では調査しない。報告を受けて方向転換を指示し、収束を判定する。サッカーの監督がピッチに立たないのと同じ。

2. 状態はファイルに永続化する — SendMessageの内容は揮発する。重要な発見は状態ファイルに記録して、compactに耐える設計にする。

3. 不要なメンバーは早期シャットダウン — config-analystが「変更なし」を確認したら即解散。全員最後まで走らせる必要はない。コストはメンバー数 × ターン数に比例する。

4. --max-turnsでコスト上限を設定 — バジェット80%消費でワーニング、100%で強制収束。「朝起きたらトークン使い切ってた」は笑えない。

まとめ: 自分はこう使い分けている

判断基準	パイプライン型	収束型（Agent Team）
タスクの独立性	高い	低い（結果が相互依存）
成果物	コード（PR）	分析レポート・修正案
向いている場面	機能実装	バグ調査、監査、インシデント

迷ったら「タスクをファイル単位で分割できるか？」を最初に考える。できるならパイプライン型。途中の発見が他に影響するなら収束型。分からなければまず単一エージェントで試して、行き詰まったらAgent Teamを検討する。

---

元記事

この記事は 【Claude Code】バグ調査・コード監査を並列で回すAgent Team協調設計 — 収束型マルチエージェントの実装パターン のコア部分を再構成したものです。元記事ではさらに：

• code-audit-teamのホットスポット検出とクロスドメインのスコアリング式
• incident-responseのタイムライン構築と調査ライン間の連携フロー
• 3スキルそれぞれのチーム構成・フェーズ設計の詳細比較

を扱っています。

---

この記事は playpark Blog からの転載です。