agent-team-guide

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 でチーム削除