Claude Code Agent Teamsの全体像と従来のサブエージェントでは不可能だった協調開発の仕組み

Claude Code Agent Teamsの全体像と従来のサブエージェントでは不可能だった協調開発の仕組み

Claude Code Agent Teamsは、複数のClaude Codeインスタンスを1つのチームとして連携させ、並列で開発タスクを遂行できる機能です。2026年2月にリサーチプレビューとして公開され、従来のサブエージェントでは実現できなかったエージェント間の直接コミュニケーションや共有タスクリストによる自律的な作業分担が可能になりました。単一セッションの延長線上にあるサブエージェントとは根本的にアーキテクチャが異なり、チームリードが全体を指揮しながら各チームメイトが独立したコンテキストウィンドウで作業を進める構造を持っています。

単一セッション完結型の開発から複数インスタンス協調型へ移行した背景にある3つの技術的課題

Claude Codeはもともと1つのセッションで1つのタスクを処理する設計でした。開発者がプロンプトを送り、Claudeが応答し、フィードバックを受けて次の作業に進むという逐次的なフローが基本です。しかし、プロジェクトの規模が大きくなるにつれ、3つの技術的課題が顕在化してきました。

第一に、単一セッションでは一度に1つの作業しか処理できないため、複数のバグ修正やフィーチャー開発を同時に進めたい場面でボトルネックが生じていました。第二に、コンテキストウィンドウの制約があり、巨大なコードベースを扱う際に1セッションだけでは全体を把握しきれないケースが増加していました。第三に、コードレビューやテスト実行といった異なる観点の作業を1つのエージェントに順番に担当させると、観点の切り替えコストが発生し、品質にばらつきが出る問題がありました。Agent Teamsはこれらの課題に対し、複数のClaudeインスタンスを同時に稼働させ、それぞれが専門領域に集中できる仕組みとして設計されています。

エージェント間の直接メッセージングがサブエージェントの「報告のみ」モデルを超えた具体的な差分

従来のサブエージェントは、メインエージェントから派生した子プロセスのような存在でした。サブエージェントが作業を終えると、その結果はメインエージェントにのみ返され、サブエージェント同士が互いの成果物を参照したり議論したりすることはできませんでした。この「報告のみ」のモデルは、単純なタスクの並列処理には十分でしたが、相互検証や議論を要する複雑な作業には適していません。

Agent Teamsでは、チームメイト同士がメールボックス機能を通じて直接メッセージを送り合える仕組みが導入されています。たとえば、セキュリティ担当のチームメイトが認証モジュールの脆弱性を発見した場合、バックエンド担当のチームメイトにその情報を即座に共有し、修正方針を議論できます。さらに、ブロードキャスト機能を使えば全チームメイトに同時に情報を配信することも可能です。この直接通信の導入により、エージェント間で発見内容を相互検証し、互いの仮説に反論するという科学的な議論プロセスが実現しました。Anthropicの公式ブログでも、5つのエージェントに異なる仮説を持たせて互いに反証させるデバッグ手法が紹介されており、単一エージェントでは陥りやすいアンカリングバイアスの回避に有効であると報告されています。

共有タスクリストと依存関係の自動解決がもたらす並列作業の実効スループット向上率

Agent Teamsの中核機能の1つが、全エージェントがアクセスできる共有タスクリストです。タスクにはpending、in progress、completedの3つの状態があり、さらにタスク間の依存関係も定義できます。あるタスクが別のタスクの完了に依存している場合、依存先が完了するまでそのタスクはブロック状態となり、チームメイトが誤って着手することを防ぎます。

タスクの取得にはファイルロック機構が採用されており、複数のチームメイトが同一タスクを同時にクレームしようとした場合の競合状態を回避できます。チームリードがタスクを明示的にアサインする方法と、チームメイトが空きタスクを自律的にセルフクレームする方法の2通りが用意されており、プロジェクトの性質に応じて使い分けが可能です。Redditのユーザー報告によれば、サブエージェント利用時と比較して同一規模のタスクを約50%短い時間で完了できたケースもあり、エージェント数が3〜5の範囲でスループット向上率が最も高くなる傾向が見られます。ただし、エージェント数を増やしすぎるとコーディネーションオーバーヘッドが増加し、費用対効果が低下する点には注意が必要です。

チームリードが担うオーケストレーション機能と人間オペレーターの介入ポイントの境界線

Agent Teamsにおいて、チームリードはチームを作成したメインのClaude Codeセッションが自動的に担当します。チームリードの役割は、タスクの分解と割り当て、チームメイトのスポーンとシャットダウン、作業結果の統合の3つに大別されます。チームリードは自然言語で指示を受け取り、適切なチーム構成を判断してチームメイトを生成します。

一方で、人間オペレーターの介入ポイントも明確に設計されています。まず、チームの作成自体は人間の承認なしには行われません。Claudeがタスクに対してチーム構成を提案した場合でも、ユーザーが確認するまでチームは生成されない仕組みです。また、各チームメイトに直接メッセージを送って方針を修正したり、作業を中断させたりすることも可能です。In-Processモードではshift+Up/Downでチームメイトを切り替えて個別に指示できますし、Split Paneモードでは各チームメイトのペインをクリックして直接操作できます。この「自律と統制のバランス」が、Agent Teamsを単なる自動化ツールではなく、人間と複数のAIエージェントが協働するフレームワークとして機能させている要因です。

2026年2月時点のリサーチプレビュー段階で確認されている機能制限と今後のロードマップ予測

Agent Teamsは2026年2月時点でリサーチプレビューとして公開されており、いくつかの既知の制限事項があります。最も影響が大きいのは、セッション再開時にIn-Processモードのチームメイトが復元されない点です。/resumeや/rewindコマンドを使用しても、以前のチームメイトは復元されず、リードが存在しないチームメイトにメッセージを送ろうとするケースが報告されています。

そのほか、1セッションにつき1チームしか管理できない制約、チームメイトがさらにチームをネストして作成することはできない制約、リーダーシップの移譲ができない制約があります。Split Paneモードについても、VS Codeの統合ターミナルやWindows Terminal、Ghosttyでは動作しないという互換性の制限があります。タスクステータスの更新が遅延し、依存タスクがブロックされたままになるケースも報告されており、運用時には手動での状態確認が必要になることがあります。正式リリースに向けては、セッション復元機能の強化やネストチームのサポート、より広範なターミナル互換性の確保が期待されています。現段階ではリサーチ・レビュー系のタスクから段階的に導入し、安定性を確認しながら適用範囲を広げるアプローチが推奨されます。

開発チームが導入前に把握すべきAgent Teamsの前提条件とシステム要件

Agent Teamsを活用するには、Claude Codeの環境構築に加えていくつかの前提条件を満たす必要があります。実験的機能であるため、通常のClaude Code利用とは異なる有効化手順が必要であり、表示モードによっては追加のターミナルツールのインストールも求められます。コスト面でもチームメイト数に応じてトークン消費が増大するため、事前の予算試算が欠かせません。

Claude Codeの最新バージョンへの更新とCLI環境の互換性チェックで確認すべき5項目

Agent Teamsを利用するための第一歩は、Claude Codeが最新バージョンに更新されていることの確認です。Agent Teams機能はバージョン2.1.33以降で導入されたため、それ以前のバージョンでは環境変数を設定しても機能が有効化されません。更新はnpm update -g @anthropic-ai/claude-codeコマンドで実行できます。

バージョン確認に加えて、CLI環境の互換性として以下の5項目をチェックすることを推奨します。Node.jsのバージョンが推奨要件を満たしているか、npmのグローバルインストールパスに適切な権限があるか、既存のClaude Code設定ファイル（settings.json）に競合する設定がないか、プロジェクトディレクトリにCLAUDE.mdが配置されているか、そしてMCPサーバーを利用している場合はその接続設定が最新かどうかです。特にCLAUDE.mdの有無は重要で、チームメイトはスポーン時にリードの会話履歴を引き継がない代わりに、プロジェクトコンテキストとしてCLAUDE.mdやMCPサーバー設定を自動的に読み込みます。この初期コンテキストの品質が、チームメイトの作業精度に大きく影響します。

環境変数CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSの有効化とsettings.jsonへの反映手順

Agent Teamsはデフォルトで無効化されており、明示的に有効化する必要があります。方法は2通りあり、シェル環境変数として直接設定する方法と、settings.jsonに記述する方法です。シェル環境変数で設定する場合は、ターミナルでexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を実行するか、.bashrcや.zshrcに追記して永続化します。

settings.jsonに記述する場合は、envオブジェクト内に"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"を追加します。settings.jsonはユーザーレベルとプロジェクトレベルの2箇所に配置でき、プロジェクトレベルの設定が優先されます。チーム全体で統一的にAgent Teamsを有効化したい場合は、プロジェクトルートのsettings.jsonに記述するのが確実です。設定反映後、Claude Codeを新規セッションで起動すれば、チーム作成のプロンプトが受け付けられるようになります。既存のセッション内で環境変数を変更しても反映されないケースがあるため、必ず新しいセッションで確認することが推奨されます。設定が正しく反映されているかの確認は、Claudeに対して「エージェントチームを作成してください」と依頼し、チーム生成のフローが開始されるかどうかで判断できます。

Split Paneモードを使う場合のtmux・iTerm2のインストール要件と非対応ターミナルの一覧

Agent Teamsの表示モードには、In-ProcessモードとSplit Paneモードの2種類があります。In-Processモードはすべてのチームメイトがメインターミナル内で動作し、追加のソフトウェアは不要です。一方、Split Paneモードは各チームメイトに専用のペインを割り当て、全員の出力を同時に確認できるため、4人以上のチーム運用では視認性が大幅に向上します。

Split Paneモードを利用するには、tmuxまたはiTerm2のいずれかが必要です。tmuxはLinuxおよびmacOSの主要パッケージマネージャからインストール可能で、macOSではbrew install tmux、Ubuntuではsudo apt install tmuxで導入できます。iTerm2を使用する場合は、it2 CLIのインストールに加えて、iTerm2の設定画面からSettings → General → MagicでPython APIを有効化する手順が必要です。注意すべきは、VS Codeの統合ターミナル、Windows Terminal、GhosttyではSplit Paneモードが動作しない点です。これらのターミナルを使用している場合は、In-Processモードで運用するか、tmuxセッション内からClaude Codeを起動する回避策を取る必要があります。teammateModeの設定値は「auto」「in-process」「tmux」の3つで、autoの場合はtmuxセッション内であればSplit Pane、それ以外ではIn-Processが自動選択されます。

APIキーの権限設定とトークン消費量がチーム人数に比例して増加する料金体系の事前試算

Agent Teamsでは、チームメイト1人につき1つの独立したClaude Codeインスタンスが起動するため、トークン消費量はチームメイト数に比例して増加します。たとえば、チームリード1名とチームメイト3名の構成であれば、単一セッションと比較して約4倍のトークンが消費される計算です。2026年2月時点のAPI料金は、Claude Opus 4.6がインプット$5/100万トークン・アウトプット$25/100万トークン、Claude Sonnet 4.5がインプット$3/100万トークン・アウトプット$15/100万トークンとなっています。

Redditのユーザー報告では、サブエージェント利用時のトークンコストが約$10だったタスクが、Agent Teamsでは$15〜$20に増加したケースが紹介されています。ただし、作業時間が6時間から2時間に短縮されたことを考慮すると、時間あたりの費用対効果は改善しています。事前試算としては、月間の開発タスク量からチームメイト数と稼働時間を想定し、Claudeの公式ドキュメントで案内されている平均$100〜$200/開発者/月（Sonnet 4.5基準）を基準にチーム運用分を上乗せする方法が実用的です。コストを抑えたい場合は、チームメイトにSonnetを指定し、リードのみOpusを使用するモデル混在戦略が有効です。

CLAUDE.mdやMCPサーバー設定などプロジェクトコンテキストの事前整備が成果に直結する理由

Agent Teamsにおいて、チームメイトはスポーン時にリードの会話履歴を引き継ぎません。チームメイトが受け取る初期情報は、プロジェクトのCLAUDE.md、MCPサーバー設定、スキル定義、そしてリードからのスポーンプロンプトの4つです。つまり、CLAUDE.mdの品質がチームメイトの作業精度を直接左右するということです。

効果的なCLAUDE.mdには、プロジェクトの技術スタック、ディレクトリ構造の説明、コーディング規約、テストの実行方法、重要な設計判断の経緯などを記載します。Anthropicの公式ベストプラクティスでも「チームメイトに十分なコンテキストを与えること」が強調されており、スポーンプロンプトにタスク固有の詳細を含めることが推奨されています。たとえば「src/auth/以下の認証モジュールをレビューしてください」だけでなく、「JWTトークンをhttpOnlyクッキーに保存する構成で、トークンハンドリング・セッション管理・入力バリデーションに焦点を当ててレビューしてください」のように具体的な技術的文脈を添えることで、チームメイトの初動が格段に改善します。MCPサーバーを活用している場合は、チームメイトもそのサーバーにアクセスできるよう事前に設定を確認しておく必要があります。

初回セットアップから最初のチーム起動までを迷わず完了するための手順と設定項目

環境要件を満たしたら、実際にAgent Teamsを起動してみましょう。チームの作成は自然言語で指示するだけで完了しますが、プロンプトの記述粒度や表示モードの選択によって使い勝手が大きく変わります。初回セットアップで押さえるべきポイントと、よくあるトラブルの回避策を具体的な操作手順とともに解説します。

自然言語プロンプトでチーム構成を指示する際に成果を左右する記述粒度の具体例3パターン

Agent Teamsの作成は、Claude Codeのセッション内で自然言語のプロンプトを送るだけで開始できます。しかし、プロンプトの記述粒度によって、生成されるチームの構成と成果物の品質が大きく異なります。実務で有効な記述粒度を3つのパターンに分類して紹介します。

第一のパターンは「役割定義型」です。「CLIツールの設計をエージェントチームで検討してください。UX担当、技術アーキテクチャ担当、デビルズアドボケイト担当の3名で構成してください」のように、各チームメイトの役割を明示する方法です。役割が独立しているほどチームメイト間のファイル競合が起きにくく、初回導入時に最も成功率が高い形式です。第二のパターンは「成果物指定型」で、「認証モジュールのリファクタリングをチームで実施してください。1人はAPI設計、1人はテスト作成、1人はドキュメント更新を担当してください」のように、各チームメイトの最終成果物を指定します。第三のパターンは「制約付き自律型」で、「このPRのレビューを3名のチームで行ってください。ただし、セキュリティ観点を必ず含めてください」のように、最低限の制約のみを与えてClaudeに構成を委ねます。初回は第一のパターンから始め、チームの動作を把握してから徐々に自律度を上げていくのが安全なアプローチです。

チームメイト数とモデル指定をコマンドで明示する方法とClaude自動判定に任せる場合の判断基準

チームメイトの人数は、プロンプト内で明示的に指定することも、Claudeの自動判定に任せることも可能です。明示的に指定する場合は「4人のチームメイトでこれらのモジュールを並列にリファクタリングしてください。各チームメイトにはSonnetを使用してください」のように、人数とモデルの両方を自然言語で記述します。

Claudeの自動判定に任せる場合、Claudeはタスクの複雑さと並列化可能性を評価してチーム規模を決定します。一般的に、独立した3〜5のサブタスクに分解可能な場合にチームが提案される傾向があります。自動判定が適しているのは、タスクの全体像は明確だが最適な分担方法が不明な場合です。逆に、ファイルの依存関係が複雑で意図しない競合が起きやすいケースや、コスト管理を厳密に行いたい場合は、人数を明示する方が安全です。モデル指定は費用最適化の重要なレバーで、チームリードにはOpus 4.6を使い複雑な判断とオーケストレーションを任せつつ、各チームメイトにはSonnet 4.5を指定して実装コストを抑える混在構成が実務では多く採用されています。モデルを指定しない場合、リードと同じモデルがチームメイトにも適用されます。

In-Processモードでの起動確認とShift+Up/Downによるチームメイト切り替え操作の実演手順

In-Processモードは追加ソフトウェア不要で最も手軽に利用できる表示モードです。Agent Teamsを有効化した状態でClaude Codeを起動し、チーム作成のプロンプトを送信すると、メインターミナル内でチームリードとチームメイトが動作を開始します。起動直後の画面にはリードのセッションが表示され、チームメイトのスポーン状況がログとして出力されます。

チームメイトの切り替えには、Shift+Up/Downキーを使用します。Shift+Downで次のチームメイトへ、Shift+Upで前のチームメイトへ移動できます。特定のチームメイトを選択した状態でメッセージを入力すると、そのチームメイトに直接指示を送ることが可能です。Enterキーでチームメイトのセッション全体を表示し、Escapeキーで現在のターンを中断できます。また、Ctrl+Tでタスクリストの表示・非表示を切り替えられるため、全体の進捗を確認しながら個別のチームメイトに指示を出すワークフローが実現します。初回起動時は、まずShift+Downでチームメイト一覧を確認し、各メンバーが正しくスポーンされているかを目視チェックしてから作業を開始することを推奨します。チームメイトが表示されない場合は、後述のトラブルシューティングを参照してください。

Split Paneモードへの切り替え時にteammateModeをtmuxに設定する際の落とし穴と回避策

Split Paneモードを利用するには、settings.jsonの"teammateMode"を"tmux"に設定するか、コマンドラインフラグとして--teammate-mode tmuxを渡します。tmuxが正しくインストールされていれば、チーム作成時に各チームメイトが独立したtmuxペインに割り当てられ、全員の出力を同時に確認できる環境が構築されます。

ただし、Split Paneモードの設定にはいくつかの落とし穴があります。最もよくある問題は、tmuxがインストールされているにもかかわらずPATHが通っていないケースです。which tmuxコマンドでパスを確認し、結果が返らない場合はシェルの設定ファイルにパスを追加する必要があります。iTerm2を使用する場合は、it2 CLIのインストールとPython APIの有効化の両方が必要で、どちらか一方が欠けると起動に失敗します。もう1つの落とし穴は、既にtmuxセッション内でClaude Codeを起動している場合です。teammateModeが「auto」の設定で既存のtmuxセッション内からClaude Codeを起動すると、自動的にSplit Paneモードが選択されますが、tmuxのネストセッションが意図せず作成されてしまうことがあります。この場合は明示的に--teammate-mode in-processフラグを付けて起動するか、teammateModeの設定をin-processに固定することで回避できます。

初回起動後にチームメイトが表示されない場合の5段階トラブルシューティングフロー

Agent Teamsの初回起動時に最もよく遭遇する問題が「チームメイトが表示されない」というケースです。この問題は複数の原因が考えられるため、以下の5段階で順番に確認することで効率的に原因を特定できます。

1. In-Processモードの場合、チームメイトは起動済みでも画面に表示されていないだけの可能性があります。Shift+Downキーを押してアクティブなチームメイトが存在するか確認してください。
2. 環境変数CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSが正しく「1」に設定されているか、echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSで確認します。
3. Claude Codeのバージョンが2.1.33以降であるかをclaude --versionで確認します。
4. 送信したプロンプトがチーム作成を正当化する複雑さを持っているか検討します。Claudeはタスクが単純すぎるとチームメイトのスポーンを見送ることがあります。明示的に「エージェントチームを作成してください」と指示を含めてみてください。
5. Split Paneモードを指定した場合は、tmuxまたはiTerm2のインストール状態とPATH設定を再確認します。

これらの手順で解決しない場合は、Claude Codeのセッションを完全に終了し、新しいターミナルウィンドウから再起動することで環境変数の反映漏れを解消できるケースが多く報告されています。

チームリード・タスクリスト・メールボックスで構成されるAgent Teamsの内部アーキテクチャ

Agent Teamsの動作を理解するためには、その内部アーキテクチャを把握することが不可欠です。チームリード、チームメイト、タスクリスト、メールボックスの4つのコンポーネントがどのように連携しているかを理解することで、トラブルシューティングの精度が上がり、より効果的なチーム構成の設計が可能になります。

チームリード・チームメイト・タスクリスト・メールボックスの4コンポーネントが担う役割の相関図

Agent Teamsは4つの主要コンポーネントで構成されています。チームリードはチームを作成した元のClaude Codeセッションで、チームメイトのスポーン、タスクの作成と割り当て、作業結果の統合を担当します。チームメイトはリードによって生成される独立したClaude Codeインスタンスで、それぞれが自分専用のコンテキストウィンドウを持ち、割り当てられたタスクを自律的に処理します。

タスクリストはチーム全体で共有される作業項目の一覧で、各タスクの状態と依存関係を管理します。メールボックスはエージェント間のメッセージングシステムで、チームメイト同士の直接通信やリードからの指示伝達に使用されます。これら4つのコンポーネントの相関関係として、リードがタスクリストを作成し、チームメイトがタスクをクレームして作業を開始します。作業中にチームメイト間で情報共有が必要になった場合はメールボックスを通じて直接通信し、タスクが完了するとタスクリストの状態が更新されてリードに通知が届きます。依存関係のあるタスクは自動的にアンブロックされ、次のチームメイトが着手可能になるという一連のフローが自律的に進行します。

タスクの3状態管理（pending・in progress・completed）とファイルロックによる競合防止の仕組み

タスクリスト内の各タスクは、pending（未着手）、in progress（作業中）、completed（完了）の3つの状態を遷移します。新しく作成されたタスクはpending状態で、チームメイトがそのタスクをクレームするとin progressに変わり、作業が完了するとcompletedに更新されます。さらに、タスク間には依存関係を設定でき、依存先のタスクがcompletedになるまで、依存元のタスクはクレームできない設計です。

複数のチームメイトが同時に同じタスクをクレームしようとした場合の競合を防ぐため、ファイルロック機構が採用されています。この仕組みはAnthropicのCコンパイラ構築プロジェクトでも使用されたアプローチと類似しており、gitの同期メカニズムに着想を得たものです。最初にロックを取得したチームメイトがタスクを獲得し、2番目以降のチームメイトは別のタスクを選択するよう誘導されます。ただし、既知の制限として、チームメイトがタスクのcompletedマークを付け忘れるケースがあり、これが依存タスクのブロックにつながることがあります。この場合は、リードに対して「タスクの状態を確認して更新してください」と指示するか、手動で対象のチームメイトに完了報告を促す必要があります。

チームメイト間のmessageとbroadcastの使い分けでトークンコストが2〜5倍変動する実測比較

Agent Teamsのメッセージング機能には、特定の1名に送るmessageと全チームメイトに一斉送信するbroadcastの2種類があります。messageは送信先が1名に限定されるため、トークン消費は送信元と受信先の2インスタンス分で済みます。一方、broadcastはチームメイト全員にメッセージが配信されるため、チームメイト数に応じてトークン消費が線形に増加します。

具体的な比較として、5名構成のチームでリードから全員に情報を共有する場合を考えます。messageを5回個別に送ると、各メッセージは受信者のコンテキストウィンドウにのみ追加され、合計5インスタンス分のトークンが消費されます。broadcastを1回使用した場合も同様に5インスタンス分が消費されますが、メッセージの内容が全員で同一であるため、リード側での送信処理は1回で済むという利点があります。問題はbroadcastの頻繁な使用で、チームメイトが10名の場合に10回broadcastを送ると、100インスタンス分のコンテキスト追加が発生し、トークンコストが大幅に膨張します。公式ドキュメントでも「broadcastはチームサイズに応じてコストがスケールするため、控えめに使用すること」と明記されています。基本方針として、特定の相手への情報共有にはmessageを使い、broadcastは全員に影響する重大な方針変更時のみに限定するのが費用対効果の面で最適です。

teams/{team-name}/config.jsonとtasks/ディレクトリに保存されるローカルデータの構造と管理方法

Agent Teamsの設定情報とタスクデータは、ローカルファイルシステムに保存されます。チーム設定は~/.claude/teams/{team-name}/config.jsonに格納され、membersという配列に各チームメイトの名前、エージェントID、エージェントタイプが記録されています。タスクリストは~/.claude/tasks/{team-name}/ディレクトリ以下に保存されます。

config.jsonのmembers配列は、チームメイトが他のメンバーを発見するためにも使用されます。各チームメイトはこのファイルを読み取ることで、チーム内の他のメンバーの存在を認識し、メッセージの送信先を特定できます。運用上の注意点として、チームのクリーンアップを実行せずにセッションを終了した場合、これらのファイルが残存し、次回のチーム作成時に競合を起こすことがあります。クリーンアップはリードに「チームをクリーンアップしてください」と指示することで実行されますが、アクティブなチームメイトが残っている状態では失敗するため、先にすべてのチームメイトをシャットダウンする必要があります。定期的に~/.claude/teams/ディレクトリを確認し、不要なチーム設定が残存していないかをチェックすることで、ストレージの肥大化と設定の競合を防止できます。

チームリードの権限設定がチームメイト全員に継承される仕様と個別変更時の注意点2つ

Agent Teamsでは、チームメイトはスポーン時にリードの権限設定をそのまま継承します。リードが--dangerously-skip-permissionsフラグで起動されていた場合、すべてのチームメイトも同じ権限で動作します。この仕様は利便性と安全性のトレードオフを含んでおり、特に本番環境に近いコードベースで作業する場合は慎重な判断が求められます。

スポーン後に個別のチームメイトの権限モードを変更することは可能ですが、2つの注意点があります。第一に、スポーン時にチームメイトごとに異なる権限を設定することはできないという制約があります。つまり、リードがスキップ権限で起動していると、すべてのチームメイトが一旦はスキップ権限で生成され、その後に個別に権限を絞る運用が必要になります。第二に、権限変更後もチームメイトが既に実行中の操作には影響しないため、権限を絞るタイミングはスポーン直後が望ましいという点です。実務上の推奨は、リードの権限設定を必要最小限に留め、よく使うファイル操作やコマンド実行をパーミッション設定でプリアプルーブしておくことです。これにより、過剰なパーミッションプロンプトの発生を抑えつつ、安全性も担保できます。

サブエージェントとAgent Teamsを判断基準ごとに使い分けるための比較と選定指針

Claude Codeで並列作業を行う方法は、サブエージェント、Agent Teams、Git Worktreeによる手動並列セッションの3つがあります。それぞれに適した場面があり、プロジェクトの特性やタスクの性質に応じた選択が費用対効果を最大化する鍵となります。ここでは判断基準ごとに各手法を比較し、実務での選定指針を提示します。

コンテキスト共有・通信方向・調整主体の3軸で整理するサブエージェントとAgent Teamsの構造差

サブエージェントとAgent Teamsは、いずれも作業を並列化する機能ですが、アーキテクチャレベルで根本的に異なります。この違いを理解するためには、コンテキスト共有、通信方向、調整主体の3つの軸で整理するのが効果的です。

この構造差を踏まえると、サブエージェントは「関数呼び出し」に、Agent Teamsは「チーム開発」に例えることができます。サブエージェントは入力を受け取って結果を返す単方向のワーカーであり、Agent Teamsのチームメイトは互いに情報を交換しながら問題を解決するチームメンバーです。どちらが優れているかではなく、タスクの性質に応じた使い分けが成果を左右します。

「結果だけ返せばよいタスク」と「議論・検証が必要なタスク」を分類する実務判断フローチャート

実務でサブエージェントとAgent Teamsのどちらを使うかを判断する際、最も有効な基準は「エージェント間のコミュニケーションが必要かどうか」です。この基準をもとに、タスクを以下のフローで分類できます。

まず、タスクが単一の明確な成果物を生成するものかどうかを確認します。「このファイルのテストを書いてください」「この関数のリファクタリング案を出してください」のように、入力と出力が1対1で対応するタスクは、サブエージェントが適しています。次に、タスクが複数の観点からの検証を必要とするかを判断します。コードレビューやバグの根本原因調査など、異なる視点からの分析を突き合わせる必要がある場合はAgent Teamsが効果的です。さらに、タスクの実行中に他のタスクの結果を参照する必要があるかを検討します。フロントエンドとバックエンドの同時開発のように、一方の設計がもう一方に影響する場合は、チームメイト間の直接通信が可能なAgent Teamsが必要です。最後に、コスト制約を確認します。予算が限られている場合は、サブエージェントの方がトークン効率が良いため、多少の品質トレードオフを許容してサブエージェントを選択する判断も合理的です。

トークン消費量の比較でサブエージェントが最大60%低コストになるケースの具体的条件

サブエージェントがAgent Teamsと比較して大幅にコストを抑えられるのは、いくつかの具体的な条件が揃った場合です。最もコスト差が顕著になるのは、タスクの成果物が短い要約やコード断片で十分に表現でき、エージェント間の情報交換が不要なケースです。

サブエージェントの場合、作業結果はメインエージェントのコンテキストに要約されて返却されるため、チームメイトが保持する長大なコンテキストを維持し続ける必要がありません。たとえば、5つの独立したファイルのコードレビューを並列実行する場合、サブエージェントであれば各レビュー結果を数百トークンの要約としてメインに返却するため、合計のトークン消費は比較的少量で済みます。同じタスクをAgent Teamsで実行すると、5つの独立したコンテキストウィンドウが維持され、さらにタスクリストの読み書きやメールボックスの通信コストが上乗せされるため、トータルでは最大60%程度のコスト増になる場合があります。逆に言えば、エージェント間の協調が不要で成果物が簡潔にまとまるタスクであれば、サブエージェントを選択することで同じ成果をより少ないトークンで得られるということです。コスト意識の高いチームでは、この判断基準を開発ガイドラインに組み込んでおくことが推奨されます。

Git Worktreeによる手動並列セッションを第3の選択肢として検討すべき規模と人数の目安

サブエージェントとAgent Teamsに加えて、Git Worktreeを使った手動並列セッションも有力な選択肢です。Git Worktreeは、1つのリポジトリから複数の作業ディレクトリを作成し、それぞれで独立したClaude Codeセッションを実行する方法です。自動的なチーム調整機能はありませんが、開発者が直接各セッションを管理するため、予期しない動作が起きにくいという利点があります。

Git Worktreeが適しているのは、開発者が2〜3名のチームで作業し、各メンバーの担当範囲が明確に分離されている場合です。たとえば、1人がフロントエンド、1人がバックエンド、1人がインフラを担当するような分業体制では、エージェント間の自動調整が不要なためGit Worktreeで十分です。Agent Teamsのコーディネーションオーバーヘッドがない分、トークンコストも抑えられます。一方で、5名以上の並列作業や、作業間の依存関係が複雑な場合は、手動管理の負荷が増大するためAgent Teamsの自動調整機能が有利になります。また、実験的にAgent Teamsの挙動を確認したい場合に、まずGit Worktreeで手動運用の感覚を掴んでからAgent Teamsに移行するという段階的アプローチも有効です。

プロジェクト規模別に最適な並列手法を選定するための3段階チェックリスト

並列手法の選定を効率化するために、プロジェクト規模に応じた3段階のチェックリストを提示します。このリストは実務での判断を高速化することを目的としており、各段階で最適な手法が異なります。

第一段階は、小規模タスク（1〜2時間で完了、独立した2〜3ファイルの変更）です。この規模では、サブエージェントが最も費用対効果に優れます。タスクが独立しており、結果の統合も単純なため、Agent Teamsのオーバーヘッドは正当化されません。第二段階は、中規模タスク（半日〜1日、5〜10ファイルにまたがる変更、複数の観点からの検証が必要）です。この規模では、Agent Teamsの3〜5名構成が効果を発揮します。並列レビューや競合仮説によるバグ調査など、エージェント間の協調が成果の品質を向上させます。第三段階は、大規模タスク（数日〜数週間、モジュール単位の大規模リファクタリングや新機能開発）です。この規模では、Agent TeamsとGit Worktreeを組み合わせ、モジュール単位でWorktreeを分離しつつ、各Worktree内でAgent Teamsを運用するハイブリッドアプローチが有効です。規模の判断に迷った場合は、まず小さく始めてサブエージェントで試し、効率が頭打ちになった時点でAgent Teamsへ段階的に移行するのが低リスクな方針です。

デリゲートモード・プラン承認・Hooksを活用した品質と統制を両立する運用設計

Agent Teamsの運用では、自律性と統制のバランスが品質に直結します。チームリードが実装作業に介入してしまう問題や、チームメイトが不十分な計画のまま作業を開始するリスクに対し、デリゲートモード、プラン承認、Hooksという3つの制御機構が用意されています。これらを組み合わせることで、人間の監視負荷を最小限に抑えながら高い品質基準を維持する運用が実現します。

Shift+Tabで有効化するデリゲートモードがリードの実装暴走を防止する仕組みと適用条件

Agent Teamsの運用で頻繁に報告されている問題の1つが、チームリードがチームメイトの完了を待たずに自ら実装作業を始めてしまう現象です。リードは本来オーケストレーションに専念すべきですが、タスクの内容が具体的だと自分で解決しようとする傾向があります。デリゲートモードは、この「リードの実装暴走」を防止するための機能です。

デリゲートモードの有効化は、チームを起動した後にShift+Tabキーを押すことで行います。デリゲートモードが有効になると、リードが使用できるツールはチームメイトのスポーン、メッセージング、シャットダウン、タスク管理の4つに制限され、ファイルの直接編集やコマンドの実行ができなくなります。これにより、リードはタスクの分解、チームメイトへの割り当て、作業結果の統合という本来の役割に集中できます。デリゲートモードが特に有効な場面は、5名以上の大規模チームを運用する場合や、複数のモジュールにまたがる複雑なタスクを扱う場合です。逆に、3名以下の小規模チームでリードにも実装を一部担当させたい場合は、デリゲートモードを無効のままにして柔軟に運用する方が効率的です。デリゲートモードはセッション中に切り替え可能なため、初動ではリードにも探索を許可し、チーム構成が安定した後にデリゲートモードに切り替えるという段階的な運用も可能です。

チームメイトに計画承認を義務付けるプラン承認フローの設定方法と承認基準の記述例

プラン承認は、チームメイトが実装に着手する前にリードの承認を必要とする品質ゲート機能です。リスクの高いタスクや、設計判断がプロジェクト全体に影響するタスクで特に有効です。設定はスポーンプロンプトに自然言語で記述するだけで有効化できます。

具体的な設定例として、「認証モジュールのリファクタリングを担当するアーキテクトチームメイトをスポーンしてください。変更着手前にプラン承認を必須とします」のようにプロンプトに記述します。プラン承認が有効なチームメイトは、まず読み取り専用のプランモードで動作し、コードベースの調査と実装計画の策定を行います。計画が完成すると、リードにプラン承認リクエストが送信されます。リードは計画を確認し、承認するか、フィードバック付きで却下するかを判断します。却下された場合、チームメイトはプランモードに留まったまま計画を修正して再提出します。承認基準の記述例としては、「テストカバレッジを含む計画のみ承認してください」「データベーススキーマを変更する計画は却下してください」のように、リードの判断基準をプロンプトに明示することで、承認プロセスの一貫性を保てます。リードは自律的に承認判断を行うため、基準が曖昧だと意図しない承認や却下が発生する点に注意が必要です。

TeammateIdleフックでexit code 2を返しチームメイトを稼働させ続ける品質ゲートの実装手順

TeammateIdleフックは、チームメイトがアイドル状態になろうとした際に自動実行されるスクリプトです。このフックでexit code 2を返すと、チームメイトにフィードバックメッセージが送信され、作業を継続させることができます。品質基準を満たしていない段階でチームメイトが作業を終了してしまう問題の防止に有効です。

実装手順としては、まずsettings.jsonのhooksセクションにTeammateIdleイベントのハンドラを登録します。ハンドラは任意のスクリプトを指定でき、たとえばテストカバレッジを検証するスクリプトを設定すれば、チームメイトがアイドルになる前にカバレッジが基準を満たしているかを自動チェックできます。テストカバレッジが80%未満であればexit code 2とともに「テストカバレッジが基準未達です。不足しているテストケースを追加してください」というメッセージを返し、チームメイトは追加作業を開始します。exit code 0を返した場合はチームメイトのアイドル遷移が許可されます。このフックを活用することで、人間が逐一チームメイトの作業品質を確認しなくても、自動的に品質基準を満たすまで作業が継続される仕組みを構築できます。ただし、フックの条件設定が厳しすぎるとチームメイトが無限ループに陥るリスクがあるため、最大リトライ回数の設定やタイムアウトの仕組みを併用することを推奨します。

TaskCompletedフックによるタスク完了条件の自動検証でレビュー漏れを防ぐ設定パターン

TaskCompletedフックは、タスクが完了マークされる際に実行されるスクリプトです。TeammateIdleフックと同様に、exit code 2を返すことでタスクの完了を阻止し、フィードバックを送信できます。この機能はタスクの完了条件を自動的に検証する品質ゲートとして機能します。

典型的な設定パターンとしては、以下の3つがあります。第一のパターンは、リンターやフォーマッターの自動実行です。タスク完了時にコードスタイルチェックを実行し、違反があればexit code 2で差し戻すことで、スタイルの一貫性を担保します。第二のパターンは、ユニットテストの自動実行です。タスクに関連するテストスイートを実行し、1つでも失敗があれば完了を阻止します。第三のパターンは、ビルド検証で、変更後のコードがビルドを通過するかを確認します。これら3つのパターンを組み合わせることで、リンター通過→テスト通過→ビルド成功の3段階の品質ゲートを自動化できます。フックスクリプトの実装自体はシェルスクリプトで行えるため、既存のCI/CDパイプラインで使用しているチェックスクリプトをそのまま流用できるケースが多く、導入の敷居は比較的低いと言えます。

権限プリセットとHooksの組み合わせで過剰なパーミッションプロンプトを80%削減した運用実例

Agent Teamsの運用で作業効率を大きく低下させる要因の1つが、チームメイトからの過剰なパーミッションプロンプトです。チームメイトの権限リクエストはリードに集約されるため、5名のチームで全員が頻繁にファイル操作を行うと、リードの処理がパーミッション応答で詰まる事態が発生します。

この問題に対する実践的な対処法は、パーミッション設定でよく使う操作をプリアプルーブしておくことです。具体的には、プロジェクトディレクトリ内のファイル読み書き、テストコマンドの実行、gitの基本操作などを事前に許可リストに登録します。ある開発チームの事例では、ファイル操作系のパーミッション5項目とコマンド実行系の3項目をプリアプルーブに設定した結果、チームメイトからのパーミッションプロンプトが従来の約80%削減され、リードがオーケストレーションに集中できる環境が実現しました。さらに、Hooksを組み合わせて危険な操作（本番データベースへの接続やルートディレクトリ外への書き込み）をフック段階でブロックすることで、広めのプリアプルーブ設定でもセキュリティリスクを抑制できます。プリアプルーブの設定はチームを起動する前に行うのが鉄則で、チームメイトがスポーンされた後に設定を変更しても、既存のチームメイトには即時反映されないケースがあるためです。

並列コードレビューやバグ調査など現場で成果を出すAgent Teamsの実務活用パターン

Agent Teamsの真価は、具体的な開発タスクに適用した際の成果で測定されます。公式ドキュメントやコミュニティで報告されている活用パターンを分析すると、並列コードレビュー、競合仮説によるバグ調査、クロスレイヤー同時開発、専任エージェントによる品質維持の4つの領域で特に高い効果が確認されています。

セキュリティ・パフォーマンス・テストカバレッジの3観点同時レビューで発見率が向上する構成例

単一のレビューアに複数の観点を任せると、1つの観点に偏りやすいという課題があります。たとえば、セキュリティに注目し始めると、パフォーマンスの問題を見逃しやすくなる認知バイアスが働きます。Agent Teamsでは、各観点に特化したチームメイトを並列に配置することで、このバイアスを構造的に解消できます。

公式ドキュメントで紹介されている構成例では、PR #142のレビューに3名のチームメイトをスポーンし、1名はセキュリティの影響評価、1名はパフォーマンスへの影響確認、1名はテストカバレッジの検証にそれぞれ専念させています。各レビューアは同じPRを異なるフィルターで分析し、発見事項をリードに報告します。リードは3つの観点からの報告を統合し、総合的なレビュー結果を作成します。この構成の利点は、各チームメイトが自分の専門領域に集中できるため、観点の切り替えコストがゼロになることです。実際の運用では、スポーンプロンプトに「JWTトークンのハンドリングとセッション管理に焦点を当て、重要度評価をつけて報告してください」のように具体的な評価基準を含めることで、レビュー結果の粒度と実用性が向上します。3観点の同時レビューにかかる時間は、逐次レビューの約3分の1に短縮されるとの報告もあります。

競合仮説方式によるバグ調査で5エージェントが互いの理論を検証し根本原因を特定する手法

バグの根本原因調査において、単一エージェントは最初に見つけたもっともらしい説明に固執しやすいという問題があります。これはアンカリングバイアスと呼ばれる認知的な偏りで、人間の開発者にも共通する課題です。Agent Teamsでは、複数のエージェントにそれぞれ異なる仮説を割り当て、互いの仮説に反論させる「競合仮説方式」でこの偏りを解消できます。

Anthropicの公式ドキュメントに記載されている構成例では、「アプリが1つのメッセージ送信後に切断される問題」に対して5名のチームメイトをスポーンし、各メンバーに異なる仮説を調査させています。重要なのは、各チームメイトに自分の仮説を調査するだけでなく「他のメンバーの理論に反論する」という明示的な指示を与えている点です。科学的な討論のような構造を作ることで、反証に耐えた仮説が根本原因である可能性が高まります。逐次調査では1つの仮説を検証してから次に進むため、最初の仮説にバイアスがかかりやすいのに対し、並列調査では独立した複数の視点が同時に検証されるため、真の原因を見逃すリスクが大幅に低減します。調査結果はチームメイト間のメッセージングで共有され、最終的にリードが合意形成を行い、findings docに結論を記録します。

フロントエンド・バックエンド・テストの3レイヤー同時開発でリリースサイクルを短縮する設計

新機能の開発では、フロントエンド、バックエンド、テストの3つのレイヤーが互いに依存関係を持ちながら進行します。従来の単一セッションでは、API設計→バックエンド実装→フロントエンド実装→テスト作成という逐次的なフローになりがちでした。Agent Teamsでは各レイヤーを専任のチームメイトに割り当て、並列に開発を進めることが可能です。

この構成が機能するためのポイントは、各チームメイトの担当ファイルが重複しないようにタスクを分割することです。バックエンド担当はsrc/api/以下、フロントエンド担当はsrc/components/以下、テスト担当はtests/以下のように、ディレクトリレベルで所有権を分離します。インターフェースの取り決めはリードがタスクリストの依存関係として定義し、バックエンド担当がAPI仕様を確定させたタスクが完了すると、フロントエンド担当のAPI接続タスクが自動的にアンブロックされる設計にします。チームメイト間のメッセージングを活用すれば、仕様の疑問点をリアルタイムでやりとりすることも可能です。ただし、同一ファイルの同時編集は上書き事故の原因となるため、共通の型定義ファイルやコンフィグファイルなどの変更はリードまたは1名の担当者に集約する運用が推奨されます。

ドキュメント整備・コード品質監視・パフォーマンス最適化を専任エージェントに分離する役割設計

Agent Teamsの並列処理能力は、メインの開発タスクだけでなく、品質維持の専任エージェントを配置する用途にも活用できます。Anthropicのエンジニアリングブログで紹介されたCコンパイラ構築プロジェクトでは、メインの開発エージェントに加えて、重複コードの統合担当、コンパイラ自体のパフォーマンス改善担当、出力コードの効率化担当、Rustの設計品質担当、ドキュメント担当という5つの専任エージェントが設置されていました。

この役割分離のアプローチは、規模の大きなプロジェクトで特に効果を発揮します。メインの開発エージェントは新機能の実装に集中でき、コード品質やドキュメントの整備は専任エージェントが継続的に監視・改善します。実務で採用する場合は、まず開発エージェント2〜3名とドキュメント担当1名の構成から始め、必要に応じてコード品質担当やパフォーマンス担当を追加するのが段階的で安全なアプローチです。専任エージェントのスポーンプロンプトには「Rustの設計観点からプロジェクト全体を批評し、構造的な改善を提案してください」のように、明確な役割定義と権限範囲を記述することで、メインの開発エージェントの作業と衝突しない運用が可能になります。

初回導入時にリサーチ・レビュー系タスクから始めるべき理由と段階的拡張の成功パターン

Agent Teamsの公式ドキュメントでは、初めて利用する場合は「リサーチ・レビュー系のタスクから始めること」が明確に推奨されています。この推奨には、技術的な合理性とリスク管理の両面から根拠があります。

リサーチやレビュー系のタスクは、成果物がコードの変更ではなく報告書や分析結果であるため、チームメイト間のファイル競合が発生しません。万が一チームメイトの出力品質が低くても、コードベースに直接影響しないため、安全に機能の挙動を確認できます。また、レビューの結果は人間が容易に検証可能であり、Agent Teamsの品質がプロジェクトの基準に適合するかの評価が容易です。段階的拡張の成功パターンとしては、第一段階でPRレビューやライブラリ調査をAgent Teamsで実行し、チームの動作特性とコスト感を把握します。第二段階で、独立した新規モジュールの開発をAgent Teamsに任せ、並列実装の効果を確認します。第三段階で、既存コードのリファクタリングや機能追加など、より複雑で影響範囲の広いタスクに適用を拡大します。各段階で2〜3のタスクを試行し、コスト、品質、所要時間のデータを蓄積することで、自チームにとって最適なAgent Teamsの活用範囲を客観的に判断できるようになります。

トークンコスト・ファイル競合・セッション孤立など導入後に直面する課題と具体的な対処法

Agent Teamsは強力な並列開発機能を提供しますが、リサーチプレビュー段階ということもあり、導入後にいくつかの典型的な課題に直面することがあります。トークンコストの膨張、ファイルの同時編集による上書き事故、リードの早期シャットダウン、tmuxセッションの残存、セッション復元の制限が代表的な問題です。いずれも事前に対処法を把握しておくことで影響を最小限に抑えられます。

チームメイト数×コンテキストウィンドウで膨張するトークンコストを抑制する3つの実践的手法

Agent Teamsのトークンコストはチームメイト数に比例して増加するため、無計画にチームメイトを増やすとコストが急激に膨張します。コストを抑制しながら並列処理の恩恵を最大化するためには、3つの実践的な手法が有効です。

第一の手法は、チームメイトのモデルをSonnet 4.5に指定することです。リードには判断力の高いOpus 4.6を使用し、実装を担当するチームメイトにはSonnet 4.5を割り当てることで、トークン単価を約40%削減できます。第二の手法は、チームメイト数を必要最小限に留めることです。3〜5名の範囲がスループットとコストのバランスが最も良く、それ以上増やしてもコーディネーションオーバーヘッドがスループット向上を打ち消す傾向があります。第三の手法は、broadcastメッセージの使用を最小限に抑え、特定のチームメイトへのmessageで情報共有を行うことです。broadcastはチームメイト全員のコンテキストにメッセージを追加するため、頻繁に使用するとコンテキストの肥大化とトークン消費の増加を招きます。これら3つの手法を組み合わせることで、単一セッションと比較したコスト増を2〜3倍程度に抑えながら、作業速度は2〜3倍に向上するという費用対効果の高い運用が実現できます。

2名以上が同一ファイルを編集した場合の上書き事故を防ぐファイル所有権分離の設計原則

Agent Teamsで最も深刻な実害をもたらすのが、複数のチームメイトが同一ファイルを同時に編集した際の上書き事故です。各チームメイトは独立したコンテキストで動作しているため、他のチームメイトの変更をリアルタイムで認識できません。結果として、後から保存した変更が先の変更を上書きし、作業が消失する可能性があります。

この問題を防ぐための設計原則は「1ファイル1オーナー」です。チームの構成を設計する段階で、各チームメイトが編集するファイルまたはディレクトリを明確に分離します。たとえば「バックエンド担当はsrc/api/のみ、フロントエンド担当はsrc/components/のみ、テスト担当はtests/のみを編集すること」のように、スポーンプロンプトで所有権を明示します。共通のファイル（設定ファイル、型定義、共有ユーティリティなど）の変更が必要な場合は、1名のチームメイトまたはリードに担当を集約し、その変更が完了するまで他のチームメイトの関連タスクをブロック状態にしておきます。Anthropicの公式ベストプラクティスでも「2人のチームメイトが同じファイルを編集すると上書きにつながります。各チームメイトが異なるファイルセットを所有するように作業を分割してください」と明記されています。

リードがチームメイト完了前に終了する「早期シャットダウン問題」の検知と再指示の具体的な文言

Agent Teamsの運用で意外と頻繁に発生するのが、チームリードがすべてのチームメイトの作業完了を待たずにチームを終了させてしまう問題です。リードがタスクの一部が完了した時点で「全体が完了した」と判断してしまうケースや、チームメイトの応答が遅延している間にリードが待ちきれず終了するケースが報告されています。

この問題を検知するには、リードが統合作業に入った段階でタスクリストを確認し、すべてのタスクがcompleted状態になっているかを目視チェックします。チームメイトにまだin progress状態のタスクが残っている場合は、リードに対して明確な指示を送る必要があります。効果的な指示の文言としては「チームメイトがすべてのタスクを完了するまで進めないでください。各チームメイトの作業状況を確認して、全員の完了を待ってから結果を統合してください」が推奨されます。予防策としては、チーム作成の初期プロンプトに「すべてのチームメイトのタスクがcompletedになるまで、結果の統合やクリーンアップを行わないでください」という制約を含めておくことが有効です。デリゲートモードを有効にしている場合はリードが実装作業を行えないため、この問題がやや軽減される傾向がありますが、完全には防げないため、プロンプトでの明示が依然として重要です。

tmuxセッションが残存するオーファン問題のkillコマンドと再発防止のクリーンアップ手順

Split Paneモードで運用する場合、チームの終了処理が正常に完了しないとtmuxセッションがバックグラウンドに残存する「オーファンセッション」問題が発生することがあります。オーファンセッションはシステムリソースを消費し続けるだけでなく、次回のチーム作成時にセッション名の競合を引き起こす可能性があります。

オーファンセッションの確認と解消は、ターミナルでtmux lsコマンドを実行することから始めます。表示されたセッション一覧の中に、Agent Teamsが作成したセッション名（通常はチーム名を含む）が残っていれば、それがオーファンです。tmux kill-session -t {session-name}コマンドで該当セッションを終了できます。再発防止のためには、チームの終了時に必ず正しいクリーンアップ手順を踏むことが重要です。まず、リードに「すべてのチームメイトをシャットダウンしてください」と指示し、全員が停止したことを確認してから「チームをクリーンアップしてください」と指示します。クリーンアップはアクティブなチームメイトが存在すると失敗するため、この順序は厳守です。定期的にtmux lsを実行してオーファンの有無を確認する運用を習慣化しておくと、リソースリークの蓄積を防止できます。

セッション再開時にin-processチームメイトが復元されない制限への対処と新規スポーン戦略

Agent Teamsの既知の制限の中で実務への影響が最も大きいのが、セッション再開時にIn-Processモードのチームメイトが復元されないという問題です。/resumeコマンドでリードのセッションを再開しても、以前のチームメイトは復元されません。その結果、リードが存在しないチームメイトにメッセージを送ろうとしてエラーが発生することがあります。

この制限に対する現時点での対処法は、セッション再開後にリードに新しいチームメイトをスポーンするよう指示することです。具体的には「以前のチームメイトは復元されていません。同じ構成で新しいチームメイトをスポーンしてください」と伝えます。このとき、以前のチームの作業成果がコードベースに反映されていれば、新しいチームメイトはCLAUDE.mdとコードベースの現在の状態から作業を継続できます。予防策としては、長時間のチーム運用では定期的にチームメイトに作業成果をコミットさせるプロンプトを含めておくことが効果的です。これにより、万が一セッションが切断されても、コードベース上の変更は保持されます。また、重要な中間成果物やタスクの進捗状況をファイルに記録するよう指示しておけば、新しいチームメイトがスポーン後にその記録を参照して効率的に作業を再開できます。

Cコンパイラ構築事例に学ぶ16エージェント並列運用の成果と限界の実測データ

Agent Teamsの能力を最も象徴的に示すのが、Anthropicの研究者Nicholas Carlini氏が実施したCコンパイラ構築プロジェクトです。16のエージェントを並列に稼働させ、Rust製のCコンパイラを自律的に構築するこの実験は、Agent Teamsの現時点での可能性と限界を具体的な数値で示しています。

2,000セッション・2Bインプットトークン・約$20,000で10万行のRust製Cコンパイラを生成した全体像

このプロジェクトでは、Claude Opus 4.6を使用した16のエージェントが約2週間にわたり稼働し、計約2,000のClaude Codeセッションが実行されました。消費されたトークンはインプット20億トークン、アウトプット1億4,000万トークンで、総コストは約$20,000です。その成果物は、Rustの標準ライブラリのみに依存する10万行のCコンパイラでした。

このコンパイラは完全なクリーンルーム実装であり、開発中のエージェントにはインターネットアクセスが一切与えられていませんでした。成果物の能力としては、Linux 6.9をx86、ARM、RISC-Vの3アーキテクチャでビルドできるほか、QEMU、FFmpeg、SQLite、PostgreSQL、Redisのコンパイルにも成功しています。コストだけを見ると$20,000は高額に見えますが、人間のエンジニアチームが同等のコンパイラを開発した場合のコストと比較すると桁違いに低いとCarlini氏は述べています。ただし、この規模のプロジェクトは一般的な開発タスクとは異なり、テスト駆動型の自律エージェント運用を前提としたハーネス設計が不可欠であったという点は重要です。

GCC torture test suite 99%通過率とLinux 6.9ビルド成功に至るまでのテスト設計の工夫

16エージェントによる自律開発で品質を担保するために、Carlini氏はテスト設計に最も多くの労力を投じたと報告しています。エージェントが自律的に正しい方向へ進むためには、テスト検証器がほぼ完璧である必要があるからです。テスト検証器に欠陥があれば、エージェントは誤った方向に最適化してしまいます。

テスト設計の工夫は大きく3つあります。第一に、GCCのtorture test suiteを含む高品質なコンパイラテストスイートを採用し、基本的なコンパイル機能の網羅性を確保しました。最終的に99%の通過率を達成しています。第二に、SQLiteやRedisなどの実際のオープンソースプロジェクトをビルド対象として追加し、テストスイートだけではカバーできない実用的な互換性を検証しました。第三に、プロジェクトの後半で新機能実装時に既存機能が壊れる退行問題が多発したため、CI（継続的インテグレーション）パイプラインを構築し、新しいコミットが既存のテストを破壊しないことを自動検証する仕組みを導入しました。この3層のテスト設計が、10万行規模のコードベースを自律エージェントが管理可能にした最大の要因です。

GCCをオラクルとした差分コンパイル手法で16エージェントの並列効率を最大化した戦略

プロジェクトの後半でLinuxカーネルのコンパイルに挑戦した際、並列化の効率に関する重大な問題が発生しました。Linuxカーネルのビルドは1つの巨大なタスクであり、テストスイートのように独立した小さなテストに分割できなかったため、16のエージェント全員が同じバグに取り組み、互いの修正を上書きし合うという非効率な状態に陥ったのです。

この問題を解決したのが、GCCを「既知の正解を出すオラクル」として活用する差分コンパイル手法です。カーネルのソースファイルの大部分をGCCでコンパイルし、残りのファイルのみをClaude製コンパイラでコンパイルする構成を取りました。カーネルが正常に動作すれば、Claude製コンパイラが担当したファイルに問題はないと判断でき、動作しなければそのファイル群にバグがあると特定できます。さらに、GCCで再コンパイルするファイルを絞り込むことで、バグのあるファイルを効率的に特定するデルタデバッグ技法も適用されました。この手法により、各エージェントが異なるファイルのバグ修正を並列に担当できるようになり、16エージェントの並列効率が大幅に改善しました。この戦略は、大規模なビルドタスクを並列化する際の汎用的なパターンとして参考になります。

コンテキスト汚染・時間感覚の欠如など自律エージェント固有の弱点に対処したハーネス設計

16エージェントの長時間自律運用で明らかになったのが、LLMエージェント固有の弱点です。Carlini氏は「テストハーネスはClaude向けに書いており、自分向けではない」と述べ、人間の開発者とは異なるLLMの特性に合わせた設計が必要だったと報告しています。

最も深刻だったのがコンテキスト汚染の問題です。テストハーネスが大量のログを出力すると、その情報がコンテキストウィンドウを圧迫し、エージェントの判断精度が低下します。対策として、テスト出力を数行に絞り、詳細なログはファイルに書き出す設計にしました。ログファイルのフォーマットも工夫し、エラー発生時はERRORという文字列と理由を同一行に記述することで、grepによる自動検索が容易になるようにしています。もう1つの弱点が時間感覚の欠如です。Claudeは時間の経過を認識できないため、放置するとテスト実行に何時間もかけてしまいます。これに対しては、インクリメンタルな進捗表示を低頻度で出力し、デフォルトで全テストの1%または10%のランダムサンプルを実行する--fastオプションを用意しました。このサンプルはエージェントごとに決定論的でありながらVM間ではランダムになるよう設計されており、各エージェントが少ないテストで退行を検知しつつ、全体では全ファイルをカバーする仕組みです。

16bit x86コード生成の失敗やコード品質の限界から見える現時点のOpus 4.6の能力境界

10万行のCコンパイラという成果は印象的ですが、Carlini氏はその限界についても率直に報告しています。最も象徴的な失敗が、16bit x86コード生成の実装です。Linuxのブート処理には16bitリアルモードのコード生成が必要ですが、Opus 4.6はこの実装に成功できませんでした。

技術的には、66/67オペコードプレフィックスを使った16bit x86出力自体は可能でしたが、生成されたコードが60KB以上になり、Linuxが要求する32KBのコードサイズ制限を超えてしまうという問題を解決できませんでした。結果としてx86環境ではGCCに16bitコード生成を委任する形になっています。ただし、ARMとRISC-Vではこの制約がないため、Claude製コンパイラ単独でLinuxカーネルの完全なビルドに成功しています。それ以外の限界として、生成されるRustコードの品質が専門家の水準には達していない点、全最適化を有効にしてもGCCの最適化無効時より非効率なコードを出力する点、新機能の追加時に既存機能が壊れる退行が頻発する点が挙げられています。これらの限界は、現時点のLLMエージェントが「ほぼ達成できるが完璧にはできない」境界線を示しており、Agent Teamsの活用範囲を検討する際の現実的な参考指標になります。

Agent Teamsを組織の開発フローへ段階的に定着させるためのロードマップと判断基準

Agent Teamsの導入は一度に全面展開するのではなく、段階的に進めるのが成功確率を高めるアプローチです。リサーチプレビュー段階の機能であることも踏まえ、小さく始めて効果を検証しながら適用範囲を拡大するロードマップと、各段階での判断基準を提示します。

フェーズ1：単一タスクのサブエージェント運用で基礎を固める最初の2週間の具体的な目標設定

Agent Teamsに直接飛び込む前に、まずサブエージェントの運用で並列処理の基礎を固めることを推奨します。サブエージェントはAgent Teamsと比較してシンプルな構造であり、トークンコストも低く、トラブルシューティングも容易です。最初の2週間で、Claude Codeの並列処理の動作特性を把握しておくことが、Agent Teams導入後のスムーズな運用につながります。

具体的な目標としては、第1週でサブエージェントを使った単純なタスク並列化を3〜5回実行し、トークンコストと作業時間のベースラインデータを取得します。たとえば、既存のテストファイルの分析や、コードベースの特定ディレクトリのレビューなど、結果が検証しやすいタスクが適しています。第2週では、やや複雑なタスク（複数ファイルにまたがるリファクタリング提案など）をサブエージェントで実行し、成果物の品質を評価します。この2週間で蓄積したデータは、Agent Teamsの費用対効果を評価する際の比較基準として活用できます。また、CLAUDE.mdの整備やパーミッション設定の最適化など、Agent Teams導入時にも必要となる基盤整備をこの段階で済ませておくことで、フェーズ2への移行がスムーズになります。

フェーズ2：3人構成のAgent Teamsでコードレビュー並列化を試行する際の成功指標と撤退基準

フェーズ1の基礎固めが完了したら、3名構成の小規模Agent Teamsでコードレビューの並列化を試行します。3名という規模は、Agent Teamsのコーディネーション機能を体験しつつ、トークンコストとトラブルシューティングの負荷を低く抑えられるバランスの良い構成です。

成功指標としては、以下の3項目を設定することを推奨します。第一に、3観点の並列レビューが逐次レビューと比較して同等以上の品質を達成しているか。第二に、トークンコストがフェーズ1のサブエージェント運用と比較して3倍以内に収まっているか。第三に、チームの起動からレビュー結果の統合まで、人間の介入回数が5回以内で完結しているかです。撤退基準としては、トークンコストがサブエージェント比で5倍以上に膨張する場合、チームメイトの出力品質が明らかにサブエージェント以下の場合、またはトラブルシューティングに作業時間の30%以上を費やしている場合は、現時点でのAgent Teams導入を見送り、サブエージェントでの運用を継続する判断が妥当です。リサーチプレビューの更新で改善される可能性があるため、撤退した場合でも定期的な再評価をスケジュールに組み込んでおくことを推奨します。

フェーズ3：本番開発ワークフローへの統合時にCI/CDパイプラインと連携させる設計上の要点

フェーズ2で十分な成果が確認できたら、本番の開発ワークフローへのAgent Teams統合を検討します。この段階では、既存のCI/CDパイプラインとの連携が品質を担保する上で重要な設計要素になります。

CI/CDとの連携において最も効果的なのは、TaskCompletedフックとTeammateIdleフックをCIパイプラインの検証スクリプトと接続することです。チームメイトがタスクを完了しようとした際に、自動的にリンター、ユニットテスト、ビルド検証を実行し、すべてをパスした場合のみ完了を許可する品質ゲートを構築します。Cコンパイラ構築プロジェクトでも、後半にCI/CDパイプラインを導入したことで新しいコミットが既存機能を壊すことが大幅に減少したと報告されています。ブランチ戦略としては、Agent Teamsの作業をフィーチャーブランチで実行し、全タスク完了後にリードが結果を統合してPRを作成する流れが推奨されます。メインブランチへの直接コミットは、Agent Teamsの作業品質がまだ完全には信頼できない段階では避けるべきです。チームメイトに定期的なコミットを促すプロンプトを含めておくことで、長時間の作業が消失するリスクも軽減できます。

月間トークン予算の設定とモデル混在戦略（Opus＋Sonnet）で費用対効果を最大化する計算式

Agent Teamsを継続的に運用するためには、月間のトークン予算を事前に設定し、その範囲内で最大の成果を得るための戦略が必要です。予算設定の基本式は「1セッションあたりの平均トークン消費量 × チームメイト数 × 月間セッション数」で算出できます。

Claude Codeの公式ドキュメントによれば、Sonnet 4.5を使用した場合の平均的な月間コストは1開発者あたり$100〜$200です。Agent Teamsで3名のチームメイトを使用すると、この数値が3〜4倍になるため、月間$300〜$800が目安となります。コストを最適化するモデル混在戦略では、チームリードにOpus 4.6（$5/$25/MTok）を配置し、実装担当のチームメイトにはSonnet 4.5（$3/$15/MTok）を指定します。この構成により、オーケストレーションの判断精度を維持しながら、全員Opusの場合と比較して約30〜40%のコスト削減が可能です。さらに、タスクの複雑さに応じてサブエージェントとAgent Teamsを使い分けることで、単純なタスクはサブエージェントで低コストに処理し、Agent Teamsは複雑な協調タスクにのみ投入するという選択的運用が費用対効果を最大化します。月間予算は最初は控えめに設定し、実績データに基づいて四半期ごとに見直すアプローチが現実的です。

リサーチプレビュー終了後の正式リリースに備え今から整備すべきCLAUDE.mdとスキル資産の棚卸し

Agent Teamsは現在リサーチプレビュー段階であり、正式リリース時には機能の追加や仕様変更が行われる可能性があります。しかし、Agent Teamsの根幹であるCLAUDE.mdやスキル定義といったプロジェクトコンテキスト資産は、正式リリース後もそのまま活用できる基盤です。今のうちからこれらの資産を整備しておくことで、正式リリース時にスムーズに本格運用へ移行できます。

CLAUDE.mdの整備では、プロジェクトの技術スタック、ディレクトリ構造、命名規約、テスト実行方法、デプロイ手順を網羅的に記載します。Agent Teamsではチームメイトがリードの会話履歴を引き継がないため、CLAUDE.mdに記載された情報の網羅性がチームメイトの初動品質を決定します。スキル定義については、繰り返し使用するレビュー基準やリファクタリングパターンをスキルとして定義し、チームメイトが即座に参照できるようにしておきます。また、パーミッション設定のプリアプルーブリストや、Hooks用のバリデーションスクリプトも資産として整理します。これらの資産は、Agent Teamsだけでなく通常のClaude Code運用やサブエージェントの品質向上にも寄与するため、リサーチプレビュー段階で投資しても無駄にはなりません。現時点での制限事項と正式リリースで期待される改善点を記録しておけば、移行計画の策定もスムーズになります。