バグ調査に3時間かけて、まだ原因が特定できない。ログを追い、コードを読み、設定を確認する。1つの仮説を検証して潰して、また次へ。単一エージェントでは調査ラインを1本ずつ潰すしかない。
セキュリティとパフォーマンスを同時レビューしたいが、複数ドメイン網羅は現実的ではない。
この課題への解がAgent Team協調型スキルです。複数のAIエージェントが専門分野ごとに並列で動き、発見を共有しながら答えに収束していく。
この記事で学べること
- Agent Team（TeamCreate / SendMessage）の基本構造と使いどころ
- 「パイプライン型」と「収束型」の違い
- 3つの実装から見える設計原則
- コスト制御と早期シャットダウンの仕組み
前提知識
- Skillsの基本概念を把握
- 状態管理パターンを理解
- Claude CodeのTask toolを使ったことがある
この記事で紹介するスキルはすべてGitHubリポジトリで公開しています。
なぜ「チーム」が必要なのか
前回の記事では、worktree並列開発によるパイプライン型を紹介しました。Issueを分割し独立実装し最後にマージする「分けて、束ねる」パターンです。
でも世の中には分割できない問題があります。
パイプライン型が通用しない場面
| 場面 | なぜ分割できないか |
|---|---|
| 複雑なバグ調査 | 仮説Aの結果が仮説Bの方向を変える |
| マルチドメイン監査 | セキュリティの発見がアーキ問題を示唆 |
| インシデント対応 | ログ・コード・設定変更が相互に影響 |
パイプライン型は「各タスクが独立」が前提。でも調査系の問題は途中の発見が他の調査ラインに影響します。
これが「収束型探索」パターン、Agent Teamの出番です。
Agent Teamの基本構造
Claude CodeのAgent Teamは3つのツールで構成されます。
| ツール | 役割 | 例え |
|---|---|---|
| TeamCreate | チーム編成・起動 | プロジェクトの立ち上げ |
| SendMessage | メンバー間の通信 | Slack DM |
| TaskList | 共有タスクボード | カンバンボード |
Task toolとの違いです。
| 比較軸 | Task subagent | Agent Team |
|---|---|---|
| 通信方向 | 親↔子（一方通行） | メンバー間で自由にDM |
| 動的調整 | 結果受領後に次を起動 | リアルタイムで方向転換 |
| コンテキスト | 独立（呼び出し時固定） | SendMessageで随時追加 |
| 適する問題 | 分割可能なタスク | 相互依存のある探索 |
ポイントはSendMessageです。あるエージェントの発見を別のエージェントに即座に伝えられます。このリアルタイム共有が逐次調査との決定的な違いです。
実例1: bug-hunt — 並列バグ調査
最初のAgent Teamスキルが/bug-huntです。
問題意識
単一エージェントでバグ調査すると仮説を1つずつ潰すしかありません。探索空間が広いバグほど逐次調査のコストが膨らみます。
チーム構成
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が発見したらSendMessageでhunt-leadに報告し、方向転換を指示します。
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だけ起動する。単純なバグに4エージェント投入するのは1万円の浪費です。
hunt-leadがTriageフェーズで複雑さを判定し、単純なら1エージェント、複雑なら2エージェント。--max-turnsでターン上限も設定できます。
実例2: code-audit-team — クロスドメイン監査
/code-audit-teamは、セキュリティ・パフォーマンス・アーキテクチャの3ドメインを並列監査します。
単一エージェントとの違い
think-analyzeでも4ドメイン分析はできましたが、クロスドメインの発見ができないのが弱点でした。
| 場面 | 単一エージェント | Agent Team |
|---|---|---|
| SQLインジェクション | セキュリティのみ | sec→archへ横展開確認 |
| N+1クエリ | パフォーマンスのみ | perf→secへリスク確認 |
| 認証ロジック散在 | アーキテクチャのみ | arch→secへリスク確認 |
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だけ起動し他は省略。無駄なトークンを使わない設計です。
実例3: incident-response — インシデント調査
/incident-responseは、本番障害調査に特化したAgent Teamスキルです。
インシデント対応で「逐次」は致命的
本番が燃えているとき、調査は時間との戦いです。3つの調査ラインを同時に走らせ、発見を即座に共有するのがincident-responseの設計思想です。
チーム構成と調査ライン
incident-lead（指揮官）
├── code-analyst（コード変更分析）
├── log-analyst（ログ・メトリクス分析）
└── config-analyst（設定・インフラ変更分析）
調査ラインの連携例を見てみます。
- log-analystが「15:30からDB応答が急激に遅延」を発見
- → SendMessageでcode-analystに「デプロイ差分を確認して」
- 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は揮発するが重要な発見は状態ファイルに記録します。
原則3: 不要なメンバーは早期シャットダウン
コストは参加メンバー数×ターン数に比例します。config-analystが「変更なし」を確認したらシャットダウン。必要なくなったら即座に解散。
原則4: --max-turnsでコスト上限を設定する
全スキルに--max-turnsを実装。80%でワーニング、100%で強制収束します。
パイプライン型 vs 収束型
| 判断基準 | パイプライン型 | 収束型（Agent Team） |
|---|---|---|
| タスク独立性 | 高い（分離可能） | 低い（相互依存） |
| ゴール | 分割→実装→統合 | 探索→共有→収束 |
| 成果物 | コード（PR） | レポート・修正案 |
| コスト特性 | worktree数で線形増加 | メンバー×ターンで増加 |
| 向く場面 | 機能実装、リファクタ | バグ調査、監査、インシデント |
迷ったときの判断フロー：
- タスクをファイル単位で分割できるか？ → Yes → パイプライン型
- 途中の発見が他のタスクに影響するか？ → Yes → 収束型
- 分からない → まず単一エージェントで試し、行き詰まったら検討
まとめ
Agent Teamの本質は 「1人で考えるより、3人で同時に考えた方が速い問題がある」 というシンプルな原理です。
バグ調査、コード監査、インシデント対応。どれも「途中の発見が全体の方向を変える」問題群です。専門エージェントを並列で走らせ共有する、それがAgent Team協調の設計パターンです。
設計の詳細はソースコードで確認できます。
あわせて読みたい
- エージェントチーム入門 — 基本から始めたい方向け
- Worktree並列開発 — パイプライン型パターン
- Skills設計思想と自作ガイド — Skillsの基礎
→ 気軽に相談する
Claude Code エージェント・安全設計 完全ガイド — 本記事含む13本で体系解説。
