## サブエージェント連携モード 想像してみてください。あなたは Claude に大きなモジュールのリファクタリングを頼みたいのですが、その前に三つのことを把握してもらう必要があります — 既存の API インターフェースには何があるのか、データベースの schema はどうなっているのか、テストカバレッジはどの程度か。通常モードでは、Claude はこれらを一つずつ順番にしか調べられません。しかし、もし同時に三人の「分身」を送り出してそれぞれ別々に調査させられるとしたら？ これがサブエージェントの魅力です。 ## サブエージェントとは ### Agent ツールの概念 サブエージェント（Subagent）は Claude Code の特殊なツールの一種であり、メインセッションが独立した Claude インスタンスを作成して特定のタスクを実行することを可能にします。これは「Claude が助手を雇った」と理解することができます。 メインセッションの Claude はプロジェクトマネージャーであり、全体を統括する役割を担います。深く調査する必要のあるサブタスクに遭遇すると、サブエージェントを起動して専門的に処理させ、自分自身は他の作業を進め続けることができます。 ### サブエージェントとメインセッションの違い | 特性 | メインセッション | サブエージェント | |------|--------|--------| | コンテキスト | 完全な会話履歴を含む | **独立したコンテキストウィンドウ**、タスク記述のみを含む | | ライフサイクル | Claude Code を閉じるまで継続 | タスク完了後に自動終了 | | ツールアクセス | 認可済みのすべてのツール | 特定のツールのサブセットに制限可能 | | 実行方式 | あなたとの対話型のやり取り | 自律的に実行し、完了後に結果を返す | | コンテキスト消費 | すべての操作が同じコンテキストを消費 | **メインセッションのコンテキストを消費しない** | | 結果 | 直接表示 | 概要形式でメインセッションに返す | 最も重要な違いは**独立したコンテキストウィンドウ**です。サブエージェントは独自のコンテキスト空間を持っており、その探索過程がメインセッションのコンテキストを膨張させることはありません。最終結果のみがメインセッションに送り返されます — これは、誰かを出張させて調査してもらい、その人が戻ってきたときに調査過程全体を逐一報告するのではなく、一通のレポートだけを渡してもらうようなものです。 ### 独立コンテキストウィンドウの優位性 なぜ独立したコンテキストがこれほど重要なのでしょうか。実際の例を挙げてみましょう。 たとえば、200 個のファイルを持つプロジェクトを Claude に分析させる必要があるとします。メインセッションでファイルを一つずつ読み取ると、各ファイルが平均 200 行として、ファイルの内容だけで 40000 行のコンテキストを占めてしまいます。さらに Claude の分析過程が加わると、あっという間にコンテキストがいっぱいになってしまいます。 サブエージェントを使えば話は別です。サブエージェントは自分自身のコンテキストの中でこれらのファイルを読み取って分析し、最後に数百行の分析レポートだけを返します。メインセッションのコンテキストはほとんど増加せず、後続の作業を続けるための十分なスペースが残ります。 ## 内蔵サブエージェントタイプ Claude Code のサブエージェントは、実際には固定された「タイプ」があるわけではなく、メインセッションがタスクの性質に応じて柔軟に作成します。ただし実践においては、サブエージェントは通常、以下のような役割を担います。 ### Explore（コード検索と探索） これは最も一般的なサブエージェントの用途です。Claude がプロジェクトのある側面を理解する必要があるとき、Explore サブエージェントを起動します。 **能力**： - ファイルの読み取り（Read） - コードの検索（Grep、Glob） - ディレクトリ構造の確認 - コードの依存関係の分析 **制限**： - 通常は読み取り専用ツールのみが付与される - ファイルを変更できない - コマンドを実行できない **典型的なシナリオ**： ``` src/services/ ディレクトリ下のすべてのサービスのパブリックインターフェースを分析する UserService を参照しているすべてのファイルを見つける 認証ミドルウェアのワークフローを理解する ``` ### Plan（アーキテクチャ設計と計画） 計画の立案や設計案の作成に使用されるサブエージェント。 **能力**： - Explore のすべての能力 - ウェブ検索（ドキュメントやベストプラクティスの調査） - 詳細な設計案ドキュメントの生成 **典型的なシナリオ**： ``` キャッシュ層のアーキテクチャ設計案を作成する REST から GraphQL への移行の実現可能性を評価する データベースのテーブル分割戦略を策定する ``` ### 汎用タスク（General-Purpose） 具体的な実行タスクを処理するサブエージェントで、完全なツールアクセス権を持ちます。 **能力**： - ファイルの読み書き - コマンドの実行 - テストの実行 - 依存関係のインストール **典型的なシナリオ**： ``` バックグラウンドで完全なテストスイートを実行する API ドキュメントを生成する コードフォーマットを実行する ``` ## サブエージェントを使うシナリオ ### シナリオ 1：コードの検索と理解 Claude に不慣れなコードベースを深く理解させる必要があるとき、サブエージェントは効率的に探索を完了できます。 ``` このプロジェクトを引き継いだばかりなので、アーキテクチャを全体的に把握するのを手伝ってください： 1. サブエージェントでバックエンドのディレクトリ構造とコアモジュールを分析する 2. サブエージェントでフロントエンドのコンポーネントツリーと状態管理を分析する 3. サブエージェントでデータベースの schema とエンティティ関係を分析する そのうえで三つの側面の情報を総合して、プロジェクトのアーキテクチャ概要をください。 ``` Claude は三つのサブエージェントを並列に起動してこれらのタスクを実行し、その後それらのレポートをまとめる、という動き方をするかもしれません。 ### シナリオ 2：複数の方式を並列で調査する 複数の技術方式を比較する必要があるとき、サブエージェントの並列能力は非常に役立ちます。 ``` プロジェクト用にメッセージキューを選ぶ必要があります。以下の方式をそれぞれ調査してください： 1. Redis Streams — 既存の Redis 設定が対応しているか確認する 2. RabbitMQ — 新しい依存関係を導入するコストを評価する 3. PostgreSQL の LISTEN/NOTIFY を直接使う 各方式について、メリット・デメリットと、私たちのプロジェクトとの互換性を分析してください。 ``` ### シナリオ 3：長時間タスクをバックグラウンドで実行する 一部のタスク（テストの実行、ドキュメントの生成など）は時間がかかるため、サブエージェントに渡してバックグラウンドで実行できます。 ``` プロジェクトの完全なテストスイートをバックグラウンドで実行してください。私は他の作業を続けます。 テストが終わったら結果を教えてください。 ``` Claude はテストを実行するバックグラウンドサブエージェントを起動するので、あなたは待つ必要なく、メインセッションとの会話を続けることができます。 ### シナリオ 4：高リスクな操作を隔離する リスクを伴う可能性のある操作を実行する必要があるとき、サブエージェントを使って隔離できます。 ``` サブエージェントで以下の操作を試してください： 1. 一時ブランチに切り替える 2. React を 19.x にアップグレードしてみる 3. ビルドを実行し、互換性エラーがいくつ出るか確認する 4. エラーのリストを私に送る メインブランチでは操作しないでください。 ``` ## サブエージェント実践チュートリアル ### 例 1：サブエージェントで不慣れなコードベースを理解する 中規模の Python プロジェクト（約 50 個のソースファイル）を引き継いだ初日を想定してください。その構造を素早く把握する必要があります。 **あなたのプロンプト：** ``` このプロジェクトを引き継いだ初日なので、プロジェクトへの理解を素早く築くのを手伝ってください。 サブエージェントを使って以下の側面を並列に分析してください： 1. プロジェクト構造とエントリポイント — ディレクトリ構造をスキャンし、main エントリ、ルーティング定義、設定ファイルを見つける 2. データモデル — すべての model ファイルを分析し、エンティティ関係を描き出す 3. ビジネスロジック — services ディレクトリを分析し、コアとなるビジネスプロセスを理解する 4. 外部依存関係 — requirements.txt と実際の import を分析し、主要な依存関係を見つける 最後にすべての情報を総合して、500 字以内のプロジェクト概要をください。 ``` **Claude の実行過程：** Claude は複数のサブエージェントを作成し、それぞれにタスクを実行させます。各サブエージェントは独立して探索を行い、結果を返します。全体の過程では、おおよそ次のような出力が表示されます。 ``` 4 個のサブエージェントを起動して並列分析を開始しています... [サブエージェント 1] プロジェクト構造を分析中... - 52 個の Python ファイルをスキャン - エントリポイントを発見：main.py → FastAPI app - ルーティング定義は routers/ ディレクトリ（8 個のルーティングモジュール） - 設定：config.py + .env [サブエージェント 2] データモデルを分析中... - 12 個の SQLAlchemy モデルを発見 - コアエンティティ：User, Organization, Project, Task, Comment - 主要な関係：User ← many-to-many → Organization, Project → has-many → Task [サブエージェント 3] ビジネスロジックを分析中... - 9 個の service ファイル - コアプロセス：ユーザー管理、プロジェクト管理、タスク割り当て、通知システム - 非同期タスク処理に Celery を使用 [サブエージェント 4] 外部依存関係を分析中... - 32 個の直接依存関係 - 主要な依存関係：FastAPI, SQLAlchemy, Celery, Redis, Alembic - 未使用の依存関係を 2 個発見（requests, beautifulsoup4） ``` 最後に Claude は四つのサブエージェントの結果を総合して、構造の明確なプロジェクト概要をくれます。 ### 例 2：複数のサブエージェントを並列に起動して方式を比較する リアルタイム通知機能をどう実装するか検討していて、いくつかの方式を比較したいとします。 ``` プロジェクトにリアルタイム通知機能を追加する必要があります。以下の三つの方式を並列で評価してください： 方式 A：WebSocket（FastAPI 内蔵の WebSocket サポートを使用） 方式 B：Server-Sent Events（SSE） 方式 C：ポーリング（Polling） 各方式について、以下を分析してください： 1. 既存アーキテクチャとの互換性（既存のコードを確認） 2. 実装の複雑さ（おおよそ何ファイルを変更する必要があるか） 3. パフォーマンスとスケーラビリティ 4. クライアントの互換性 そのうえで、比較表とあなたの推奨をください。 ``` **Claude の比較結果は次のようになるかもしれません：** ``` 3 個のサブエージェントが分析を完了しました。総合的な比較は以下のとおりです： | 評価軸 | WebSocket | SSE | ポーリング | |----------|-----------|-----|------| | アーキテクチャ互換性 | 新しい WebSocket ルートの追加が必要 | 既存の HTTP ルートを再利用可能 | 完全に互換 | | 実装の複雑さ | 高（約 8 ファイル） | 中（約 4 ファイル） | 低（約 2 ファイル） | | リアルタイム性 | 最良（全二重） | 良好（サーバー側プッシュ） | 普通（ポーリング間隔に依存） | | スケーラビリティ | WebSocket の負荷分散が必要 | CDN が利用可能 | 最もシンプル | | Celery 統合 | 追加のメッセージブリッジが必要 | Celery イベントを直接消費可能 | データベースをポーリングするだけでよい | **推奨**：すでに Celery + Redis を使用していることを考慮すると、SSE が最良の選択です。 Redis チャンネルを購読して Celery イベントを直接取得でき、実装の複雑さは中程度で、 かつ追加のインフラストラクチャも不要です。 ``` ### 例 3：バックグラウンドサブエージェントでテストを実行する コードを修正しながら、同時にテスト結果も知りたいとします。 ``` バックグラウンドで pytest を実行し、テストスイート全体を走らせてください。私はコードの修正を続けるので、終わったら教えてください。 ``` Claude はテストを実行するバックグラウンドサブエージェントを起動します。あなたは Claude との会話やコードの修正を続けることができます。テストが完了すると、結果の通知が表示されます。 ``` バックグラウンドのテストが完了しました。結果： - 合計：247 個のテスト - 成功：241 個 - 失敗：4 個 - スキップ：2 個 失敗したテスト： 1. test_order_service.py::test_calculate_total_with_discount AssertionError: 99.99 != 100.0 2. test_user_service.py::test_create_user_duplicate_email IntegrityError: テストデータベースが正しくクリーンアップされていない 3. ... これらの失敗したテストの分析をお手伝いしましょうか？ ``` ## サブエージェントの設定 ### CLAUDE.md でサブエージェントの動作を誘導する サブエージェントのパラメータを直接「設定」することはできませんが、`CLAUDE.md` を使って、Claude がいつ、どのようにサブエージェントを使用するかを誘導できます。 ```markdown ## サブエージェント使用規範 ### いつサブエージェントを使うか - 10 ファイルを超える分析タスクには、サブエージェントを使用すべき - 複数の方式を比較する必要があるときは、各方式ごとに独立したサブエージェントを起動する - テストの実行はバックグラウンドサブエージェントで行うべき ### サブエージェントのタスク記述テンプレート サブエージェントを起動するとき、タスク記述には以下を含めるべき： 1. 明確な目標（何をするか） 2. 範囲の制限（何をしないか） 3. 出力フォーマット（どのような結果を返すか） ### サブエージェントの結果処理 サブエージェントの結果には、以下を含めるべき： - 分析サマリー（200 字以内） - 主要な発見のリスト - 関連するファイルパス - 潜在的なリスクや問題 ``` ### サブエージェントが利用できるツールを理解する サブエージェントがどのツールを使用できるかは、メインセッションがそれにどのような認可を与えるかによって決まります。実践においては： - **読み取り専用タスク**：通常は Read、Grep、Glob などの検索ツールのみを付与する - **実行タスク**：Bash、Write、Edit などの書き込みツールを付与する - **ネットワークタスク**：WebSearch、WebFetch などのネットワークツールを付与する 自然言語によってツールの範囲をほのめかすことができます。 ``` サブエージェントで（読み取り専用で）src/models/ ディレクトリ下のすべてのモデルの関係を分析してください。 ``` 「読み取り専用」というヒントを加えることで、Claude は検索と読み取りの能力のみを持つサブエージェントを作成する傾向になります。 ### バックグラウンド実行 サブエージェントはバックグラウンドで実行でき、あなたとメインセッションのやり取りをブロックしません。「バックグラウンドで...」や「非同期で...」と言うと、Claude は `run_in_background` パラメータを使用します。 ``` バックグラウンドで以下の二つのことをしてください： 1. 完全な lint チェックを実行する 2. すべての依存関係に既知のセキュリティ脆弱性がないか確認する 私はコードの修正を続けるので、完了したら結果を教えてください。 ``` バックグラウンドサブエージェントが完了すると、システムが Claude に通知し、Claude がその結果をあなたに伝えます。 ## ベストプラクティス ### 1. サブエージェントに明確なタスク記述を与える サブエージェントのコンテキストはまっさらな状態です — あなたが以前メインセッションで何を話したかを知りません。そのため、タスク記述は自己完結していなければなりません。 **悪いやり方：** ``` サブエージェントで、さっき言ったあの問題をチェックしてください。 ``` （サブエージェントは「さっき言ったあの問題」が何かを知りません） **良いやり方：** ``` サブエージェントで src/services/payment_service.py の process_refund() メソッドが、並行する払い戻しリクエストを正しく処理しているかどうかを確認してください。 データベーストランザクションの分離レベルと楽観ロックの使用に注目してください。 ``` ### 2. 並列サブエージェントをうまく使って効率を上げる 複数のタスクの間に依存関係がない場合は、それらを並列に実行させましょう。 ``` 以下のタスクを並列で実行してください： 1. [サブエージェント A] フロントエンドコードのすべての API 呼び出し箇所を分析する 2. [サブエージェント B] バックエンドの API エンドポイントとパラメータ定義を分析する 3. [サブエージェント C] API ドキュメントが実際のインターフェースと一致しているか確認する 三つのタスクが完了したら、API が一致していない箇所をまとめてください。 ``` ### 3. サブエージェントを過剰に使わない サブエージェントは万能ではありません。以下のシナリオでは、メインセッションで直接処理するほうが効率的です。 - **単純なファイルの閲覧**：1～2 個のファイルを読むだけなら、直接 `@` で参照すればよい - **単純な検索**：一つのキーワードを検索するだけなら、メインセッションで行うほうが速い - **継続的なやり取りが必要なタスク**：サブエージェントは「使い切り」であり、複数回の対話が必要なタスクには向かない - **前のステップの結果に依存する直列タスク**：サブエージェントを使うとかえって複雑さが増す 経験則：タスクが一言二言で明確に説明でき、かつ大量のファイルを読み取る必要がないなら、メインセッションで直接行いましょう。 ### 4. サブエージェントの結果伝達の仕組みを理解する サブエージェントがタスクを完了すると、その結果は**サマリー形式で**メインセッションに送り返されます。これが意味するのは： - サブエージェントが読み取ったファイルの原文は**完全には送り返されない**（大きすぎるため） - サブエージェントの分析結論と主要な情報だけが送り返される - サブエージェントが見つけた特定のファイルを確認する必要がある場合は、メインセッションで自分でもう一度読み直す必要がある ``` サブエージェントが payment_service.py の 127 行目に問題があると言っていました。 このファイルの 120-140 行を見せてください。 ``` ### 5. サブエージェントを「試行的」な操作に使う ある方式が実行可能かどうか確信が持てませんか。メインブランチでリスクを冒すのではなく、サブエージェントを使って試してみましょう。 ``` サブエージェントで実験をしてみてください： 1. 一時ディレクトリ /tmp/experiment を作成する 2. src/models/user.py をそこにコピーする 3. SQLAlchemy の宣言型モデルを dataclasses で置き換えてみる 4. どんな問題が出るか確認する プロジェクトのファイルには一切手を触れないでください。 ``` ## 応用：サブエージェントと他の機能の組み合わせ ### サブエージェント + Plan モード Plan モードでもサブエージェントを使用できます。これは強力な組み合わせです — サブエージェントを使って、計画段階で深い調査を行うのです。 ``` （Plan モードにて） サブエージェントで以下の問題を調査してもらい、その調査結果に基づいて移行計画を立ててください： 1. 現在のすべての REST API のエンドポイントリストと呼び出し頻度 2. すでに GraphQL の同等実装があるエンドポイントはどれか 3. クライアントコードにおける REST API への依存度 ``` ### サブエージェント + MCP ツール MCP サーバー（データベースクエリツールなど）を設定している場合、サブエージェントもそれらを使用できます。 ``` サブエージェントでデータベースに接続し、以下の内容を分析してください： 1. 各テーブルのデータ量 2. スロークエリ Top 10 3. 不足しているインデックス データベースの MCP ツールを使ってクエリを実行してください。 ``` ### サブエージェント + Hooks Hooks を使って、サブエージェントが特定の操作を実行したときにカスタムロジックをトリガーできます。たとえば、サブエージェントがテストを完了したときに自動的に通知を送る、といったことです。 ```json { "hooks": { "Notification": [ { "hooks": [ { "type": "command", "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\": \"$MESSAGE\"}'" } ] } ] } } ``` ## よくある質問 **Q：サブエージェントは私とメインセッションの会話履歴を見ることができますか？** A：できません。サブエージェントのコンテキストはまっさらな状態で、Claude がそれに与えたタスク記述のみを含みます。これが、タスク記述が自己完結していなければならない理由でもあります。ただし、サブエージェントは `CLAUDE.md` を読み取れるので、プロジェクトレベルの規範や取り決めはサブエージェントにも有効です。 **Q：サブエージェントは「サブサブエージェント」を起動できますか？** A：できますが、あまり深くネストすることはおすすめしません。通常は一層のサブエージェントで十分です。 **Q：複数のサブエージェント同士は通信できますか？** A：直接通信することはできません。サブエージェント B がサブエージェント A の結果に依存する必要がある場合は、A の完了を待ってから、メインセッションがその結果を B に渡すしかありません。 **Q：サブエージェントは追加の API クォータを消費しますか？** A：はい。サブエージェントは独立したコンテキストウィンドウを使用するため、各サブエージェントの入力と出力はいずれもトークンを消費します。ただし、サブエージェントのコンテキストは通常小さい（特定のタスクのみを含む）ため、同じことをメインセッションで行う場合よりも、全体の消費は少なくて済むことが多いです。 **Q：サブエージェントが今何をしているかは、どうすればわかりますか？** A：Claude はメインセッションにサブエージェントの実行ステータスを表示します。どのサブエージェントを起動したか、各サブエージェントが何をしているか、すでに完了したかどうかを確認できます。