AIコーディングアシスタントの進化は目覚ましいものがありますが、単一のエージェントでは限界を感じる場面が増えてきました。大規模なリファクタリング、複数モジュールにまたがるテスト生成、APIの一括マイグレーション――こうした作業は、1つのコンテキストウィンドウに収まりきらず、途中で文脈が失われたり、指示が抜け落ちたりすることがあります。Claude Code Agent Teamsは、こうした課題に対するAnthropicの実験的な回答です。複数のClaude Codeセッションをチームとして編成し、協調して作業させる仕組みで、マルチエージェント開発という新しいパラダイムを切り開こうとしています。
本記事では、Agent Teamsの基本概念からサブエージェントとの違い、実践的なユースケース、そして効果的な設計指針までを、私たちaduceでの検証経験を交えてご紹介します。Claude Codeの基本をすでに理解されている方を対象としていますが、初めての方もClaude Codeの概要を押さえたうえで読み進めていただければ問題ありません。
Agent Teamsとは？マルチエージェント開発の概要
Agent Teamsは、Claude Codeの実験的機能として提供されているマルチエージェントオーケストレーション機構です。従来のClaude Codeが1つのセッション内で作業を完結させるのに対し、Agent Teamsでは複数のClaude Codeセッションがそれぞれ独立したコンテキストウィンドウを持ちながら、チームとして協調動作します。
基本的な構造はシンプルです。1つのセッションが「チームリード」として全体を統括し、他のセッションが「チームメイト」として個別のタスクを担当します。チームリードはタスクの分割と割り当てを行い、チームメイトはそれぞれの担当領域で独立して作業を進めます。
ここで重要なのは、チームメイト同士が直接コミュニケーションできるという点です。後述するサブエージェントでは、各エージェントはメインセッションにのみ結果を返す一方向の通信しかできませんが、Agent Teamsではチームメイト間で情報を共有し、相互に調整を行えます。たとえば、あるチームメイトがAPIのインターフェースを変更した場合、別のチームメイトがその変更を参照して対応するクライアントコードを更新する、といった連携が可能になります。
この連携を実現するのがGitベースの調整システムです。各チームメイトはGitリポジトリの状態を通じて他のメンバーの作業内容を把握し、コンフリクトを検出・解決しながら作業を進めます。ファイルシステムとバージョン管理という、開発者にとって馴染みのある仕組みの上に構築されているため、動作の予測可能性が高いのが特徴です。
マルチエージェント開発が必要になる背景
なぜ単一エージェントではなく、複数エージェントによる協調が求められるのでしょうか。主な理由は3つあります。
1つ目は、コンテキストウィンドウの制約です。どれだけ大きなコンテキストウィンドウが利用可能になっても、大規模プロジェクトの全容を1つのセッションに収めることは現実的ではありません。複数のセッションに分割することで、各セッションが担当領域に集中でき、文脈の喪失を防げます。
2つ目は、並列処理による速度向上です。100個のファイルに対して同じ変換処理を適用する場合、1つのセッションで逐次処理するよりも、複数のセッションで並列処理するほうが圧倒的に速くなります。私たちの検証では、10ファイルのテスト生成を1セッションで逐次処理した場合と、サブエージェント5つで並列処理した場合で、体感的に3倍以上の速度差がありました。ファイル数が多くなるほど、この差は顕著になります。
3つ目は、関心の分離です。コードを書く作業とレビューする作業を同じセッションで行うと、書き手のバイアスがレビューに影響します。別のセッションでレビューを行うことで、新鮮な視点からのフィードバックが得られます。これはWriter/Reviewerパターンと呼ばれ、マルチエージェント開発の代表的な活用法の一つです。
5つのワークフローパターン
Claude Codeのエージェント活用には、大きく5つのワークフローパターンが存在します。Agent Teamsはその中の1つに位置づけられますが、全体像を理解しておくと適切なパターンを選択しやすくなります。
Sequential（逐次実行）パターン: 1つのエージェントが複数のタスクを順番に処理します。最もシンプルで、タスク間に強い依存関係がある場合に適しています。
Operator（操作者）パターン: 1つのエージェントが外部ツールやAPIを操作しながらタスクを遂行します。MCPサーバーとの連携が典型例で、Claude Code x MCP連携ガイドで詳しく解説しています。
Split-and-Merge（分割統合）パターン: タスクを複数に分割し、それぞれを並列に処理した後、結果を統合します。サブエージェントの典型的な使い方です。
Agent Teams パターン: 複数のエージェントがチームとして協調し、相互にコミュニケーションしながらタスクを遂行します。本記事で詳しく扱うパターンです。
Headless（ヘッドレス）パターン: UIを持たないバックグラウンドプロセスとしてエージェントを実行します。CI/CDパイプラインやスケジュールジョブでの自動実行に適しています。たとえば、プルリクエストが作成されたときに自動でコードレビューを実行したり、定期的にコードの品質チェックを走らせたりする用途で活用されます。
これらのパターンは排他的ではなく、組み合わせて使うことも多いです。たとえば、Agent TeamsのチームリードがOperatorパターンでGitHubのIssueを読み取り、チームメイトにSplit-and-Mergeパターンでタスクを分配する、といった構成が実際に可能です。
サブエージェントの仕組みと使い方
Agent Teamsの理解を深める前に、まずはサブエージェントについて把握しておく必要があります。サブエージェントはAgent Teamsの前段階にある機能で、単一セッション内で別のコンテキストウィンドウを持つエージェントを起動する仕組みです。Agent Teamsほどの柔軟性はありませんが、多くのユースケースではサブエージェントで十分であり、セットアップもはるかに簡単です。
サブエージェントの基本構成
サブエージェントは .claude/agents/ ディレクトリにMarkdownファイルとして定義します。ファイル構成は以下のとおりです。
---
name: code-reviewer
description: コードの品質・セキュリティ・パフォーマンスを独立した視点でレビューする
tools:
- Read
- Grep
- Glob
model: claude-sonnet-4-20250514
---
# コードレビュー担当エージェント
以下の観点でコードをレビューしてください：
- セキュリティ上の脆弱性がないか
- パフォーマンスのボトルネックになりうる箇所はないか
- エラーハンドリングが適切に行われているか
- 命名規則がプロジェクトの慣習に沿っているか
問題を発見した場合は、ファイルパスと行番号を明示し、修正案を具体的に提示してください。フロントマターで指定できる主要な項目を整理します。name はエージェントの識別名で、メインセッションから呼び出す際に使用します。description はエージェントの役割を記述するもので、Claude Codeがどのサブエージェントに仕事を振るべきかを判断する手がかりになります。tools はそのサブエージェントに許可するツールのリストです。不必要なツールを除外することで、意図しない操作を防げます。たとえば、レビュー専用のエージェントにはファイル編集の権限を与えず、Read・Grep・Globのみに制限するのが望ましいです。model は使用するモデルを指定するもので、コスト最適化やタスクの複雑さに応じて使い分けられます。単純な検索や集計にはSonnetを、複雑な設計判断が必要なタスクにはOpusを使うといった使い分けが現実的です。
ファイル名はそのままエージェントの識別に使われるため、code-reviewer.md、test-generator.md、investigator.md のように、役割が一目で分かる命名を心がけてください。
サブエージェントの実行と並列処理
サブエージェントは最大10個まで並列に実行できます。メインセッションからサブエージェントを起動すると、それぞれが独立したコンテキストウィンドウで作業を開始します。各サブエージェントは作業が完了するとメインセッションに結果を報告し、メインセッションはその結果をもとに次のアクションを決定します。
たとえば、10個のモジュールに対するテスト生成を並列で行う場合、以下のような流れになります。
- メインセッションがタスクの全体像を把握する
- 各モジュールに対応するサブエージェントを並列起動する
- 各サブエージェントが独立してテストコードを生成する
- メインセッションが全結果を収集し、整合性を確認する
この方式の利点は、各サブエージェントがメインセッションのコンテキストを消費しない点です。メインセッションは全体の調整に専念でき、個々のファイルの詳細を把握する必要がありません。
サブエージェントの典型的な活用法
サブエージェントが効果を発揮する代表的なシナリオを挙げます。
独立した視点でのコードレビュー: メインセッションでコードを書いた後、レビュー用のサブエージェントを起動します。サブエージェントは書き手の文脈を持たない「新鮮な目」でコードを読むため、メインセッション内でのセルフレビューよりも客観的な指摘が得られます。これが先述したWriter/Reviewerパターンです。
メインの会話を汚さない調査: 大量のファイルを読み込んで調査する作業は、メインセッションのコンテキストを大きく消費します。サブエージェントに調査を委託すれば、要約された結果だけがメインセッションに返ってくるため、メインの会話の流れを維持できます。
並列ファイル処理: 同一の変換ルールを複数のファイルに適用する場合、サブエージェントによる並列処理が威力を発揮します。型定義の更新、インポートパスの変更、ロギングの追加など、繰り返しの多い作業に向いています。
ただし、サブエージェントには制約もあります。サブエージェント同士は直接通信できず、すべてメインセッションを介する必要があります。そのため、エージェント間で頻繁に情報交換が必要なタスクには不向きです。こうした場面ではAgent Teamsの出番になります。
Agent Teams活用のユースケース
Agent Teamsが真価を発揮するのは、複数のエージェントが相互に影響し合うような複雑なタスクです。サブエージェントの「メインに報告して終わり」という一方向モデルでは対処しきれない場面で、その力を発揮します。
大規模リファクタリング
数百ファイルにまたがるリファクタリングは、Agent Teamsの最も分かりやすいユースケースです。たとえば、レガシーなクラスベースのReactコンポーネントを関数コンポーネントとHooksに移行する場合を考えてみます。
チームリードが移行計画を策定し、コンポーネントの依存関係を分析します。依存関係のないコンポーネント群を並列に処理するチームメイトを割り当て、各チームメイトが移行作業を進めます。あるチームメイトが共通のカスタムHookを作成した場合、他のチームメイトはGitを通じてその変更を検知し、新しいHookを利用する形でコンポーネントを移行できます。
この「作業中に他のメンバーの成果物を参照できる」という点が、サブエージェントとの決定的な違いです。サブエージェントでは、共通Hookの作成と利用を同時並行で進めることはできません。まず共通Hookを作り、その結果をメインセッションが確認してから、次のサブエージェントに渡すという逐次的な流れになります。
テスト生成の大規模展開
既存プロジェクトにテストカバレッジを追加する場合も、Agent Teamsが有効です。チームリードがプロジェクト全体のモジュール構成を分析し、テスト戦略を決定します。各チームメイトがモジュール群を担当してテストを書き、境界部分のインテグレーションテストについてはチームメイト間で調整を行います。
たとえば、ユーザー管理モジュールのテストを書くチームメイトと、認証モジュールのテストを書くチームメイトが、双方のモックの整合性をとりながら作業を進められます。認証モジュール側でユーザーオブジェクトの構造を変更した場合、ユーザー管理モジュール側のテストにも即座にその変更が反映されるため、後から手作業で修正する手間が省けます。
APIエンドポイントのマイグレーション
REST APIからGraphQLへの移行、APIバージョンのアップグレード、認証方式の変更など、APIのマイグレーションは影響範囲が広く、整合性の維持が難しいタスクです。Agent Teamsでは、サーバー側の変更を担当するチームメイトとクライアント側の変更を担当するチームメイトが、互いの進捗を参照しながら作業を進められます。
具体的には、サーバー側のチームメイトがエンドポイントのレスポンス形式を変更すると、クライアント側のチームメイトがその変更をGit経由で検知し、対応するリクエスト処理を更新します。これにより、サーバーとクライアントの不整合が発生するリスクが大幅に低減されます。
従来このようなマイグレーションでは、サーバーの変更を先に完了させ、次にクライアントを更新するという逐次的な進め方が一般的でした。Agent Teamsでは両者を並行して進められるため、マイグレーション全体の所要時間を短縮できます。もちろん、サーバーの変更がクライアントに先行する必要がある箇所もありますが、そうした依存関係の管理もGitベースの調整で自然に行われます。
ドキュメントの一括更新
コードの変更に伴うドキュメントの更新も、Agent Teamsの適用範囲です。コード変更を担当するチームメイトの成果物を、ドキュメント担当のチームメイトがリアルタイムで参照し、変更内容に即したドキュメントを生成します。READMEの更新、APIリファレンスの再生成、ChangeLogの追記などを、コード変更と並行して進められます。
このユースケースは見落とされがちですが、実用性は高いです。コード変更とドキュメント更新を別々のタイミングで行うと、ドキュメントの更新漏れが発生しやすくなります。Agent Teamsで同時並行に進めることで、コードとドキュメントの乖離を構造的に防げます。
実プロジェクトでの活用事例
ここでは、私たちaduceが実際にAgent Teamsとサブエージェントを検証した経験をもとに、現場での活用について紹介します。
サブエージェントによるWriter/Reviewerパターン
私たちが最初に導入したのは、サブエージェントを使ったWriter/Reviewerパターンです。実装は以下のように .claude/agents/ にレビュー用のエージェント定義を配置するだけです。
---
name: reviewer
description: 実装済みコードを第三者視点でレビューし、改善点を報告する
tools:
- Read
- Grep
- Glob
model: claude-sonnet-4-20250514
---
# レビュー担当
以下の観点でコードをレビューしてください：
- 型安全性が確保されているか
- エッジケースの処理が漏れていないか
- 既存のユーティリティ関数と重複する実装がないか
- テストが意味のある検証を行っているか
指摘事項はファイルパスと該当箇所を明示し、修正案を添えてください。このパターンの効果は想像以上でした。メインセッションで実装したコードをレビュー用サブエージェントに渡すと、実装時には気づかなかった型の不整合やエッジケースの漏れを指摘してくれます。同じClaude Codeであっても、コンテキストが異なるだけで視点が変わるという事実は、マルチエージェントアプローチの有効性を端的に示しています。
調査用サブエージェントの活用
もう一つ私たちが重宝しているのが、調査専用のサブエージェントです。たとえば「このプロジェクトで未使用のエクスポートを洗い出してほしい」という依頼をメインセッションで行うと、大量のファイルを走査する過程でコンテキストが消費され、その後の作業に支障をきたすことがあります。
調査をサブエージェントに委託すれば、結果だけが簡潔にメインセッションに返ってきます。メインセッションのコンテキストは温存され、調査結果をもとにした次のアクションにスムーズに移行できます。Claude Codeの使い方ガイドでも触れていますが、コンテキストウィンドウの管理はClaude Codeを効果的に使ううえでの重要なスキルの一つです。
Agent Teamsによるモジュール横断の変更
Agent Teamsの検証では、フロントエンドとバックエンドにまたがるAPIの変更を題材にしました。具体的には、レスポンスの日付フォーマットをISO 8601からUnixタイムスタンプに統一する変更です。
チームリードが影響範囲を分析した後、バックエンドのレスポンス変換を担当するチームメイトと、フロントエンドの表示ロジック変更を担当するチームメイトが並行して作業を開始しました。バックエンド側の変更がGitにコミットされると、フロントエンド側のチームメイトがその変更を参照し、日付パース処理を更新するという流れです。
この検証で実感したのは、Agent TeamsがGitベースで調整を行うため、通常の開発ワークフローとの親和性が高いという点です。エージェントの作業結果はすべてGitコミットとして記録されるため、何がどの順序で変更されたかを後から追跡できます。
導入時の注意点
検証を通じて気づいた注意点もいくつかあります。
まず、Agent Teamsは実験的機能であり、安定性や挙動が今後変わる可能性があります。本番のワークフローに全面的に組み込むにはまだ早い段階です。私たちも現時点では、影響範囲が限定的なタスクやブランチ上での検証に留めています。
次に、エージェント数を増やしすぎると、調整コストが増大して逆に効率が下がるケースがありました。3から5程度のチームメイトが実用的な上限だと感じています。
最後に、各チームメイトの作業範囲を明確に定義しておかないと、同じファイルを複数のチームメイトが編集してコンフリクトが頻発するという問題もありました。事前のタスク設計が成功の鍵を握ります。
Agent TeamsとClaude Coworkの違い
Agent Teamsと名前が似ている機能に「Claude Cowork」があります。両者を混同されている方も少なくないため、ここで明確に違いを整理しておきます。
Claude Coworkは、Claude.aiのWebインターフェースから利用できるファイル自動化ワークフローの機能です。コーディングエージェントではなく、ドキュメントの生成・変換やデータの加工といったファイルベースのタスクを自動化するためのものです。Claude Coworkとは？で詳しく解説していますが、ここではAgent Teamsとの対比に焦点を絞ります。
対比表
| 項目 | Agent Teams | Claude Cowork |
|---|---|---|
| 実行環境 | Claude Code（ターミナル） | Claude.ai（Webブラウザ） |
| 主な用途 | コーディング・リファクタリング | ファイル自動化・ドキュメント生成 |
| エージェント間通信 | Git経由で直接通信可能 | ワークフロー定義に基づく逐次処理 |
| 対象ユーザー | 開発者 | 開発者に限らず幅広い職種 |
| コード実行 | ターミナルコマンドの実行が可能 | ファイル操作に特化 |
| 状態管理 | Gitリポジトリ | Webセッション |
使い分けの指針
端的に言えば、コードベースに対する変更作業にはAgent Teams、コードベース外のファイル処理やドキュメント作業にはClaude Coworkが適しています。
たとえば、プロジェクト全体のTypeScriptの型定義をリファクタリングするならAgent Teamsの領域です。一方、会議の議事録から要約を生成してSlackに投稿する、といったワークフローはClaude Coworkの得意分野です。
両者は競合するものではなく、補完関係にあります。Agent Teamsで実装した機能のリリースノートをClaude Coworkで生成する、という組み合わせも自然な使い方です。
もう1点、技術的な違いとして押さえておきたいのは、Agent TeamsがローカルのGitリポジトリ上で動作するのに対し、Claude CoworkはクラウドベースのWebセッションで動作するという点です。これはセキュリティの観点からも重要で、機密性の高いソースコードを扱う場合はローカルで完結するAgent Teamsのほうが適しています。一方、社外のステークホルダーとドキュメントを共同作業する場合は、WebブラウザからアクセスできるClaude Coworkのほうが利便性が高い場合もあるでしょう。
効果的なエージェント分割の設計指針
Agent Teamsやサブエージェントを導入する際、最も重要で最も難しいのが「どう分割するか」の設計です。分割が粗すぎると並列化の恩恵が得られず、細かすぎるとエージェント間の調整コストが増大します。私たちが検証を通じて得た設計指針を共有します。
独立性を基準に分割する
最も重要な原則は、共有状態を最小化できる単位で分割することです。エージェントAの作業結果がエージェントBの作業に影響しないのであれば、それらは独立したタスクとして並列実行できます。
逆に、エージェント間で頻繁にデータをやり取りする必要がある場合は、無理に分割せず、1つのエージェント（またはメインセッション）にまとめたほうが効率的です。分割のメリットがコミュニケーションコストを上回るかどうかを常に判断基準にしてください。
具体例として、フロントエンドのコンポーネントライブラリを考えます。ボタン、フォーム、モーダルなど互いに独立したコンポーネントの実装は、それぞれ別のエージェントに割り当てられます。一方、フォームコンポーネントとそのバリデーションロジックは密結合なので、同じエージェントが担当すべきです。
適切な粒度を見極める
粒度の判断には「15分ルール」が参考になります。1つのタスクを人間が手動で行った場合に15分から30分程度で完了する規模が、サブエージェント1つに割り当てるタスクとして適切な粒度です。これより小さいと、エージェントの起動・終了のオーバーヘッドが無視できなくなります。これより大きいと、コンテキストウィンドウの制約にかかるリスクが高まります。
Agent Teamsの場合は、各チームメイトに30分から2時間程度の作業を割り当てるのが適切です。チームメイト同士が通信できるため、サブエージェントよりも大きな粒度で分割しても問題なく機能します。
境界を明確に定義する
各エージェントの責任範囲をファイルパスやモジュールの境界で明確に区切ることが、コンフリクトを防ぐ最善策です。
チームメイトA: src/components/ 配下のコンポーネントファイル
チームメイトB: src/hooks/ 配下のカスタムHook
チームメイトC: src/utils/ 配下のユーティリティ関数
チームメイトD: tests/ 配下のテストファイル（A/B/Cの成果物に対するテスト）このように、ディレクトリ単位で担当を分けると、同じファイルを複数のエージェントが編集するリスクを最小化できます。チームメイトDのように、他のチームメイトの成果物に依存するタスクは、Agent Teamsのチームメイト間通信が活きる場面です。
サブエージェントとAgent Teamsの選択基準
どちらを使うべきかの判断基準を整理します。
サブエージェントが適するケース:
- タスク間に依存関係がない
- 結果をメインセッションで統合すれば十分
- 比較的小規模なタスク（ファイル数が少ない）
- セットアップの手間を最小限にしたい
Agent Teamsが適するケース:
- タスク間に相互依存がある
- 作業中にエージェント間の調整が必要
- 大規模なタスクで長時間の作業が見込まれる
- コードベース全体にまたがる変更
実際のところ、多くのケースではサブエージェントで十分です。私たちの経験では、Agent Teamsの出番は全体の2割程度でした。まずサブエージェントで試してみて、エージェント間通信が必要だと感じたときにAgent Teamsへ移行する、というアプローチをお勧めします。
エージェント定義の管理
サブエージェントの定義ファイルは .claude/agents/ ディレクトリに格納し、プロジェクトのリポジトリにコミットしておくことを推奨します。チーム全員が同じエージェント構成を共有でき、レビューやバージョン管理の対象にもなります。
エージェント定義もコードと同様にイテレーティブに改善していくものです。最初から完璧な定義を目指すのではなく、実際に使いながら指示の精度を高めていくのが現実的なアプローチです。私たちも、定義ファイルの改善をスプリントの振り返りで定期的に行っています。
エージェント設計のアンチパターン
効果的な設計を理解するためには、避けるべきパターンも知っておくことが重要です。
全能エージェント: 1つのエージェントにすべてのツールと広範な指示を与えてしまうパターンです。コンテキストウィンドウを無駄に消費するだけでなく、指示が曖昧になり出力の品質が低下します。エージェントは「何でもできる」よりも「1つのことを確実にできる」ほうが有用です。
過度な分割: 逆に、5行のコード変更のために専用エージェントを起動するのも非効率です。エージェントの起動にはオーバーヘッドがあるため、手動で行ったほうが速いタスクまで分割する意味はありません。
曖昧な境界: 「フロントエンドを担当」「バックエンドを担当」のような粗い境界では、共有ファイル（型定義、設定ファイルなど）の編集権限が曖昧になり、コンフリクトが多発します。境界はディレクトリやファイル名のパターンで具体的に定義してください。
まとめ
本記事では、Claude Code Agent Teamsとサブエージェントによるマルチエージェント開発について解説しました。要点を振り返ります。
サブエージェントは、単一セッション内で別のコンテキストウィンドウを持つエージェントを最大10個まで並列起動できる仕組みです。.claude/agents/ にMarkdownファイルを配置するだけで定義でき、Writer/Reviewerパターンや並列ファイル処理で効果を発揮します。
Agent Teamsは、複数のClaude Codeセッションがチームとして協調動作する実験的機能です。チームメイト同士がGit経由で直接通信できるため、大規模リファクタリングやモジュール横断の変更といった、エージェント間の調整が必要なタスクに適しています。
Claude Coworkはこれらとは異なる製品で、Claude.aiのWebインターフェースから利用するファイル自動化ワークフローです。コーディングではなく、ドキュメント生成やデータ加工に特化しています。
効果的なエージェント分割のポイントは、独立性を基準にした分割、適切な粒度の見極め、そして明確な境界の定義です。まずはサブエージェントから試し、必要に応じてAgent Teamsへ段階的に移行していくのが、現実的な導入パスだと考えています。
マルチエージェント開発は、単にツールの使い方を覚えるだけでなく、タスクの分解と協調の設計というソフトウェアエンジニアリングの根本的なスキルが問われる分野です。その意味で、マイクロサービスアーキテクチャやチーム開発で培ってきた知見がそのまま活きる領域でもあります。
この分野はまだ発展途上であり、ベストプラクティスも日々更新されています。私たちaduceでも引き続き検証を進め、知見を共有していく予定です。Claude CodeやAIを活用した開発効率化についてご相談がある方は、お問い合わせからお気軽にご連絡ください。