はじめに
「このiCloud同期の設計だと、デバイスAで削除したタスクがデバイスBで復活しないか？」
mini-todoアプリの設計レビュー中、コナン（Research & Analysis担当のAIエージェント）からこんな指摘が飛んできた。リムル（Lead Architect）が提案した単純な「最終更新勝ち」方式では、削除操作が同期時に上書きされてしまう可能性があった。
この瞬間、私は気づいた。Agent Teamsの真価は「4人で並列にコードを書く」ことではなく、「4人の異なる視点で設計を叩く」ことにあると。
Claude Codeで導入されたAgent Teamsは、複数のAIエージェントが協力して作業を進める機能だ。本記事では、実際にmini-todoというiOSアプリを開発した経験から、Agent Teamsが設計ディスカッションツールとして特に優れていることを解説する。
対象読者
- Claude Codeを使い始めた開発者
- 単一エージェントの限界を感じている人
- 複数エージェントの協調動作に興味がある人
- 設計品質を向上させたい開発者
1. Agent Teamsとは
1.1 基本構成の4要素
Team Lead（チームリーダー）
チーム全体を統括・調整する管理エージェントで、タスクの分解と割り当て、各チームメイトの成果物を統合する役割を担う。Delegate Modeを有効化すると、リーダーは調整専門に制限され、実装はすべてチームメイトに委譲される。先走って実装を始めるのを防げるため、Agent Teamsに不慣れなうちは有効化をおすすめする。
Teammates（チームメイト）
明示的にシャットダウンするまで存続する永続エージェントだ。以前の「使い捨てエージェント」から根本的に進化しており、各チームメイトが独立したセッションで動作する。
重要な進化点として、コンテキストを保持したまま修正サイクルが回せるため、「指摘 → 修正 → 再レビュー」が同一エージェント間で完結する。
Shared Task List（共有タスクリスト）
チーム全員で共有する進捗管理ツールだ。タスクの状態（pending/in_progress/completed）や依存関係（blockedBy/blocks）を管理する。
リーダーだけでなくチームメイトも自律的にタスクを追加・更新できるため、チーム全体で柔軟にタスク管理が可能だ。
Mailbox/Direct Communication（メールボックス・直接通信）
エージェント間の直接通信機能だ。SendMessageツールを使い、type: "message"で特定のチームメイトへの個別メッセージ、type: "broadcast"で全チームメイトへの一斉通知が可能になる。
以前はすべての通信がオーケストレータ経由で情報ロスが発生していたが、Agent Teamsではエージェント間の直接やりとりでフィードバックループが高速化された。
1.2 Subagentsとの比較
Agent TeamsとSubagentsは、どちらも複数エージェントを扱う機能だが、適用シーンが異なる。
| 観点 | Agent Teams | Subagents | 選択基準 |
|---|---|---|---|
| 通信 | エージェント間で直接通信可能 | メインエージェントへのレポートのみ | チームメイト間で発見を共有・検証する必要がある場合はAgent Teams |
| ライフタイム | 明示的にシャットダウンまで存続 | タスク完了で消滅 | 修正サイクルを回す必要がある場合はAgent Teams |
| セッション独立性 | 完全独立（各自が独自コンテキスト） | 単一セッション内 | 独立した視点が必要な場合はAgent Teams |
| トークン使用量 | 大幅増加（チームメイト数に比例） | 抑制される | リサーチ・レビューなど品質重視ならAgent Teams |
| 調整オーバーヘッド | チームメイト数に比例して増加 | 最小限 | 迅速・補助的な作業ならSubagents |
| 適用シーン | 並列調査/多視点レビュー/設計探索 | ファイル検索/単純なコード生成 | 作業の独立性とコミュニケーション必要性で判断 |
判断フロー
作業を独立したピースに分割できるか？
├─ YES → ピース間でコミュニケーションが必要か？
│ ├─ YES → Agent Teams推奨
│ └─ NO → Subagents推奨（トークン効率的）
└─ NO → 単一エージェント（調整不要）
2. セットアップと基本操作
2.1 settings.jsonでの有効化
Agent Teamsは実験的機能でデフォルトでは無効だ。.claude/settings.jsonのenvで環境変数を設定して有効化する。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
シェル環境変数で設定する場合はexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1でもよい。
注意点として、チームメイトは自動的にCLAUDE.mdを読み込むが、リーダーの会話履歴は引き継がれない。起動時のプロンプトで十分なコンテキストを提供することが重要だ。
2.2 表示モードの選択（teammateMode）
チームメイトの表示方法はteammateModeで制御する。
| 値 | 説明 | 推奨シーン |
|---|---|---|
| auto（デフォルト） | tmux内ならスプリットペイン、それ以外はin-process | 環境に応じて自動選択 |
| in-process | 全チームメイトをメインターミナル内で表示。Shift+Up/Downで切り替え | 任意のターミナルで動作 |
| tmux | 各チームメイトをスプリットペインで表示 | tmuxまたはiTerm2使用時 |
{
"teammateMode": "in-process"
}
スプリットペインにはtmuxまたはiTerm2が必要だ。VS Code統合ターミナルやWindows Terminalでは非対応となる。
2.3 Delegate Modeの活用
Delegate Modeを有効化すると、リーダーは調整専門に制限され、実装はすべてチームメイトに委譲される。
Delegate Modeはsettings.jsonでは設定できない。 チームを起動した後、Shift+Tabでサイクルして有効化する。リーダーが先走って実装を始めるのを防ぎたい場合に活用してほしい。
3. 「mini-todo」をAgent Teamsで開発してみた
mini-todoは「Less is More」をコンセプトにしたミニマルなTODO管理iOSアプリだ。React Native + Expo SDK 54 + TypeScriptで構築し、1日最大7タスクという制限で「本当にやるべきこと」に集中させる設計になっている。
3.1 エージェントにキャラクターペルソナを付けてみた
通常のAgent Teams活用では「Architect」「Reviewer」といった機能名でエージェントを命名するが、今回は実験的にアニメキャラクターのペルソナを付与した。
| エージェント | キャラクター | 役割 | ペルソナ特徴 |
|---|---|---|---|
| rimuru | リムル＝テンペスト | Lead Architect | 元サラリーマンの合理的思考、仲間思い |
| saiki | 斉木楠雄 | Implementation Engineer | 超能力者の効率主義、「やれやれ」が口癖 |
| conan | 江戸川コナン | Research & Analysis | 名探偵の鋭い観察眼、「真実はいつもひとつ」 |
| lelouch | ルルーシュ | Strategy & Optimization | 戦略的マスターマインド、チェス的思考 |
ペルソナを付けた理由は3つある。第一に思考パターンの差異化で、各エージェントが異なる思考スタイルで設計にアプローチする。第二にログの可読性向上で、誰が何を言っているか一目瞭然になる。第三に実験的試みとして、AIエージェントにキャラクター性を持たせることの効果を検証したかった。
3.2 ドキュメント駆動開発のフロー
開発は4つのフェーズに分けて進めた。
Phase 1: 要件定義（youken.md作成）
↓ rimuru統括、全員で議論
Phase 2: 技術選定（tech-stack-decision.md作成）
↓ lelouchが8軸比較マトリクス提示
Phase 3: アーキテクチャ設計（architecture.md作成）
↓ rimuruが設計、conanが技術検証
Phase 4: 実装（48コミット）
↓ saikiが実装、全員でレビュー
各フェーズで作成したドキュメント（youken.md、tech-stack-decision.md、architecture.md）が次フェーズのコンテキストになり、エージェント間の認識ずれを防いだ。特に技術選定フェーズでは、lelouchが「React Native + Expo vs Swift + Skip vs Flutter」を8軸（Claude Code自動化度、開発スピード、Xcode依存度、iOS品質、Android品質、学習コスト、エコシステム、市場シェア）で比較し、定量評価の結果React Native + Expoを選定した。
3.3 具体的な設計改善の実例
事例1: iCloud同期のtombstoneメカニズム
rimuruが提案したiCloud同期の初期設計は「最終更新勝ち（Last Write Wins）」という単純な戦略だった。ローカルとリモートのタスクをupdatedAtで比較し、新しい方を採用する仕組みだ。
しかし、conanがこう指摘した。「この設計だと、デバイスAで削除したタスクがデバイスBで復活しないか？」
具体的には、デバイスAでタスクを削除すると、そのタスクはローカルストレージから消える。一方、デバイスBのiCloudには削除前のタスクが残っている。次回同期時に、デバイスBの古いデータが「最終更新が新しい」と判定され、削除されたはずのタスクが復活してしまう。
rimuruはこの指摘を受けて設計を修正し、削除済みタスクの「墓標（tombstone）」を一定期間保持する仕組みを追加した。削除操作をdeleted: trueフラグで記録し、同期時に削除済みであることを確実に伝播させる。これにより、削除操作が正しく同期されるようになった。
事例2: 技術選定の多角的検討
Phase 2の技術選定では、lelouchが作成した比較マトリクスが意思決定の質を大きく高めた。
| 軸 | React Native + Expo | Swift + Skip | Flutter |
|---|---|---|---|
| Claude Code自動化度 | ◎ 完璧 | △ 制限あり | ○ 可能 |
| 開発スピード | ◎ 最速 | ○ 速い | ○ 速い |
| Xcode依存度 | ◎ ほぼゼロ | △ 必須 | ○ 低い |
| iOS品質 | ○ 高い | ◎ ネイティブ | ○ 高い |
| Android品質 | ○ 高い | ○ 高い | ○ 高い |
| 学習コスト | ◎ 既存知識活用 | △ Swift学習必要 | △ Dart学習必要 |
| エコシステム | ◎ 最大級 | △ 発展途上 | ○ 成熟 |
| 市場シェア | ○ 40% | △ <5% | ○ 46% |
各軸で定量評価し、プロジェクトの優先順位（スピード、Claude Code活用、Xcode依存排除）に基づいてReact Native + Expoを選定した。単一エージェントでは「なんとなくReactで」という曖昧な判断になりがちだが、戦略的視点を持つlelouchが多軸評価を提示したことで、チーム全体が納得できる意思決定になった。
3.4 意外な発見：設計ディスカッションこそ本領
48コミットの開発を通じて実感したのは、Agent Teamsは「4人で並列にコードを書く」のではなく、「4人の異なる視点で設計を叩く」ツールだということだ。
実装フェーズでは、saiki単体でも十分に対応できた。TypeScriptのコンポーネント実装やZustandストア構築は、単一エージェントの得意領域だ。むしろ複数エージェントで並列実装すると、ファイル競合や調整コストが発生する。
一方、設計フェーズでは多視点レビューが圧倒的な価値を発揮した。rimuruの設計案をconanが技術的妥当性で検証し、lelouchが戦略的最適性で評価する。この批判的レビューが、実装後の手戻りを防いだ。tombstoneメカニズムの指摘がなければ、実装後のテストで「削除したタスクが復活する」というバグに直面し、大幅な設計変更が必要になっていただろう。
独立したコンテキストが批判的思考を生む。これがAgent Teamsの本質的な強みだ。
4. 設計ディスカッションツールとしての活用
4.1 なぜ複数エージェント議論が有効か
mini-todoでの経験を踏まえ、なぜ複数エージェント議論が設計品質を高めるのか、そのメカニズムを解説する。
1対1だとAIが同調しやすい
単一エージェントとの1対1の会話では、AIは開発者の前提や意図を尊重する傾向が強い。「このアーキテクチャでいきます」と言うと「良いですね」と同調しがちで、開発者の盲点がそのまま実装に持ち込まれる。確証バイアスを強化してしまうリスクがある。
mini-todoの開発でも、単一エージェントに「最終更新勝ちで同期しよう」と提案していたら、「了解です、実装します」と進んでいただろう。tombstoneメカニズムの必要性に気づくのは、実装後のバグ発見時になっていた可能性が高い。
独立したコンテキストでの批判的思考
Agent Teamsでは、各エージェントが異なるセッションで動作する。これが重要で、他のエージェントの「前提」に縛られず、独自の観点から疑問を投げかけられる。
conanがtombstoneの問題を指摘できたのは、rimuruの設計を「既定路線」として受け入れるのではなく、独立したコンテキストで「削除操作の同期」という観点から分析したからだ。「真実はいつもひとつ」というconanのペルソナが、設計の矛盾を許さない批判的思考を促した。
Plan Modeで設計に集中させる
Plan modeのエージェントは実装ツール（Edit、Write等）を使えないため、必然的に「設計」「分析」「提案」に専念する。実装の詳細に引きずられず、アーキテクチャレベルで思考できる。
mini-todoではrimuruとlelouchをPlan modeで運用した。実装の制約を気にせず、「理想的な設計は何か」を追求できたことが、高品質なアーキテクチャドキュメントにつながった。
4.2 Devil's Advocate（悪魔の代弁者）
コンセプト
red-teamエージェントが分析者の前提条件に継続的に問いかけることで、「なぜそう考えるのか？」「本当にその仮定は正しいのか？」を追求し、潜在的な仮定や盲点を顕在化させる。
エージェント構成例
├─ Analyst（通常モード）
│ └─ ビジネス分析・データ分析を実施
│
└─ Red Team（Plan mode推奨）
└─ Analystの結果を批判的にレビュー
└─ 独自にWeb検索して業界ベンチマークを収集
└─ 「CONDITIONAL-GO」判定とMust Fix指摘
プロンプト例
red-teamエージェント作成してください。
役割：Analystの分析結果を批判的にレビューする独立した視点を提供
タスク：
1. Analystの前提条件の妥当性を検証
2. Web検索で業界ベンチマーク・競合事例を収集
3. 楽観的すぎる仮定を指摘
4. 判定結果（GO/CONDITIONAL-GO/NO-GO）とMust Fixをレポート
Agent Teamsによる効率化
以前はred-teamの指摘後にAnalystをゼロから再起動する必要があったが、今回ではred-teamがAnalystに直接SendMessageツールで修正依頼を送れる。フィードバックループが劇的に高速化された。
4.3 多視点設計レビュー（Multi-perspective Review）
コンセプト
複数の独立したレビュアーが異なる専門性（パフォーマンス/セキュリティ/DX/可読性など）でレビューし、並列実行で時間短縮する。
エージェント構成例
├─ Security Reviewer（通常モード）
│ └─ SQLインジェクション対策/権限チェック/入力検証
│
├─ Performance Reviewer（通常モード）
│ └─ クエリ最適化/キャッシュ戦略/レスポンスタイム
│
└─ DX Reviewer（通常モード）
└─ API設計/エラーメッセージ/ドキュメント整合性
プロンプト例
3人のレビュアーを作成してください。
1. Security Reviewer
- 認証システムの変更を含むPRをレビュー
- 重点項目：入力検証、権限チェック、SQLインジェクション対策
2. Performance Reviewer
- 同じPRをパフォーマンス観点でレビュー
- 重点項目：クエリ最適化、N+1問題、キャッシュ戦略
3. DX Reviewer
- 同じPRを開発者体験の観点でレビュー
- 重点項目：API設計、エラーメッセージ、ドキュメント整合性
並列レビューの効率性
- 単一エージェントでの逐次レビュー: 3視点 × 各10分 = 30分
- Agent Teamsでの並列レビュー: max(10分, 10分, 10分) = 10分
- 時間短縮: 3倍の高速化
各エージェントが専門性に集中することで、単一エージェントでは見落とすバグやリスクを発見できる。
4.4 アーキテクチャ探索（Architecture Exploration）
コンセプト
複数の設計案をPlan modeで並行探索し、実装前にアーキテクチャレベルで比較検討する。早期段階での設計決定を改善する。
エージェント構成例
├─ Architect A（Plan mode）
│ └─ モノリシック設計を提案
│
├─ Architect B（Plan mode）
│ └─ マイクロサービス設計を提案
│
└─ Architect C（Plan mode）
└─ モジュラーモノリス設計を提案
プロンプト例
3人のアーキテクトをPlan modeで作成してください。
共通タスク：新しい認証システムのアーキテクチャ設計
各自、異なるアプローチで設計案を作成してください：
1. Architect A: モノリシック設計
- メリット・デメリット
- スケーラビリティの考慮
- 運用コスト
2. Architect B: マイクロサービス設計
- メリット・デメリット
- 分散トランザクション対策
- 運用コスト
3. Architect C: モジュラーモノリス設計
- メリット・デメリット
- 将来のマイクロサービス化への移行パス
- 運用コスト
各自の設計案を共有し、メリット・デメリットを議論してください。
実装前の意思決定改善
Plan modeにより、各Architectは実装に引きずられず、アーキテクチャレベルの意思決定に専念できる。3つの設計案を並行で検討し、トレードオフを明確化することで、「なんとなく選んだ設計」から脱却できる。
実装後の手戻りコストはトークンコストを大きく上回る。設計段階での議論が後の大規模リファクタリングを防ぐ。
4.5 コスト対効果
トークンコスト増加の実態
- 単一エージェント: 1セッション分のトークン
- Agent Teams（3人）: 約3セッション分のトークン
- 増加率: チームメイト数に比例
Agent Teamsではエージェント間の通信にSendMessageツールを使用するため、メッセージのやりとりごとにトークンを消費する。broadcastで全メンバーに一斉送信する場合、メンバー数分のトークンが発生する点に注意が必要だ。
設計手戻り防止の価値（筆者の体感値）
| シナリオ | 設計フェーズ | 実装フェーズ | 手戻りフェーズ | 合計 |
|---|---|---|---|---|
| 単一エージェント | 0.5時間 | 5時間 | 10時間（設計不備で全面書き直し） | 15.5時間 |
| Agent Teams | 2時間（+トークンコスト） | 5時間 | 0時間（設計で潰した） | 7時間 |
削減効果: 8.5時間（約55%削減）
mini-todoの開発では、tombstoneメカニズムの指摘がなければ、実装後のテストで「削除したタスクが復活する」というバグに直面し、iCloud同期の設計を全面的に見直す必要があっただろう。設計段階で潰せたことで、実装フェーズはスムーズに進んだ。
「実装してから気づく設計ミス」が最もコストが高い。コードが積み上がった後の方向転換は非常に困難だ。Agent Teamsによる設計段階での議論が、後の大規模リファクタリングを防ぐ。
いつAgent Teamsを使うべきか
- 高ROI: 新機能アーキテクチャ、データモデル設計、セキュリティ設計
- 中ROI: リファクタリング計画、パフォーマンス最適化
- 低ROI: 単純なバグ修正、コーディング規約適用
5. ベストプラクティスと注意点
5.1 公式ベストプラクティスから厳選
チームメイトへの十分なコンテキスト提供
課題として、チームメイトはCLAUDE.md/MCPサーバー/スキルを読み込むが、リーダーの会話履歴は引き継がれない。コンテキスト不足で的外れなレビューになることがある。
対策は、起動時のプロンプトにタスク固有の詳細を含めることだ。
良い例
セキュリティレビュアーを作成してください。
このPRは認証システムの変更を含んでいます。
具体的には：
- JWTベースの認証からOAuth2.0への移行
- セッション管理の刷新
- パスワードハッシュアルゴリズムの変更
以下の点を重点的にレビューしてください：
- 入力検証（ユーザー名、パスワード、トークン）
- 権限チェック（管理者vs一般ユーザー）
- SQLインジェクション対策
- XSS対策
悪い例
セキュリティレビューしてください。
リサーチとレビューから始める
Agent Teamsに不慣れな場合、「明確な境界があり、コード編集が不要」なタスクから始めるといい。
適切なスタート地点
- PRのセキュリティ・パフォーマンス・可読性レビュー
- ライブラリ・フレームワークの調査（パフォーマンス・セキュリティ・互換性など）
- バグ調査と仮説検証（複数の仮説を並列テスト）
理由
- ファイル競合のリスクがない
- タスクの境界が明確
- 結果の統合が容易
モニタリングと舵取り
チームを長時間無人で実行すると、無駄な努力のリスクが増加する。
実践方法
- チームメイトの進捗を定期的に確認（TaskListを活用）
- 方向性が間違っている場合は早めにリダイレクト
- 発見が入ってくるたびに統合
推奨サイクル: 15-30分ごとにTaskListとメッセージをチェックし、「このアプローチ、うまくいっていない」と感じたら即座に修正指示を送る。
5.2 トークンコストの考慮
コスト対効果の判断基準
| タスクタイプ | トークン増加 | 品質向上 | 推奨度 |
|---|---|---|---|
| 設計レビュー | 2-3倍 | 大（盲点発見） | ★★★ |
| アーキテクチャ探索 | 3-4倍 | 大（最適解発見） | ★★★ |
| 並列実装 | 2-3倍 | 中（時間短縮） | ★★☆ |
| 単純タスク | 2-3倍 | 小（調整OHが無駄） | ★☆☆ |
トークン節約のTips
- 不要になったチームメイトは早めにシャットダウン
- Broadcastは必要最小限に（各チームメイトにトークン消費）
- Delegate Modeでリーダーの無駄な実装を防ぐ
6. まとめ
ユースケース推奨度テーブル
| ユースケース | 推奨度 | 理由 | トークンコスト | 適用タイミング |
|---|---|---|---|---|
| 設計レビュー | ★★★ | 複数視点で盲点を発見、確証バイアス排除 | 2-3倍 | 設計完了後、実装前 |
| アーキテクチャ探索 | ★★★ | 並行比較で最適解発見、実装前の意思決定改善 | 3-4倍 | 新機能開発の初期段階 |
| 多視点並列レビュー | ★★★ | セキュリティ/パフォーマンス/DXを同時カバー | 3倍 | PR作成後 |
| red-team検証 | ★★★ | 前提条件の妥当性を独立検証 | 2倍 | 戦略提案・分析完了後 |
| リサーチ・調査 | ★★☆ | 異なる角度から並列調査、結果比較 | 2-3倍 | ライブラリ選定・技術調査 |
| 並列実装 | ★★☆ | 時間短縮、ただしファイル競合に注意 | 2-3倍 | クロスレイヤー機能開発 |
| バグ調査 | ★☆☆ | 複数仮説の並列テスト | 2-3倍 | 原因不明の複雑なバグ |
| 単純タスク | ★☆☆ | 調整OHがメリットを上回る | 2-3倍 | 使用非推奨 |
設計フェーズでの活用が鍵
Agent Teamsは「実装ツール」ではなく「設計ディスカッションツール」として活用することで、1対1では生まれない批判的思考を複数エージェントが生み出す。設計の手戻り防止効果がトークンコストを大きく上回る価値を提供する。
ハイブリッド運用戦略
mini-todoの開発経験から、設計フェーズでAgent Teamsを活用し、実装フェーズで単一エージェントを使うハイブリッド戦略が効果的だと分かった。
Phase 1: 設計（Agent Teams）
- 複数のArchitectで設計案を並行探索
- Red teamで前提条件を批判的検証
- 最終設計書を作成（youken.md、tech-stack-decision.md、architecture.md）
Phase 2: 実装（単一エージェント）
- 確定した設計書に基づいて実装
- 単一エージェントで十分（調整不要）
- ファイル競合リスクを回避
Phase 3: レビュー（Agent Teams）
- 多視点レビュー（Security/Performance/DX）
- 並列レビューで時間短縮
総トークンコスト: 設計（3x） + 実装（1x） + レビュー（3x） = 平均1.5x
総時間短縮: 設計手戻り防止で約40-50%削減（筆者の体感値）
始め方の推奨ステップ
- リサーチ・レビューから始める（ファイル競合リスクなし）
- Devil's Advocateパターンを試す（2人構成で簡単）
- 多視点レビューに挑戦（3人構成）
- アーキテクチャ探索で設計力を向上（Plan mode活用）
- ハイブリッド運用で最適化（設計=Teams、実装=単一）
まだまだ進化が期待できるAgent Teamsは使いこなせば、設計品質を大きく向上させる強力なツールだ。トークンコストを恐れず、設計フェーズでの活用から始めてほしい。
参考リンク
- 公式ドキュメント: https://code.claude.com/docs/en/
- Agent Teams Guide: https://code.claude.com/docs/en/agent-teams
- Best Practices: https://code.claude.com/docs/en/agent-teams/best-practices
- Plan Mode: https://code.claude.com/docs/en/agent-teams/plan-mode
- mini-todo GitHubリポジトリ: https://github.com/Rst-Organization/mini-todo