Skip to content

How I Use Claude Agent Teams

Claude Code の Agent Teams 機能がClaude Code 2.1.32でリリースされました(CHANGELOG)。

AIエージェント同士が協業するオーケストレーション自体はそこまで新しいアイデアではありません。2025年6月ごろには、複数のClaude Codeを立ち上げてTmuxで別のペインに入力指示を行うような試みがエンジニアたちの間でされており、一時期話題になっていました。

当時からエージェントオーケストレーションはごく一部で話題になっていましたが、環境設定の難しさやAIモデルの性能の関係でそこまで流行ってなかったと思います。

AIツールの機能を開拓しているClaude Codeがようやく公式機能としてAgent Teamsをリリースしたこと、AIモデルの性能が半年で飛躍的に向上したことで、改めてエージェントオーケストレーションが注目を浴びている印象です。

私も2週間ほどAgent Teamsで遊んでみて個人的な使い方が固まってきました。ここで紹介するのは個人的にはうまくいっている方法ですが、参考程度に読んでいただければと思います。

Claude Agent Teams概要

agent-teams

Claude Agent Teamsはチームリーダーがタスクを割り振り、チームメイトが独立したコンテキストウィンドウで作業し、相互にメッセージ送受信できる機能です。

以下の環境変数を設定することで有効化できます。

起動時:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

詳しい設定方法は公式ドキュメントに書いてあります。

Orchestrate teams of Claude Code sessions - Claude Code Docs
Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.
code.claude.com

実際にどのように起動しているかと言うと以下のようなオプションを使用しています。一部オプショナル。参考までに。

  cd <working-directory> && \
    env \
    CLAUDECODE=1 \
    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
    <claude-binary> \
    --agent-id <name>@<team> \
    --agent-name <name> \
    --team-name <team> \
    --agent-color <color> \
    --parent-session-id <uuid> \
    --agent-type <type> \
    --permission-mode <mode> \
    --max-turns <number> \
    --model <model>

Agent Teams vs Subagents

subagents-vs-agent-teams

Claude Code には Subagents(サブエージェント)という機能が存在します。こちらも複数のAIエージェントが独立したコンテキストを持って並列駆動できるためAgent Teamsとよく比較されます。

Agent TeamsがSubagentsと明確に違う点は以下の点です

  • タスクリストを共有している
  • AIエージェント間で相互にやり取りが可能
  • チームメイトからメインのエージェントに渡る情報

1つずつ見ていきたいと思います。

タスクリストを共有している

tasks-system

Claude Agent Teamsではチームメイトがタスクリストを共有しています。

Claude CodeのTasks Systemは2026年1月に刷新されています。タスク同士の進行や依存関係がより明確になりました。 CLAUDE_CODE_TASK_LIST_IDを使用すれば同じタスクリストを複数のClaude Codeインスタンス間で共有できます（これが後々のAgent Teamsの布石となります）

Subagentsでもこのタスクの共有をできなくはないのですが、Agent TeamsではClaude Codeのハーネスの中でこのTasks Systemを有効活用しています。

実際のタスクリストは~/.claude/tasks/{team-name}/に保存されています。形式は以下の通りです(あくまでサンプル)。

{
    "id": "1",
    "subject": "Create login handler with JWT token generation",
    "description": "**What**: ...\n**Where**: ...\n**How**: ...\n**Why**: ...\n**Verify**: ...",
    "activeForm": "Creating login handler",
    "status": "pending",
    "blocks": ["3"],
    "blockedBy": []
}

このTasks Systemは以下の4つのToolを持っているため、PreToolUse Hooksなどを使ってさらにコントロールすることも可能です。

  • TaskCreate: Creates a new task in the task list
  • TaskGet: Retrieves full details for a specific task
  • TaskList: Lists all tasks with their current status
  • TaskUpdate: Updates task status, dependencies, details, or deletes tasks
Claude Code settings - Claude Code Docs
Configure Claude Code with global and project-level settings, and environment variables.
code.claude.com

AIエージェント間で相互にやり取りが可能

Agent TeamsがSubagentsとの大きく違う点として、AIエージェント間の相互通信が挙げられます。

実際の挙動としてはAIエージェントがsendMessageをすると、~/.claude/teams/{team-name}/inboxes/{name}.jsonのinboxesに記録されます。 他のAIエージェントはinboxesを監視しているため、新しくメッセージが送信されると内容を受け取ることで、AIエージェント間の相互通信が確立されます。

具体的には以下のようなスキーマでやりとりされています。

[
  {
    "from": "team-lead",
    "text": "Task 1.4 (Auth integration) is complete. Here's a summary:...",
    "summary": "Task 1.4 auth integration complete, committed",
    "timestamp": "2026-02-14T06:37:35.599Z",
    "read": true
  }
]

このようなAIエージェント間の相互通信をすることで、メインエージェントとチームメイトの間でタスク実行中にもやり取りを差し込むことができます。 ディスカッションタスクなどでAgent Teamsが有効と言われているのはこの機能による点が大きいです。

チームメイトからメインのエージェントに渡る情報

前述のTasks Systemとinboxesを利用したタスクとメッセージの共有により、Agent Teamsでは必ずしもメインエージェントがチームメイトから全ての情報を受け取る必要がなくなりました。 メインエージェントとチームメイトはタスクリストとメッセージInboxesを介して、必要に応じてやり取りを進行します。

Subagentsの場合は、メインエージェントがSubagentsにタスクを割り振った後はSubagentsがタスクを完了した際に返却される結果のみを見ており、Subagentsがどのようなタスクを実行していたかの詳細はほぼ隠蔽されていました。 逆に言うとタスクの完了条件が明確なものはSubagentsの利用が向いていると言えるでしょう。

Claude Agent Teams

agent-teams-squad

Claude Agent Teamsは、エージェントオーケストレーションをより簡単に実現できるようにしてくれました。

現在、個人的には主に2つの使い方をしているので紹介したいと思います。参考になれば幸いです。

1. プランとディスカッション(Plan & Discussion)

Agent Teamsの強みは「Taskの共有」と「AIエージェント間の相互通信」です。 またSubagentsと違い、チームメイトは一度起動するとメインエージェントが明示的にシャットダウンしない限りアイドル状態になります。

この仕組みはAIエージェント間でオープンクエスチョンについてディスカッションさせるような使い方に有効だと思います。

以下のようなプロンプトをよく使います（あくまでサンプルです）

「Agent Teamsを使ってn体のチームメイトで、〇〇について別のディスカッションを３ラウンドかけて行ってください。 この際チームメイト同士でラウンド内で適宜やり取りをしてディスカッションをしてください。 Red Teamingの観点から批判的な意見を言うチームメイトを用意してください。」

個人的には以下の3点が上手くいっていると思います

  • 複数ラウンドによるディスカッション
  • ラウンド内のディスカッション
  • Red Teaming

特に複数ラウンドを跨いだディスカッションはSubagentsで難しいものでした。

このようなプラン・オープンディスカッションなどにAgent Teamsを利用しています。

2. タスク実行(Task execution)

task-execution

Agent Teamsはタスク実行にも使用できると思います。

Claude CodeのTasks Systemでは、タスクの細分化とタスク同士の依存関係を設定できるようになったため、タスクを共有をしているAgent TeamsはSubagentsよりも逐次・並列の両方でタスクを実行できるようになりました。

個人的なコツとしては、実行前のプランニングの段階でタスクの粒度と依存関係をしっかり設定しておくことだと思います。 明確なタスクリストがあれば、あとはClaude CodeにAgent Teamsのチームメイトにタスクを適切に割り振り適宜やり取りをする指示をすれば忠実に実行してくれることが多いです。

タスクリストをうまく作る方法はいくつかあると思います:

  • Tasks関係のイベントにHooksを設定する
  • Spec Driven Development(仕様駆動開発)のツールで事前定義する
  • Ralph-loop で作成するようなspecsを事前に定義する

この辺りは好みですが、最終的にはタスクに対して動的にチームメイトを呼んで割り当てたり、チームメイト間でレビューをさせることも可能です。 Subagentsと同様にAgent Teamsではメインエージェントのコンテキストを圧迫しない特性があるため、タスクが明確になっていればチームメイトにタスクを委譲する価値はあると思います。

まぁあんまり使うとusage limitに速攻で到達するのですが。

まとめ

Agent Teamsは個人的に非常に面白い機能だと思います。

今年はClaude Codeだけでなく他のツールもマルチエージェントオーケストレーションの機能を展開してくると思うので、一度は触っておくと良いです。