Agent Team Guide

7つの実績あるチームスキルから抽出した Agent Teams 設計パターン集。 新規チームスキルの作成と、既存スキルの品質監査の両方に使える。

このスキルの使い方

新規作成: SKILL.md テンプレート → エージェント定義 → タスク設計 → テスト の順で構築 品質監査: references/quality-checklist.md を既存スキルに適用し、改善点を特定

チームスキルのディレクトリ構成

my-team-skill/
├── SKILL.md                    <- リーダーの手順書（ワークフロー全体）
├── agents/                     <- サブエージェント定義
│   ├── role-a.md
│   ├── role-b.md
│   └── context-manager.md      <- ファイル I/O 専任を推奨
├── references/                 <- テンプレート・ドメイン知識
│   └── report-template.md
└── scripts/                    <- 初期化・ユーティリティ
    └── init.sh

設計の5原則

1. エージェント数は 3〜6 体: 少なすぎると並列の意味なし、多すぎると通信爆発
2. MECE な役割分担: 各エージェントの責務が重複しない
3. 3-Phase ワークフロー: 全エージェントが init → active → finalize の構造
4. 実質的通信のみ: ACK だけの返信は不要。相手の次アクションに繋がる内容がある時のみ返信
5. 待ちすぎない: 全員のフィードバックを待たない。2人以上から反応があれば次へ進む
6. コンテキストファイルで永続化: セッション跨ぎの知識蓄積

SKILL.md テンプレート

## Step 1: ヒアリング
以下を確認する（不明ならユーザーに質問）:
- **項目A**: {具体的に何を聞くか}
- **項目B**: ...

## Step 2: チーム作成とエージェント起動

TeamCreate で `{skill-name}` チームを作成。
以下 N エージェントを **1つのメッセージで並列に** Task ツールで起動する。

| name | 役割 | 主な手段 |
|------|------|---------|
| `role-a` | ... | 分析 |
| `role-b` | ... | WebSearch |

### タスク作成
TaskCreate で N+1 個のタスクを作成:
1. context-manager: 初期化（依存なし）
2. role-a: ...（`addBlockedBy: ["1"]`）
3. role-b: ...（依存なし or `addBlockedBy: ["1"]`）
4. ...（`addBlockedBy: ["2","3"]`）
5. 統合レポート（`addBlockedBy: ["1","2","3","4"]`）

### 起動設定（全エージェント共通）
subagent_type: "{skill-name}:{role-name}"
team_name: "{skill-name}"
mode: "bypassPermissions"
run_in_background: true

プロンプトに含める情報:
- ユーザーからヒアリングした全情報
- コンテキストファイルパス
- 既存の context.md 内容（あれば）

## Step 3: フィードバックループ

### フィードバックプロトコル
1. 自分の作業完了後、即座に関連エージェントへ共有
2. **実質的な内容のある返信のみ送る** - 「了解しました」「ありがとうございます」だけのACK返信は不要。フィードバック・質問・修正報告など、相手の次アクションに繋がる内容がある場合のみ返信する
3. 重大問題は即座に全員へ緊急通知
4. フィードバックを受けたら修正し、変更内容を共有
5. **待ちすぎない** - フィードバックを全員から集める必要はない。2人以上から反応があれば次のフェーズに進む

### Round 1: {概要}
{エージェント間の通信フロー}

### Round 2: {概要}
...

### Round 3: {概要}
...

### 緊急通知パターン
- **role-a**: {どんな問題を検知したら} → {誰にどうアクションを求めるか}
- **role-b**: ...

## Step 4: 最終レポート出力
テンプレート: [references/report-template.md](references/report-template.md)

## Step 5: クリーンアップ
1. 全エージェントに shutdown_request を送信
2. 全員シャットダウン後に TeamDelete でチーム削除

リーダーの行動指針（SKILL.md 実行時）

エージェント起動後のリーダー（メインの Claude）の動き方:

1. 見守りが基本: エージェントが自律的に議論する間は介入しない
2. 介入タイミング: エージェントが詰まった時、矛盾が解消されない時、同じメッセージが繰り返される時
3. TaskList で進捗確認: 全タスクが completed になるまで待機
4. 最終統合: 全報告を統合してレポートを作成（最終タスクはリーダー担当）
5. シャットダウン: 全員に shutdown_request → 承認確認後 TeamDelete

MCP ツールを使うエージェント

MCP ツール（mcp__pencil__* 等）は agents/*.md からアクセスできない。 MCP が必要なエージェントは subagent_type: "general-purpose" で起動し、プロンプト内で役割を定義する:

Task(
  subagent_type: "general-purpose",
  team_name: "my-team",
  prompt: "あなたは ui-designer として... mcp__pencil__batch_design を使って..."
)

よくある落とし穴

問題	原因	対策
エージェントがタスクを見つけられない	owner 未設定	TaskUpdate で必ず owner を設定
ACK だけの返信が大量に発生	「無視禁止」を厳格に適用しすぎ	「実質的な内容のある返信のみ」に変更
エージェントが全員の返信を待ちすぎる	「待ちすぎない」ルールがない	2人以上から反応があれば次フェーズへ進む
エージェントが暇すぎる	過剰な依存関係	並列可能なタスクの依存を外す + 早期フィードバック設計
最終タスクだけ残る	完了通知なし	エージェントに「完了時リーダーに報告」を指示
デバッグが困難	ログがない	PostToolUse Hook (agent-teams-log プラグイン) を有効化
MCP ツールが使えない	agents/*.md で定義	subagent_type: "general-purpose" に変更

詳細リファレンス

トピック別に分離。必要なファイルだけ Read する:

• エージェント定義の書き方: references/agent-definitions.md
  • YAML frontmatter、3-Phase 構造、SendMessage テンプレート、起動パラメータ
• 通信パターン: references/communication-patterns.md
  • Broadcast/Directed/Subteam/Hybrid モデル、SendMessage 構文、通信効率ルール
• タスク管理: references/task-management.md
  • 依存チェーン、TaskCreate のベストプラクティス、早期フィードバック
• Hook 統合: references/hooks-integration.md
  • PostToolUse でエージェント通信を自動ログ、リアルタイム監視
• 品質チェックリスト: references/quality-checklist.md
  • 30項目のレビュー観点（監査手順付き）

関連スキル

• SubAgent 定義の品質向上: subagent-best-practices スキル（~/.claude/skills/subagent-best-practices/）
  • 個別の agents/*.md の書き方に特化したベストプラクティス
  • Frontmatter 全フィールド解説、ツール選択マトリクス、3-Phase 詳細設計、アンチパターン集
  • 本スキル（agent-team-guide）がチーム全体の設計を扱うのに対し、subagent-best-practices は個別エージェント定義の品質に特化