🤖

Claude Code Agent Teams を使ってわかったチーム設計の勘所と自動化の限界

に公開

はじめに

最近、Claude Codeに Agent Teams という実験的機能が登場しました。

複数のエージェントをチームとして同時に動かし、並列で開発・テスト・レビューを進められる仕組みです。

この機能を使い込む中で、Agent Teamsを本格的に使うなら、チーム編成そのものをどう設計すべきかがボトルネックになると感じました。

After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.

理由は、ドキュメントにもあるように、プロンプトでタスクだけでなく、チーム作成の指示とチーム構成を伝える必要があるためです。

そこで、チーム編成を自動化する team-builder というskillを作りました。
これは、私の環境下にある24エージェント×83スキルの中から最適な組み合わせを自動選定し、1コマンドでチームをデプロイするものです。

ただ、正直に言うと、自動化で解決できた部分と、そうでない部分がありました。

この記事では、team-builderの設計と実装を紹介しつつ、Agent Teamsを実際に使い込んでわかった「本当に効果があったこと」と「期待ほどでもなかったこと」を正直に共有します。

team-builder

今回は、一部分を抜粋して紹介したりしますが、全体の解説は行わないので、全体を確認したい方は、以下をご参照ください。

https://github.com/sc30gsw/claude-code-customes/tree/main/.claude/skills/team-builder

TL;DR

  • Agent Teamsのチーム編成を自動化するskillを作った
  • 効果があったのは「自動化」そのものではなく、設計パターンの体系化とアンチパターンの蓄積だった
  • 自動選定やスキル注入の効果は限定的だった

Agent Teamsの前提知識

まだAgent Teamsを使ったことがない方のために、簡単に仕組みを説明します。

Agent Teamsは、1つのリードセッションが複数のTeammate(独立したClaude Codeセッション)を統率する仕組みです。

各Teammateは独立したコンテキストウィンドウを持ち、共有タスクリストを通じて作業を調整します。Subagent(Task tool)との違いは、Teammate同士が直接メッセージをやりとりできることです。

https://zenn.dev/storehero/articles/f21d49387577bb

team-builder の構成

team-builderは Skill と Subagents の2つで構成されています。

Skill と Subagents - 2つ作った理由

理由を述べる前に、前提として、Claude Codeにおけるskillとsubagentsについて、ここで一度整理しておきたいと思います。

  • Skill = 手順書。「何をどう実行するか」のワークフロー定義
  • Subagent = 実行者。skillの手順を読み、ツールを使って実際に作業を行う

つまり、以下のようにまとめることができます。

ファイル 種別 役割
.claude/skills/team-builder/SKILL.md Skill ワークフロー定義、引数、ドメイン検出テーブル、デプロイ手順
.claude/agents/team-builder.md Agent SKILL.mdに従い、リソース検出→チーム構成→デプロイを実行

当然、skillだけでも動作しますが、subagentsも作ることで、team-builderの振る舞いを明示的に制御することができるようになります。

  • プロアクティブ起動: Claude Codeが「チーム作成が必要」と判断した場合、ユーザーが /team-builder を呼ばなくてもagentを自動起動できる
  • ツール制限: tools: Read, Grep, Glob, Bash, Write で、agentが使えるツールを明示的に制限できる
  • モデル指定: model: opus で、チーム構成の判断にopusを使うことを保証
# .claude/agents/team-builder.md
---
name: team-builder
description: Intelligent Agent Team composition specialist...
tools: Read, Grep, Glob, Bash, Write
model: opus
---

Skill の構成

今回は以下のような構成でSkillを作成しました。

.claude/skills/team-builder/
├── SKILL.md                          # エントリポイント(176行)
├── scripts/
│   └── discover_resources.py         # 5スコープ横断のリソース検出
└── references/
    ├── team-templates.md             # 8テンプレート定義
    └── composition-guide.md          # 構成ベストプラクティス

各ファイルの記載概要は以下のとおりです。

SKILL.md(エントリポイント): ワークフロー全体像、12個の引数定義、ドメイン検出テーブルを記載。

scripts/(実行可能ロジック): discover_resources.py で5スコープを横断スキャンし、利用可能なエージェント/スキルをカタログ化。プロンプトの肥大化を避けるためスクリプトとして分離。

references/(参照ドキュメント): テンプレートやベストプラクティスなど「必要なときだけ読む情報」。テンプレート追加時にSKILL.mdを変更せずに済む。

SKILL.md

SKILL.mdのfrontmatterは以下のように定義しました。

---
name: team-builder
description: Intelligently compose and deploy Claude Code Agent Teams based on user requirements...
---

本文ではワークフロー、ドメイン検出テーブルに加え、12個の引数を定義しています。ここでは代表的なものを抜粋して紹介します。

引数 短縮 説明
--template -t 定義済みテンプレートを使用
--model -m モデル戦略: deep/adaptive/fast/budget
--dry-run デプロイせずに構成をプレビュー
--delegate -d リードはコーディネーション専任
--plan-approval -p Teammateに計画承認を要求

--dry-run は開発中のデバッグに重宝しました。チーム構成の提案結果だけを確認でき、実際にTeammateをspawnせずに済みました。

テンプレートの具体例: feature-dev

references/team-templates.md に定義された8テンプレートのうち、最も汎用的な feature-dev の中身を見てみましょう。

メンバー構成:

Name agentType Model Role
planner planner opus 要件分析と実装計画
architect system-architect opus システム設計
tester testing-specialist sonnet テスト戦略と実装

タスクフロー(blockedBy で依存関係を表現)

[planner] Requirements Analysis
    ↓ blockedBy
[architect] System Design & Implementation
    ↓ blockedBy
[tester] Test Implementation & Verification
    ↓ blockedBy
[planner] Final Review & Integration

Spawn Prompt テンプレート:

You are the {role-name} on team "{team-name}".

## Your Task
{task-description}

## Available Skills
- /plan: Create implementation plans before coding
- /tdd-workflow: Test-driven development with 80%+ coverage
- /code-reviewer: Code quality review

## On Completion
1. Mark your task completed via TaskUpdate
2. Send a summary to team-lead via SendMessage

Spawn Promptの「Available Skills」セクションが、後述する Skill Injection です。各Teammateの役割に応じて利用すべきスキルを注入しますが、この効果については後ほど正直に評価します。

3つのモード

team-builderは、チーム構成の指定方法として3つのモードを用意しています。自動推薦に任せるか、テンプレートから選ぶか、完全に手動で指定するかを選べます。

モード 使用例 挙動
AUTO(デフォルト) /team-builder "JWT認証を実装" キーワードからドメインを自動検出し、エージェント/スキルを推薦
TEMPLATE /team-builder -t feature-dev "User API" 8つの定義済みテンプレートから選択
MANUAL /team-builder -a "planner,architect" エージェントとスキルを直接指定

実行フロー

AUTOモードでの実行フローを示します。
ユーザーがskillを呼び出してからチームがデプロイされるまでの流れです。

ポイントは、team-builder agent自体がSubagent(Task tool)として起動されることです。メインセッションのコンテキストを消費せず、チーム構成という重い処理を独立したセッションで行います。

次にscriptについて見ていきます。

discover_resources.py の設計

5つのスコープからエージェントとスキルを横断検出するスクリプトです。

設計上のポイントとしては、以下となります。

シンボリックリンク解決と重複排除: ~/.claude/skills/ai-sdk(リンク)と ~/.agents/skills/ai-sdk/(実体)のように同じスキルが複数スコープで見つかる場合、resolve() で実体パスを正規化し重複を排除します。名前重複時は上位スコープを優先するようにしています。

resolved = resolve_path(skill_md)
if resolved in seen_resolved:
    continue
seen_resolved.add(resolved)

sc/ サブディレクトリ対応: 私は、SuperClaude_Frameworkを導入しているため、サブディレクトリとしてsc/を持っています。そのため、直下と sc/ の両方を走査するようにしています。

for search_dir in [base_path, base_path / "sc"]:
    if not search_dir.is_dir():
        continue
    for md_file in sorted(search_dir.glob("*.md")):

以上がteam-builderの全体像です。ここからは、実際に使ってみて何が効いて何が効かなかったかを共有します。

本当に効果があったもの

1. 公式ベストプラクティスのSkillへの組み込み

実は、Agent Teamsの落とし穴の多くは公式ドキュメントにベストプラクティスとして記載されています。

  • 「チームメイトに十分なコンテキストを与える:spawn prompts にタスク固有の詳細を含める」
  • 「タスクを適切に分割する」... 「1人のチームメイトにつき5〜6のタスクを持つことで、全員の生産性を維持できる」
  • 「チームメイトがタスクを完了するまで待つ」
  • 「ファイルの競合を避ける:2人のチームメイトが同じファイルを編集すると上書きされる」
  • 「監視と誘導:チームメイトの進捗を確認し、うまくいかないアプローチを修正する」

しかし、チームを作るたびにこれらを手動で思い出して適用するのは、そこそこ労力がかかりますし、適切に行えたとしても、確実にファイルの競合が起こらないようにしたり、アプローチをうまく修正することは難しいように感じます。

team-builderでは、これらのベストプラクティスを composition-guide.md と各テンプレートに事前に組み込むことで、チーム作成時に自動的に反映される仕組みにしました。

公式ドキュメントの指針 team-builderでの対応
"Give teammates enough context" Spawn Promptテンプレート + 役割別スキルマッピング表
"Size tasks appropriately" + "5-6 tasks" タスク粒度の良い例/悪い例 + 5-6ルールをガイドに記載
"Wait for teammates" + delegate mode --delegate フラグとして実装
"Avoid file conflicts" テンプレートで役割ごとのファイル所有権を事前設計
"Monitor and steer" 完了プロトコル + リード調整プロトコルをガイドに記載
"Token usage: significantly more tokens" --model フラグで4つのコスト戦略を選択可能
"Require plan approval" --plan-approval フラグとして実装

例えば、ファイル競合の問題は公式ドキュメントでも "leads to overwrites" と警告されていますが、team-builderのテンプレートではこれを具体的なファイル所有権パターンとして設計しています。

backend-dev: owns src/api/**, src/services/**, src/models/**
frontend-dev: owns src/components/**, src/pages/**, src/hooks/**
tester: owns tests/**, __tests__/**

公式ドキュメントの「気をつけましょう」を、skillのワークフローに組み込んで忘れても適用される状態にしたことが、team-builderの実用的な価値と考えています。

2. モデル戦略の体系化

Agent Teamsはトークンコストが非常に高いです。Teammate 1人ごとに独立したClaude Codeセッションが起動するため、4人チームなら5セッション分のコストが発生します。

そこで、役割に応じてモデルを使い分ける4つの戦略を整理しました。

戦略 リード アーキテクト/アナリスト ワーカー ユースケース
deep opus opus opus 最高品質が必要な複雑タスク
adaptive opus opus sonnet 品質/コストの最適バランス(推奨)
fast sonnet sonnet sonnet 速度重視、明確なタスク
budget sonnet haiku haiku シンプルなタスク、コスト重視

adaptive 戦略がほとんどのケースで適切です。判断と設計を行うリード/アーキテクトにはopus、明確な指示に従って実装するワーカーにはsonnetを割り当てます。

3. テンプレート - ベストプラクティスのパッケージ化

8つのテンプレートの実質的な価値は、セクション1で述べた公式ベストプラクティスをすぐに使える形にパッケージ化していることです。

各テンプレートには以下が事前に設計されています:

  • Spawn Prompt: 役割説明 + 利用スキル + 完了プロトコル("Give teammates enough context"への対応)
  • タスクフロー: blockedBy による依存関係設計("Size tasks appropriately"への対応)
  • ファイル所有権: 役割ごとの担当領域の分離("Avoid file conflicts"への対応)

例えば investigation テンプレートでは、問題定義の後に研究者とテスターが並列に作業を開始できるよう blockedBy を設計しています。

正直に言えば、Claudeに「バグ調査のチーム作って」と頼めば、テンプレートなしでも似た構成を提案できます。

テンプレートの価値は「Claudeにできないことを可能にする」ではなく、毎回のチーム作成でベストプラクティスの適用漏れを防ぐことにあります。

期待ほど効果がなかったもの

ここからは正直に、作ってみたけど期待ほどの効果がなかった部分を書きます。

1. Skill Injection - やっているのは「リマインダー」だけ

team-builderの目玉機能の1つが、各Teammateのspawn promptsに関連スキルを自動注入する Skill Injection です。

You are the architect on team "jwt-auth-team". Your task is: JWT認証のシステム設計

## Available Skills
Invoke the following skills as needed during your work:
- /senior-backend: Backend development best practices
- /tdd-workflow: Test-driven development with 80%+ coverage
- /security-review: Comprehensive security checklist

これは一見便利に見えますが、Teammateは完全なClaude Codeセッション です。
つまり、Teammateも通常のClaude Codeと同じ前提で起動します。

  • CLAUDE.mdを読む → プロジェクトのルールは自動で反映される
  • すべてのスキルにアクセス可能 → スキルは既にsystem promptに列挙されている

そのため、Skill Injectionは「この中から特にこれを使え」と伝えているだけに過ぎず、実態としては、「新しい能力を付与している」のではなく、「使うべきスキルをリマインドしている」に過ぎません。

とはいえ、ゼロ効果でないということも言及しておきます。

これはTeammateに限らずClaude Code全体に言えますが、多数のスキルの中から適切なものをTeammateやClaude Codeが自力で選ぶのは確率的な側面があり、「/security-reviewを使え」と明示することで使用率は上がります。

ただし、Claudeは十分に賢いので、「JWT認証のセキュリティレビュー」と言われたら /security-reviewなどの有用なskills を自分で見つける可能性は高いです。
そのため、限定的なリマインダー効果にとどまり、期待値以上の結果が得られなかった、というのが正直な評価です。

2. AUTOモード - Claudeの自然言語理解で代替可能

AUTOモードは、リクエストのキーワードからドメインを自動検出し、最適なエージェント構成を提案する機能です。例えば、以下のようなフローで動作します。

"JWT authentication system"
→ "authentication" を検出 → セキュリティドメイン
→ "system" を検出 → 機能開発ドメイン
→ security-reviewer + system-architect を推薦

しかし実は、team-builderを使わずに素のClaude Codeに「JWT認証のチームを作って」と頼んでも、Claudeは自分の判断でほぼ同じ構成を提案する可能性が高いです。

※ 私が試したときは、実際にほぼ同等の構成が提案されました。LLMの出力は確率的なため毎回同じ結果になるとは限りませんが、Claudeの自然言語理解力を考えると、ドメイン検出による自動選定の優位性は小さいと感じました。

結局、AUTOモードで「どのエージェントを選ぶか」を自動化するより、TEMPLATEモードで「ベストプラクティスが組み込まれた構成を選ぶ」方が実用的でした。エージェント選定はClaudeに任せ、Spawn PromptやblockedBy設計などの構成の質をテンプレートで担保する方が効果的です。

3. Teammate内でのSubagent利用 - ニッチすぎる

Agent Team内のTeammateが、さらにSubagent(Task tool)を使うケースも検討しました。

ユーザー
  └── Team Lead
        └── Teammate A (セキュリティレビュー担当)
              ├── Subagent 1 (認証コードの調査)
              └── Subagent 2 (暗号化実装の調査)

Teammateは "full, independent Claude Code session" として動作するため、技術的にはSubagentの利用は可能です。

公式ドキュメントで禁止されているのはTeammateがさらにチームやTeammateをspawnすること("No nested teams")であり、Subagent(Task tool)の利用は制限されていません。

しかし実用上は、以下の理由で効果的ではありませんでした。

  • トークンコストが3層になる: 公式ドキュメントも "Agent teams use significantly more tokens" と警告しているが、Subagentを重ねるとLead + Teammate + Subagentの3層分のコンテキストが発生する
  • Teammateのタスクが適切にスコープされていれば不要: 公式のベストプラクティス "Size tasks appropriately" では "5-6 tasks per teammate" を推奨している。Subagentが必要になる時点で、タスクの粒度が大きすぎる可能性が高い
  • Agent Teamsの強みである直接メッセージングが活かせない: Subagentの結果はTeammateのコンテキスト内に留まり、他Teammateには直接共有できない。Subagent → Teammate → Lead → 別Teammateと伝言ゲームになり、Agent Teamsの「Teammates message each other directly」という利点が失われる

(よくよく考えると、Subagentの課題に対応するための機能なので、それもそうか、という感じですね)

まとめると、「Teammateのタスクスコープを適切に設計する方が、Subagentを重ねるより効果的」ということです。
また、3層ネストの管理コストに見合うユースケースは、実践的にはほとんどないように思います。

Agent Teamsが効く場面・効かない場面

公式ドキュメントでは、Agent Teamsの適切なユースケースとして以下が挙げられています。

  • 研究とレビュー:複数のチームメンバーが同時に問題の異なる側面を調査できる
  • 新しいモジュールや機能:チームメンバーが互いに干渉せずにそれぞれの部分を所有できる
  • 競合する仮説によるデバッグ:チームメンバーが異なる理論を並行してテストする
  • 逐次的なタスク、同じファイルの編集、多くの依存関係を持つ作業には、単一のセッションやサブエージェントの方が効果的

ここでは、これらを実際に使い込んだ上での補足を共有しようと思います。

効く場面 - 公式の推奨通り、ただし構成に工夫が必要

並列調査・レビューは、公式ドキュメントでも最初に挙げられているパターンです。実際に最も安定して効果を発揮しました。
ポイントは、各Teammateに明確な観点を1つだけ割り当てることです。

# PR #142 を3つの観点で並列レビュー
- Teammate 1: セキュリティの観点
- Teammate 2: パフォーマンスの観点
- Teammate 3: テストカバレッジの観点

公式ドキュメントにもある通り、"Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously" です。

観点が重複すると結果も重複するため、team-builderのテンプレートではこの分離を事前に設計しています。

競合仮説の検証も公式推奨パターンです。公式の例では "Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories" とあり、Teammate同士のメッセージングが活きる場面です。

効かない場面 - 公式の警告に加えて

For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective"

公式ドキュメントには 上記のように記載されていますが、実体験から具体的な補足をします。

順次依存が多い作業: 「設計→実装→テスト」のように前工程の結果がないと次に進めない場合、blockedBy で直列化するしかなく並列化の恩恵がありません。この場合、1セッションで順次実行した方がコンテキストが保たれて効率的です。

同一ファイルの編集: 公式の "same-file edits" の警告は控えめですが、実際には片方の変更が丸ごと消えます。Gitのマージコンフリクトではなく無言の上書きなので、気づかないまま作業が消失するリスクがあります。

コスト感度が高い場面: 公式は "use significantly more tokens" と述べていますが、具体的には4人チームで5セッション分(Lead + 4 Teammates)のトークンが並列消費されます。team-builderの budget 戦略(Lead: sonnet、Worker: haiku)でも、単一セッションの数倍のコストになります。

実際の動作

ここでは、Subagent(Task tool)としてのteam-builderを使用して、「経済ニュースを集めるためのツール」を作ってもらうことにします。
(本来であれば、要件→設計とタスクの依存関係があるため、実装以降からを並列にしたほうがよいですが、計画メンバーと実行メンバーのmodelの違いなど、本記事で述べたことがチーム構成として得られるので、このようなpromptとしています)

@"team-builder(agent)"

Create a tool to gather economic news.

すると以下のように、ドメインを分析し、チーム構成を提案してくれます。

その後、この提案を承認することで、Teammateによる計画・実装がなされます。
実装については、並列で以下のように行われます。

結果

作成されたアプリケーションがこちらになります。

https://github.com/sc30gsw/econ-news-tool

ざっとしか見てませんが、そこまで悪いコード品質ではないという印象でした。

しかし、アプリケーションの方は、動作確認してみると、フロントエンドで1つだけエラーがあり、そこだけ、追加のpromptを与えて修正を行うという結果になりました。
(APIのほうは不具合はなく動作しました)

個人的には、rulesやコーディング規約などがないVibe codingにおいても一定の成果をAgent Teamsは上げられそうと思いました。
逆に言えば、rulesやスケルトンコードなどAIが適切に動作する環境を用意したり、適切な技術やライブラリを選定することが今後より一層重要になるとも言えるのかな〜と思っていたりもします。

まとめ: 何が効いて、何が効かなかったか

最後に、team-builderの各要素について、実際に使い込んだ上での効果を整理します。

やったこと 効果 理由
公式ベストプラクティスのSkillへの組み込み 高 公式の指針をワークフローに組み込み、適用漏れを防止
モデル戦略の体系化 中〜高 公式はコスト警告のみ。4つの具体的戦略で再現可能なコスト最適化を実現
テンプレート(8種) 中 ベストプラクティスのパッケージとして有用、ただしClaude自身も似た構成を提案できる
discover_resources.py 中 5スコープ横断の環境棚卸しに有用、ただし一度やれば十分
AUTOモードのドメイン自動検出 低 Claudeの自然言語理解で代替可能。TEMPLATEモードの方が実用的
Skill Injectionの自動注入 低 Teammateは全Skillにアクセス済み。テンプレートに直接書く方がシンプル

おわりに

team-builderを作る過程で、最も価値があったのは Agent Teamsの使い方を体系化できたこと でした。

正直、「1コマンドで全自動」という当初の目標は、Claudeの自然言語理解力の前では期待値が高すぎました。Claudeに「JWT認証のチーム作って」と言えば、team-builderなしでも妥当な構成を提案してくれます。

しかし、以下は実際にskillを作り、使い込まなければ得られなかった成果だと思います。

  • ベストプラクティスの組み込み: 公式ドキュメントの指針をテンプレートやフラグとしてワークフローに定着させた
  • コスト制御: 4つのモデル戦略により、再現可能なコスト最適化を実現した
  • 実践知の蓄積: 「ファイル競合で変更が消える」「5名超でリードのコンテキストが溢れる」といった、使い込んで初めてわかる具体的な痛みを体系化できた

Agent Teamsはまだ実験的機能であり、日常的に使うものではないかもしれません。しかし、並列調査や複数の観点からの並列レビューのように、単一セッションでは実現しづらいタスクでは非常に効果的です。

これまでも複数のClaude Codeセッションを並列起動して作業を分担することは可能でしたが、チーム作成やタスク管理、メッセージングといった調整作業はすべて手動でした。Agent Teamsはこの調整を機能として提供してくれるため、並列作業の敷居を下げてくれるのではないかと感じています。

おまけ

本記事で紹介したteam-builderですが、pluginにしてありますので、試してみたい方は導入していただけると嬉しいです!
感想やフィードバックもしていただけると今後の励みになります!

https://github.com/sc30gsw/claude-code-customes/tree/main/plugins/team-builder

参考文献

https://code.claude.com/docs/en/agent-teams

https://zenn.dev/storehero/articles/f21d49387577bb

Discussion