エージェントチームとサブエージェントは別物です。この2つを混同すると、それぞれの役割についての誤解が生じます。
サブエージェントは委任された作業者です。フォーカスされたタスクを独立して実行し、結果を返して終わります。調整はトップダウンで行われ、あなたがアサインメントをコントロールします。
エージェントチームは別のモデルです。目標を記述し、何人のエージェントが必要かを指定すると、チームがタスク分配を自律的に決定します。エージェントはタスクを自分で取得し、変更をコミットし、継続的にマージし、コンフリクトを解決します。調整は階層的ではなく横断的に行われます。これは単一の開発者がアシスタントに委任するというより、実際のエンジニアリングチームの動き方に近いです。
2026年現在、エージェントチームはまだ実験的機能としてマークされています。これはClaude Codeのリリース間で動作が変更される可能性があり、この記事の末尾で取り上げるような粗い部分があることを意味します。とはいえ、実際のワークロードには十分安定しており、並列化可能な作業での生産性向上は顕著です。
エージェントチームが実際に行うこと
コアメカニズムはGitベースの調整です。チームの各エージェントは：
- 独自のgitワークツリー（独立したファイルシステム、別ブランチ）を取得
- 共有タスクリストからタスクを取得
- 独立して作業
- 共有の統合ブランチにマージ
- すべてのタスクが取得・完了するまで繰り返す
「タスクの取得」はエージェント同士が干渉しないための仕組みです。作業単位を開始する前に、エージェントはクレームマーカー（通常はファイルかgitノート）を作成し、このタスクは自分が担当中であることを他のエージェントに伝えます。他のエージェントは取得済みのタスクをスキップし、未取得のものを選びます。これが並列作業をカオスではなく整合性のあるものにするメカニズムです。
これを手動でオーケストレーションする必要はありません。チームはあなたが記述した内容に基づいて自己組織化します。
エージェントチームの有効化
エージェントチームを有効化するには環境変数が必要です：
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1永続化するにはシェルプロファイルに設定します：
# ~/.zshrc または ~/.bashrc に追加
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1シェルをリロードするかファイルをsourceします：
source ~/.zshrcこの変数が設定されると、Claude Codeセッションでエージェントチーム機能が利用可能になります。
はじめてのエージェントチーム
環境変数が設定されたら、自然言語でチームを記述できます：
認証モジュールを並列でリファクタリングするため、3人のチームメンバーでエージェントチームを作ってください。
各チームメンバーはそれぞれ担当します：(1) トークン検証ロジック、(2) セッション管理、(3) パスワードハッシュとストレージ。Claude Codeはこれを解析してチーム構造を作成し、調整を開始します。基本的な使い方ではあらかじめ設定を書く必要はありません。
より明示的に指定することで、チームに明確な境界が与えられます：
4人のチームメンバーでエージェントチームを作ってください。
スコープ：/src/api/ 内のすべてのAPIエンドポイントをExpressからFastifyへマイグレーション。
サブディレクトリで分担します：routes/、middleware/、controllers/、utils/。
各チームメンバーは1つのサブディレクトリを担当。
担当サブディレクトリの完了後、各チームメンバーはそのスコープのテストスイートを実行して失敗を修正してください。明確さが重要です。曖昧なタスク記述は作業の重複と無駄を生みます。各エージェントの担当を正確に定義するほど、チームに必要な調整オーバーヘッドが減ります。
よく使うチーム構成のプロンプトテンプレート
毎回チームをゼロから記述する代わりに、繰り返し使うパターンのプロンプトテンプレートを用意しておきましょう。プロジェクトの CLAUDE.md または参照用の別ファイルに保存します。
レビューチーム
並列コードレビューのため、3人のチームメンバーでエージェントチームを作ってください。
チームメンバー1：セキュリティレビュー——インジェクション脆弱性、認証バイパス、安全でないデータ処理を確認。
チームメンバー2：パフォーマンスレビュー——N+1クエリ、不要なアロケーション、ブロッキング操作を特定。
チームメンバー3：正確性レビュー——ロジックエラー、エッジケース、エラーハンドリングの漏れを確認。
各チームメンバーは /review-output/ に security.md、performance.md、correctness.md というファイル名で所見をまとめてください。
ソースファイルは変更しないこと——読み取り専用。実装チーム
SPEC.mdに記載された機能を実装するため、4人のチームメンバーでエージェントチームを作ってください。
チームメンバー1：データベーススキーマ変更とマイグレーション。
チームメンバー2：バックエンドサービス層とビジネスロジック。
チームメンバー3：APIエンドポイントとリクエスト/レスポンス処理。
チームメンバー4：新しいコードすべてのユニットテスト。
統合順序：スキーマ優先（チームメンバー1が完了してマージするまで他は待機）、次に2と3を並列、最後に4。リサーチチーム
マイグレーションオプションのリサーチのため、3人のチームメンバーでエージェントチームを作ってください。
チームメンバー1：スタックと互換性のあるORMをリサーチ——Prisma、Drizzle、TypeORMを評価。/research/orm-comparison.md に出力。
チームメンバー2：各ORMのマイグレーションリスクをリサーチ——破壊的変更、データ整合性の懸念点。/research/migration-risk.md に出力。
チームメンバー3：最有力候補の最小限のプルーフオブコンセプトを作成。/research/poc/ に出力。これらを再利用可能なファイルとして保存し、参照します：
# CLAUDE.md に追加
## エージェントチームテンプレート
- レビューチーム: .claude/templates/review-team.md
- 実装チーム: .claude/templates/implementation-team.md
- リサーチチーム: .claude/templates/research-team.mdエージェントチーム向けのCLAUDE.md最適化
エージェントチームのパフォーマンスを向上させる上で最も効果的な変更です。その理由を説明します。
単独のClaude Codeセッションが開始されると、リポジトリの探索に時間がかかります——構造を読み取り、規約を理解し、関連ファイルを見つけます。この探索コストはセッションごとに1回発生しますが、あまり気になりません。
エージェントチームでは、すべてのチームメンバーが同じ探索を独立して行います。4つのエージェントがそれぞれコードベースのマッピングに3〜5分（数百トークン）を費やすと、そのオーバーヘッドが4倍になります。適切に構造化された CLAUDE.md があれば、すべてのチームメンバーのオーバーヘッドを同時に大幅に削減できます。
モジュール境界：明示的に記述する
エージェントが探索によってアーキテクチャを発見するのではなく：
## アーキテクチャ
4つのパッケージを持つモノレポです：
- packages/api — Express REST API、Node 20、TypeScript
- packages/web — Next.js 14フロントエンド
- packages/shared — 共有型とユーティリティ（ランタイム依存なし）
- packages/workers — バックグラウンドジョブプロセッサ（BullMQ）
パッケージ間のインポート：webとapiはsharedからインポート可能。他のパッケージ間のインポートは禁止。
API ↔ web通信：RESTのみ。共有ステートなし、直接の関数呼び出しなし。検証コマンド：モジュールごとに1つ
エージェントが自分の作業を確認する方法を、聞かずに把握できるようにします。明示的なコマンドを提供します：
## 検証コマンド
変更をマージする前に、自分のスコープに関連するチェックを実行してください：
- APIの変更: `cd packages/api && npm test && npm run type-check`
- フロントエンドの変更: `cd packages/web && npm test && npm run build`
- sharedパッケージの変更: `npm run test:all`（全パッケージを実行）
- データベースの変更: マイグレーションをコミットする前に `npm run db:migrate:dry-run`
チームメンバーの作業は、検証コマンドが通過するまで完了ではありません。命名規約：スタイルの競合を防ぐ
4つのエージェントが独立してコードを書くと、あらかじめ指定しない限り一貫性のないスタイルになります：
## 規約
- ファイル命名：ファイルはkebab-case、コンポーネントとクラスはPascalCase
- 関数命名：camelCase、非同期関数には末尾にAsyncをつける（例：fetchUserAsync）
- エラーハンドリング：生の文字列をthrowしない、常に説明的なメッセージを持つErrorインスタンスをthrow
- インポート：名前付きインポートのみ、内部モジュールからのデフォルトインポート禁止
- テストファイル：ソースと同じ場所に配置、*.test.ts という名前タスククレーミングプロトコル：明示的な方が良い
詳細なタスク追跡が必要なチームの場合：
## タスククレーミングプロトコル
タスク開始時：
1. .tasks/claimed/<タスクID>.lock というファイルを作成。内容：agent=<ブランチ名>、started=<タイムスタンプ>
2. ロックファイルが存在する場合にのみ作業を開始
タスク完了時：
1. 検証コマンドが通過することを確認
2. "complete: <タスクID>" というメッセージで全変更をコミット
3. ロックファイルを .tasks/completed/<タスクID>.lock に移動
ロックファイルが既に存在するタスクは開始しないこと。Gitの調整：実際の動作
チームの各エージェントは独自のブランチで作業します。デフォルトの命名規則は agent-team/<セッションID>/agent-<N> というパターンに従います。チームセッション中にアクティブなブランチを確認できます：
git branch | grep agent-team
# agent-team/abc123/agent-1
# agent-team/abc123/agent-2
# agent-team/abc123/agent-3エージェントは作業が完了すると統合ブランチにマージします。Claude Codeがマージの仕組みを処理しますが、コンフリクトが発生した場合の動作を理解しておくと役立ちます。
コンフリクト解決の優先順位：
- エージェントが自分のブランチを統合ブランチにマージしようとする
- コンフリクトがない場合、マージは自動的に進む
- コンフリクトがある場合、エージェントはタスクタイプに基づいて3つの選択肢がある：
- 追加的な変更（新しいファイル、新しい関数）：通常は自動解決可能
- 同じファイルへの変更：エージェントが現在の統合ブランチの状態を読み取り、その上に変更を再適用
- 互換性のない変更：エージェントが停止し、コンフリクトを記録し、あなたに解決を求める
実際的な意味：タスクの境界を設計して共有ファイルを最小化します。2つのエージェントがどちらも config.ts を変更する必要がある場合、それはコンフリクト解決に任せるのではなく、タスク記述で解決すべき調整問題です。
コンフリクトを最小化するタスク構造：
# コンフリクトが発生する
チームメンバー1: ユーザーサービスにキャッシュを追加
チームメンバー2: ユーザーサービスにレート制限を追加
# 発生しない
チームメンバー1: /middleware/cache.ts にスタンドアロンのキャッシュ層ミドルウェアを実装
チームメンバー2: /middleware/rate-limit.ts にスタンドアロンのレート制限ミドルウェアを実装
チームメンバー3: 両方のミドルウェアをユーザーサービスのルートに組み込む
# （チームメンバー3は1と2がマージした後に開始）エージェントチーム vs サブエージェント vs 手動マルチインスタンス
これらは競合するアプローチではなく、異なる問題に対処するものです。
通常のサブエージェントが適しているケース：
- 明確に定義されたシーケンシャルで委任可能なタスクがある
- 各ステップの内容とタイミングを正確にコントロールしたい
- サブタスクが並列化の恩恵を受けない
- ステップ間でコントロールされた方法でコンテキストを渡す必要がある
# CLAUDE.mdの典型的なサブエージェントパターン
## api-docs-writer
description: TypeScriptソースからOpenAPIドキュメントを生成する。APIルートを更新する際に使用。
tools: read, writeエージェントチームが適しているケース：
- 明確に並列化可能な大量の作業がある
- タスクの境界を明確に定義できる（異なるファイル、異なるモジュール、異なる関心事）
- アサインメントをマイクロマネジメントするより自己組織化させたい
- 各エージェントがマージ前に独立して作業を検証できる
手動マルチインスタンス（別ターミナルセッション）が適しているケース：
- 各セッションを完全にコントロールする必要がある
- 調整がノイズになる探索的・リサーチ的タスクを実行している
- エージェントチームの動作が予期せぬ結果を引き起こしていて、セッションを分離してデバッグする必要がある
# 手動マルチインスタンス：3つの別ターミナル、3つの別タスク
# ターミナル1
cd ~/project && git checkout -b feat/auth-refactor && claude
# ターミナル2
cd ~/project-worktree-1 && git checkout -b feat/api-refactor && claude
# ターミナル3
cd ~/project-worktree-2 && git checkout -b feat/db-migrations && claude手動アプローチは自動化の多くを犠牲にして最大のコントロールを提供します。
制限事項と注意点
実験的とはAPIが不安定であることを意味します。 環境変数、チーム起動構文、調整動作はすべて変更される可能性があります。エージェントチームの上にワークフローツールを構築する場合は、Claude Codeのバージョンを固定してください。
チームは不明確なスコープを魔法のように解決しません。 曖昧な目標を4つのエージェントに渡すと、互換性のない方法で重複した作業をする4つのエージェントが得られます。エージェントチームは良いタスク記述も悪いタスク記述も増幅します。プロンプトに時間を投資してください。
共有状態は敵です。 エージェントはファイルシステムレベルで分離されていますが、共有外部リソース（データベース、サードパーティAPI、環境変数、共有設定ファイル）からは分離されていません。4つのエージェントがそれぞれ独立してデータベースマイグレーションを実行しようとすると問題になります。共有リソースのステップはシリアライズするか、チームの外で処理してください。
トークン消費はチームサイズに比例します。 チームの各エージェントはトークンを独立して消費します。4エージェントのチームを並列実行すると、1つのセッションが同じ作業をシーケンシャルに行う場合のおよそ4倍のトークンを消費します。時間の節約は実際のものですが、コストも同様です。大きなチームを頻繁に実行する場合はMaxプランまたは予算管理を慎重に行ってください。
CLAUDE.mdの探索コストが最も重要な乗数です。 各エージェントがコードベースの探索に時間をかけることを余儀なくさせる構造の悪いCLAUDE.mdは、チームサイズに比例したコストをもたらします。チームサイズを増やす前に、適切に構造化されたCLAUDE.mdへの投資を惜しまないでください。
複雑なケースではマージコンフリクトに手動介入が必要です。 単純なコンフリクトについては、Claude Codeが自動的に解決します。意味的な非互換性を含むコンフリクト（2つのエージェントが同じビジネスロジックを互換性のない方法で変更した場合）については、介入する必要があります。これはバグではなく、並列作業の根本的な制約です。
エージェントチームの実用的なメリット
最も明確な効果が得られるのは次の特性を持つタスクです：
- 広いスコープ、低い調整依存性（50のAPIルートを新しいフレームワークにマイグレーションする）
- よく理解された規約（独立したスタイルが問題にならない）
- 明確なファイルまたはモジュール境界に収まる作業
- 高い検証確度（エージェント自身が実行できる包括的なテストスイート）
エージェントチームが最も弱いケースは、すべての変更が他のすべての変更に影響するような密結合の作業です。そういった作業では、コンフリクト解決にサイクルの半分を費やすチームよりも、単一のよくコンテキスト化されたエージェントによるシーケンシャル実行の方が通常は速くエラーも少なくなります。
サブエージェントは単一エージェントの委任モデルを詳しくカバーしています——2つのアプローチは補完関係にあります。大規模で並列化可能なワークロードにはエージェントチームが適しています。シーケンシャルなコンテキスト依存の委任にはサブエージェントの方が適しています。