サブエージェント連携モード¶
想象一下：你让 Claude 帮你重构一个大模块，但在重构之前，你需要它先搞清楚三件事 — 现有的 API 接口有哪些、数据库 schema 是什么样的、测试覆盖率如何。在普通模式下，Claude 只能串行地一件一件查。但如果它能同时派出三个"分身"去分别调查呢？
这就是子代理的魅力。
サブエージェントとは¶
Agent ツールの概念¶
サブエージェント（Subagent）は Claude Code における特殊なツールであり、メインセッションが独立した Claude インスタンスを作成して特定のタスクを実行することを可能にします。これは「Claude が助手を採用した」と考えることができます。
メインセッションの Claude はプロジェクトマネージャーであり、全体を统筹します。深入調査が必要なサブタスクに遭遇した場合、サブエージェントを起動して专门的に处理させ、自分では他の作業を進め続けます。
サブエージェントとメインセッションの違い¶
| 特性 | メインセッション | サブエージェント |
|---|---|---|
| コンテキスト | 完全な对话履歴を含む | 独立したコンテキストウィンドウ、タスク記述のみを含む |
| ライフサイクル | Claude Code を閉じるまで継続 | タスク完了後に自動終了 |
| ツールアクセス | 授權済みすべてのツール | 特定のツールサブセットに制限可能 |
| 実行方式 | あなたとの対話型对话 | 自律的に実行し、結果を返す |
| コンテキスト消費 | すべての操作が同じコンテキストを消費 | メインセッションのコンテキストを消費しない |
| 結果 | 直接表示 | 概要形式でメインセッションに返す |
最も重要な違いは独立したコンテキストウィンドウです。サブエージェントは独自のコンテキスト空間を持有しており、探索過程がメインセッションのコンテキストを圧迫ことはありません。最終結果のみがメインセッションに送り返されます。これは、出張先に調査に行ってもらった後、プロセス全体を再現するのではなく、レポートを提出してもらうようなものです。
独立コンテキストウィンドウの優位性¶
なぜ独立コンテキストがこんなに重要なのか？实际的な例を挙げてみましょう：
假设你需要 Claude 分析一个有 200 个文件的项目。如果在主会话中逐个读取文件，每个文件平均 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 の比較結果は次のようになります：
三个子代理已完成分析。综合对比如下：
| 評価ディメンション | 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 にサブエージェントをいつ、どのように使用するかを誘導できます：
## サブエージェント使用規範
### いつサブエージェントを使用するか
- 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. サブエージェントを過度に使用しない¶
サブエージェントは万能ではありません。以下场景はメインセッションで直接处理する方が効率的です：
- 単純なファイル表示：一两つのファイルを読むだけで、直接
@で参照すれば OK - 単純な検索：一つのキーワードを検索する場合、メインセッションで行う方が速い
- 持続的な対話が必要なタスク：サブエージェントは「一回限り」であり、複数回合の対話が必要なタスクには不向き
- 前ステップの結果に依存するシリアルタスク：サブエージェントを使用すると反而複雑さが増す
経験則：タスクが一两句话で明確に描述でき，大量ファイルを読み取る必要がない場合は、メインセッションで直接行ってでください。
4. サブエージェントの結果伝達メカニズムを理解する¶
サブエージェントがタスクを完了すると、結果はサマリー形式でメインメッセージに送られます。这意味着：
- サブエージェントが読み取ったファイル原文は完全には送り返されない（が大きすぎるため）
- サブエージェントの分析結論と主要情報のみが送り返される
- サブエージェントが見つけた特定のファイルを見る必要がある場合、メインセッションで再度読む必要があります
サブエージェントから payment_service.py の 127 行目に問題があると聞きました。
このファイルの 120-140 行を見せてください。
5. サブエージェントを「试探性」操作に使用する¶
某一方案が実行可能かどうか不确定ですか？サブエージェントで试探し、メインブランチでリスクを取らないでください：
サブエージェントで実験してみてください：
1. 一時ディレクトリ /tmp/experiment を作成
2. src/models/user.py をコピー
3. dataclasses で SQLAlchemy の宣言型モデルを置き換えてみる
4. 什么问题があるか確認
プロジェクトのファイルを触らないでください。
进阶：サブエージェント与其他機能の組み合わせ¶
サブエージェント + Plan モード¶
Plan モードでもサブエージェントを使用できます。これは強力な組み合わせです — サブエージェントで計画段階で深入調査を行います：
（Plan モード）
サブエージェントで以下の問題を調査してもらい、调查结果に基づいて移行プランを作成してください：
1. 現在すべての REST API のエンドポイントリストと呼び出し頻度
2. どのエンドポイントにすでに GraphQL の同等功能があるか
3. クライアントコードでの REST API への依存度
サブエージェント + MCP ツール¶
MCP サーバー（データベース查询ツールなど）を設定している場合、サブエージェントも它们を使用できます：
サブエージェントでデータベースに接続し、以下の内容を分析してください：
1. 各テーブルのデータ量
2. スロークエリ Top 10
3. 不足しているインデックス
データベース MCP ツールでクエリを実行してください。
サブエージェント + Hooks¶
Hook を使用して、サブエージェントが特定の操作を実行する際にカスタムロジックをトリガーできます。例えば、サブエージェントがテストを完了した後に自動的に通知を送信する：
{
"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 はメインセッションにサブエージェントの実行ステータスを表示します。どのサブエージェントが起動されたか、各サブエージェントが何をとしているか、完了したかどうかを確認できます。