「バグの原因、3時間調べてまだ分からない...」
ログを追って、コードを読んで、設定を確認して。1つの仮説を検証して潰して、また次の仮説を立てて。単一エージェントで複雑なバグを調査すると、調査ラインを1本ずつ潰していくしかない。人間でもAIでも、逐次調査は遅い。
「セキュリティとパフォーマンス、両方の観点でレビューしたいけど、1回のレビューで全部見るのは無理がある」...そんな場面に心当たりありませんか？
私たちも同じ壁にぶつかっていました。そこで作ったのが、Agent Team協調型スキルです。複数のAIエージェントが専門分野ごとに並列で動き、発見をリアルタイムで共有しながら答えに収束していく。
この記事で学べること
- Agent Team（TeamCreate / SendMessage）の基本構造と使いどころ
- 「パイプライン型」と「収束型」の設計パターンの違い
- bug-hunt / code-audit-team / incident-response 3つの実装から見える設計原則
- コスト制御と早期シャットダウンの仕組み
前提知識
- Skillsの基本概念を把握している
- 状態管理パターンを理解している
- Claude CodeのTask toolを使ったことがある
この記事で紹介するスキルはすべてGitHubリポジトリで公開しています。手元にコードを開きながら読むと理解しやすいです。
なぜ「チーム」が必要なのか
前回の記事では、worktree並列開発によるパイプライン型の並列化を紹介しました。Issueを分割して、各worktreeで独立に実装して、最後にマージする。これは「分けて、束ねる」パターンです。
でも、世の中には分割できない問題がある。
パイプライン型が通用しない場面
| 場面 | なぜ分割できないか |
|---|---|
| 複雑なバグ調査 | 仮説Aの結果が仮説Bの調査方向を変える |
| マルチドメイン監査 | セキュリティの発見がアーキテクチャの問題を示唆する |
| インシデント対応 | ログの異常とコード変更と設定変更が相互に影響する |
パイプライン型は「各タスクが独立」であることが前提。でも調査系の問題は、途中の発見が他の調査ラインに影響を与える。Aチームの発見を受けてBチームが方向転換する、という動的な連携が必要になる。
これが「収束型探索」パターンで、Agent Teamの出番です。
Agent Teamの基本構造
Claude CodeのAgent Team機能は、3つのツールで構成されます。
| ツール | 役割 | 例え |
|---|---|---|
| TeamCreate | チーム編成・メンバー起動 | プロジェクトの立ち上げ |
| SendMessage | メンバー間のリアルタイム通信 | Slackのダイレクトメッセージ |
| TaskList | 共有タスクボードの参照 | カンバンボード |
Task tool（サブエージェント）との違いを整理しておきます。
| 比較軸 | Task subagent | Agent Team |
|---|---|---|
| 通信方向 | 親→子、子→親（一方通行） | メンバー間で自由にDM |
| 動的調整 | 結果を受け取ってから次を起動 | リアルタイムで方向転換 |
| コンテキスト | 独立（呼び出し時に固定） | SendMessageで随時追加 |
| 適する問題 | 分割可能なタスク | 相互依存のある探索 |
ポイントはSendMessageです。あるエージェントが発見した情報を、別のエージェントに即座に伝えられる。「ログで15:30にDB応答遅延を発見」→「コード担当、15:30前後のデプロイ差分を確認して」。このリアルタイムの情報共有が、逐次調査との決定的な違いです。
実例1: bug-hunt — 仮説ベースの並列バグ調査
最初に作ったAgent Teamスキルが/bug-huntです。
問題意識
単一エージェントでバグ調査すると、仮説を1つずつ潰していくしかない。仮説Aがハズレ → 仮説Bを検証 → ハズレ → 仮説C...。探索空間が広いバグほど、逐次調査のコストが膨らむ。
しかも、仮説Aの調査中に「あれ、この挙動は仮説Bの方が怪しいぞ」と気づいても、今やっている調査を中断して方向転換するのは難しい。
チーム構成
hunt-lead（リーダー）
├── investigator-1（調査員1）
├── investigator-2（調査員2）
└── fix-proposer（修正担当）
| メンバー | 役割 | 動き方 |
|---|---|---|
| hunt-lead | 仮説生成・優先度管理・収束判定 | 調査員から報告を受け、仮説を追加/棄却 |
| investigator-1 | コード調査・仮説検証 | 割り当てられた仮説を検証、発見をリーダーに報告 |
| investigator-2 | 並列調査ライン | 別の仮説を同時に検証 |
| fix-proposer | 根本原因特定後の修正案作成 | 原因が確定してから起動（コスト節約） |
4フェーズのワークフロー
Phase 1: Triage — hunt-leadが症状を分析し、初期仮説を3〜5個生成。
Phase 2: Investigate — investigatorが並列で仮説を検証。ここが面白い部分で、investigator-1が「この関数、nullチェックが抜けてる」と発見したら、SendMessageでhunt-leadに報告。hunt-leadは「じゃあinvestigator-2は、同じパターンが他の箇所にもないか確認して」と方向転換を指示する。
Phase 3: Converge — 証拠が揃ったら、hunt-leadが根本原因を特定宣言。
Phase 4: Propose Fix — fix-proposerが修正コードとテストケースを提案。
状態管理: 仮説の追跡をどうやるか
bug-huntスキルにはhunt-state.shという状態管理スクリプトが同梱されていて、仮説の追加・棄却・確定をCLIから操作できます。
# 仮説を追加
hunt-state.sh add-hypothesis \
--id "h1" \
--description "認証トークンの有効期限切れ" \
--assignee "investigator-1"
# 仮説を棄却
hunt-state.sh update-hypothesis \
--id "h1" \
--status "rejected" \
--evidence "トークンは有効期限内だった"
# 仮説を確定
hunt-state.sh update-hypothesis \
--id "h3" \
--status "confirmed" \
--evidence "キャッシュのTTL設定が本番だけ0秒になっていた"
JSONファイルに永続化されるので、auto-compactが走っても仮説の状態は保持される。状態管理の記事で紹介したパターンと同じ設計思想です。
コスト制御のミソ
単純なバグではinvestigator-1だけ起動する。Agent Teamは便利だけど、メンバー数に比例してトークンを消費します。「nullチェックが抜けてた」レベルのバグに4エージェント投入するのは、1メーターのタクシーに「釣りはいらねぇ」って1万円渡すようなもの（かっこいいけど、ただの浪費）。
hunt-leadがTriageフェーズで問題の複雑さを判定し、単純なら1エージェント、複雑なら2エージェント。--max-turnsでターン上限も設定できるので、予算オーバーの心配もない。
実例2: code-audit-team — 専門家チームのクロスドメイン監査
/code-audit-teamは、セキュリティ・パフォーマンス・アーキテクチャの3ドメインを並列で監査するスキルです。
単一エージェントとの違い
単一エージェントのthink-analyzeでも4ドメイン分析はできていました。でもクロスドメインの発見ができないのが弱点でした。
| 場面 | 単一エージェント | Agent Team |
|---|---|---|
| SQLインジェクション発見 | セキュリティ観点でのみ報告 | sec-auditorが発見 → arch-auditorに「このDBアクセスパターン、他にもある？」 |
| N+1クエリ発見 | パフォーマンス観点でのみ報告 | perf-auditorが発見 → sec-auditorに「キャッシュ導入時のリスクは？」 |
| 認証ロジック散在を発見 | アーキテクチャ観点でのみ報告 | arch-auditorが発見 → sec-auditorに「各箇所の実装差異にセキュリティリスクは？」 |
1つの問題が複数のドメインにまたがる。これはチームでないと見えない。
ホットスポット検出
code-audit-teamの独自機能がホットスポット検出です。同じファイルに対して複数のドメインから指摘が集中したら、そこは重点的に見るべき場所。
# 同一locationへの複数ドメイン指摘を検出
audit-state.sh detect-hotspots
スコアリングの計算式がちょっと面白くて：
優先度 = severity × cross_multiplier / fixability
- severity: Critical=4, High=3, Medium=2, Low=1
- cross_multiplier: 2ドメインから指摘=1.5倍、3ドメイン=2.0倍
- fixability: Easy=0.3, Medium=0.6, Hard=1.0
2ドメインから指摘されたMedium（severity=2）は、2 × 1.5 / 0.6 = 5.0。
1ドメインだけのHigh（severity=3）は、3 × 1.0 / 0.6 = 5.0。
ドメインをまたぐ問題は、単一ドメインの問題より優先度が上がる。これは人間のコードレビューでも「セキュリティとパフォーマンスの両方に影響するなら優先して直そう」と判断するのと同じ感覚です。
--focus で部分起動
「今回はセキュリティだけ重点的に見たい」という場面もある。--focus securityで、sec-auditorだけ起動して他のauditorは省略。全員起動する必要がないときに無駄なトークンを使わない設計です。
実例3: incident-response — 時間勝負のインシデント調査
/incident-responseは、本番障害の調査に特化したAgent Teamスキルです。
インシデント対応で「逐次」は致命的
本番が燃えているとき、調査は時間との戦い。ログを見て→コード変更を確認して→設定を調べて、を1つずつやっていたら、復旧が遅れる。3つの調査ラインを同時に走らせて、発見を即座に共有するのがincident-responseの設計思想です。
チーム構成と調査ライン
incident-lead（指揮官）
├── code-analyst（コード変更分析）
├── log-analyst（ログ・メトリクス分析）
└── config-analyst（設定・インフラ変更分析）
調査ラインの連携例を見てみます。
- log-analystが「15:30からDB応答が急激に遅延」を発見
- → SendMessageでcode-analystに「15:30前後のデプロイ差分を重点確認してほしい」
- code-analystが「15:25のデプロイでインデックスを削除するマイグレーションが含まれていた」を発見
- → SendMessageでlog-analystに「そのテーブルのスロークエリログがあるか確認してほしい」
- config-analystは「設定変更なし」を確認 → 早期シャットダウン（コスト削減）
5番目がポイント。config-analystは「変更なし」を確認した時点で役目が終わる。不要になったエージェントを早期にシャットダウンすることで、トークン消費を抑えています。全員最後まで走らせる必要はない。
タイムライン構築
incident-responseの出力はタイムライン形式。各analystの発見を時系列で並べて因果関係を可視化します。
# タイムラインにイベントを追加
incident-state.sh add-timeline \
--time "2026-04-23T15:25:00" \
--event "デプロイ: マイグレーション実行（index削除含む）" \
--source "code-analyst"
incident-state.sh add-timeline \
--time "2026-04-23T15:30:00" \
--event "DB応答遅延が急増（p99: 200ms → 5000ms）" \
--source "log-analyst"
jqによる自動ソートで、異なるanalystからの報告が時系列順に整列される。**「15:25にインデックス削除 → 15:30にDB遅延」**という因果関係が一目で分かる。
3つのスキルに共通する設計原則
bug-hunt、code-audit-team、incident-responseを作る中で見えてきた、Agent Team設計の4原則です。
原則1: リーダーは判断に専念する
リーダー（hunt-lead / audit-lead / incident-lead）は自分では調査しない。メンバーからの報告を受けて、方向転換を指示したり、収束を判定したりする。サッカーの監督がピッチに立たないのと同じ（立ったら一発退場）。
原則2: 状態はファイルに永続化する
hunt-state.sh / audit-state.sh / incident-state.shで、調査状態をJSONに永続化。SendMessageの内容は揮発するが、重要な発見は状態ファイルに記録する。auto-compactが走ってもcat state.jsonで復帰できる。
原則3: 不要なメンバーは早期シャットダウン
Agent Teamのコストは参加メンバー数 × ターン数に比例します。config-analystが「変更なし」を確認したらシャットダウン。bug-huntで仮説が1つに絞られたらinvestigator-2をシャットダウン。必要なくなったら即座に解散。
原則4: --max-turnsでコスト上限を設定する
全スキルに--max-turnsオプションを実装。バジェットの80%消費時点でワーニングを出し、100%で強制収束。コストの予測可能性は、実運用では必須です。（「Agent Teamが暴走して朝起きたらトークン使い切ってた」は笑えない）
パイプライン型 vs 収束型 — 使い分けの指針
| 判断基準 | パイプライン型（worktree並列） | 収束型（Agent Team） |
|---|---|---|
| タスクの独立性 | 高い（ファイル境界で分離可能） | 低い（調査結果が相互依存） |
| ゴール | 分割→並列実装→統合 | 並列探索→情報共有→収束 |
| 成果物 | コード（PR） | 分析レポート・修正案 |
| コスト特性 | worktree数で線形増加 | メンバー × ターンで増加 |
| 向いている場面 | 機能実装、リファクタリング | バグ調査、監査、インシデント |
迷ったときの判断フロー：
- タスクをファイル単位で分割できるか？ → Yes → パイプライン型
- 途中の発見が他のタスクに影響するか？ → Yes → 収束型（Agent Team）
- 分からない → まず単一エージェントで試す。行き詰まったらAgent Teamを検討
まとめ
Agent Teamの本質は**「1人で考えるより、3人で同時に考えた方が速い問題がある」**という、チーム開発のシンプルな原理です。
バグ調査、コード監査、インシデント対応。どれも「1本の調査ラインでは遅い」「途中の発見が全体の方向を変える」という特徴を持つ問題群。こういう問題に対して、専門エージェントを並列で走らせて、SendMessageでリアルタイムに情報共有する。それがAgent Team協調の設計パターンです。
設計の詳細はソースコードで確認できます。
