サブエージェント（多くの場合、 サブエージェント or サブエージェント）は、エージェント開発ツールにおける最も明確な実用的な進歩の1つです。これにより、専門のAIアシスタントの小さなチームを内部で構成できるようになります。 クロード・コードそれぞれが独自の役割、ツール、コンテキストウィンドウを備えています。このアイデアはシンプルですが強力です。単一の汎用モデルにあらゆる処理を任せるのではなく、コンパクトで単一目的のエージェントを定義し、メインオーケストレーターがそれらのエージェントに作業を委任します（自動または明示的に要求された場合）。これにより、複雑なワークフローにおけるコンテキスト、ツール、そしてコストとレイテンシのトレードオフの管理方法が変わります。
サブエージェントとは何ですか?
短い定義。 サブエージェントとは、Claude Codeがタスクを委任できる、事前設定されたタスク特化型のAI「パーソナリティ」です。各サブエージェントは、独自のシステムプロンプト、独自の（分離された）コンテキストウィンドウ、明示的に許可されたツール、そしてオプションでモデル選択を持ちます。サブエージェントはプロジェクトレベルまたはユーザーレベルで作成でき、Claude Codeによって自動的に、またはユーザーによって明示的に呼び出されます。
サブエージェントの主な特性
- 特殊な目的とシステムプロンプト。 サブエージェントの役割、制約、アプローチをシステムプロンプトに記述して、その狭いドメイン内で予測どおりに動作するようにする（例： コードレビュー担当者, デバッガ, データサイエンティスト).
- 分離されたコンテキスト ウィンドウ。 各サブエージェントは独自の会話履歴とコンテキストを保持し、メインスレッドのコンテキストが低レベルの詳細によって汚染されるのを防ぎます。これは、単一の会話のコンテキストを使い果たしてしまうようなワークフローをスケーリングする上で中心的な役割を果たします。
- ツールのスコープと権限。 サブエージェントが使用できる内部ツールまたは外部のモデルコンテキストプロトコル（MCP）ツールを許可または制限できます。これは、安全性とガバナンスにとって非常に重要な機能です。
- コードとして構成します。 サブエージェントは、YAMLフロントマター（名前、説明、ツール、モデル）を含むMarkdownファイルとして定義され、プロジェクトレベル（
.claude/agents/) またはユーザーレベル (~/.claude/agents/）。プロジェクト定義が優先されます。
自動委任と明示的な呼び出しとは何か
クロード・コードは 自動的に プロンプトまたはサブエージェントがサブエージェントにタスクを委任する場合 description タスクに一致するか、 明示的 エージェントをリクエストする（例： > Use the code-reviewer subagent to check my recent changes）。 description 行動指向（"Use PROACTIVELY", "MUST BE USED") は自動委任を促進するために、Claude Code でサブエージェントを使用する 2 つの補完的な方法を提供します。
- 自動委任 — クロードはリクエストを検査し、一致する作業をサブエージェントに積極的に委任します。
- 明示的な呼び出し — プロンプト/コマンドでサブエージェントの名前を呼び出します（例：
Use the code-reviewer subagent to check my changes).
どちらのアプローチも、UXとエンジニアリングの面で異なるトレードオフがあります。以下でそれぞれについて詳しく説明します。
自動委任
ユーザーにどのように見えるか。 高レベルのコマンド（例えば、「この新しいライブラリのセキュリティ監査を準備する」）を発行すると、クロードは、 description 設定でフィールドを設定します。プロアクティブに使用するように設定されている場合、サブエージェントは自動的にディスパッチされ、結果を構造化された出力として返します。
チームがそれを使用する理由。
- 認知負荷が軽減されます。すべてのサブエージェント名を覚えたり入力したりする必要がなくなります。
- 特定のタスクを常に同じスペシャリストが処理する必要がある共有ワークフローのオンボーディングがスムーズになります。
注意事項。
- 設計する必要がある
descriptionシステムは意図的にプロンプトを表示し、クロードが確実に正しいサブエージェントを選択できるようにします。 - 過度の委任により、多くのサブエージェントが同様のタスクに対してアクティブ化する場合、トークンの使用とノイズが増加する可能性があります。説明は慎重に設計してください。
明示的な呼び出し
ユーザーにどのように見えるか。 サブエージェントを明示的に呼び出します。 > Use the test-runner subagent to run the project testsオーケストレーションは決定論的です。Claude は、事前に構成された権限とプロンプトを使用して、名前付きサブエージェントを呼び出します。
チームがそれを使用する理由。
- 完全な制御: どのスペシャリストを実行するかを正確に決定できるため、デバッグと再現性が簡素化されます。
- CI または自動化されたスクリプトでのコストとツール アクセスについて簡単に判断できます。
注意事項。
- より多くの入力と規律: 開発者または自動化担当者は、正しいサブエージェント名を知っている必要があります。
- 機会主義的ではない: メインエージェントが適切なサブエージェントを自動的に検出する利便性がいくらか失われます。
サブエージェントの仕組み - 技術概要
以下は、サブエージェントを作成して使用する場合の動作を、実用的かつ実装指向で説明したものです。
サブエージェントの定義（コードとしての構成）
サブエージェントは、YAMLフロントマターを含むMarkdownファイルです。重要なフィールドは以下のとおりです。
name— 一意の小文字のID（ハイフン付き）description— 自動委任マッチングに使用される自然言語記述tools— 許可されたツールのオプションのコンマリスト（または省略するとすべてのツールが継承されます）model— オプションのエイリアス（sonnet,opus,haiku）またはinheritメイン会話のモデルを使用する
小さな例 (概念的なものであり、ドキュメントからの逐語的引用ではありません):
---
name: code-reviewer
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Bash
model: inherit
---
You are a senior code reviewer. Focus on security, correctness, and maintainability.
これらのファイルは以下のいずれかに保存されます .claude/agents/ （プロジェクト範囲）または ~/.claude/agents/ （ユーザースコープ）。プロジェクトファイルが優先されるため、サブエージェントの共有とバージョン管理が簡単になります。
モデルの選択とツール
- モデル分野: サブエージェントには特定のモデルエイリアスを指定するか、メインの会話モデルを継承させることができます。これにより、コストと品質のトレードオフを組み合わせることができます（例えば、大規模なデータスキャンを行うサブエージェントには安価なモデルを使用し、最終的な合成には高品質のモデルを使用するなど）。
- ツールのスコープ: 各サブエージェントに最小限のツールセットを与えることで、爆発半径が縮小し、安全性に関する推論が簡素化されます。ツールには、標準的なClaude Codeプリミティブ（Read、Grep、Bash、Editなど）とMCPが提供する統合機能が含まれます。
実行時の動作とコンテキスト処理
クロードがサブエージェントに委任すると、そのサブエージェントは次のものを受け取ります。
- システムプロンプト (YAML/Markdown コンテンツ)。
- 必要なコンテキストのみ (独自のコンテキスト ウィンドウ)。
- 設定で許可されたツールへのアクセス。
各サブエージェントは独立したコンテキストを保持するため、長い調査や大きなファイルの分析を、1 つのコンテキストにすべてを保持させるのではなく、多数の小さなコンテキストに分解できます。これは、信頼性と解釈可能性の両方にとって大きなメリットです。
サブエージェントのアーキテクチャパターン
最も一般的なアーキテクチャは オーケストレーター （メインエージェント）は高レベルのタスクを分解し、複数のサブエージェントを起動し、それらの出力を合成または検証します。一般的には2つの典型的なパターンが見られます。
1) オーケストレーター + スペシャリスト
1人のエージェント（ オーケストレーター）は、複数のサブエージェントを並列または直列に調整します。オーケストレーターは、どのスペシャリストを呼び出すかを決定し、出力を集約し、整合性を検証し、最終的な統合を実行します。これは一般的な「マネージャーがチームメンバーに委任する」アプローチであり、Claude Codeの資料に記載されている多くの例や推奨設計と一致しています。利点としては、並列処理、明確な関心の分離、エラーの封じ込めの容易さ（バグのあるサブエージェントは自身のスコープのみに影響する）などが挙げられます。
いつ使用するか： 独立したサブ問題を持つ複雑なタスク（例：「テストの生成」、「静的分析の実行」、「モジュールの書き換え」、そして「エンドツーエンドのテストを統合して実行」）。
トレードオフ: オーケストレーション ロジックは複雑になる可能性があり、追加のラウンドトリップによりレイテンシがわずかに増加する可能性があります。
2) パイプライン/チェーンスペシャリスト
ここでは、サブエージェントは、あるエージェントの出力が次のエージェントの入力となるような順序で配置されています（例：spec → scaffold → implement → test → optimize）。これは本質的には、エージェントとして表現された関数合成です。段階的な変換や、ステージ間のデータの流れについて厳密な保証が必要な場合に便利です。線形ワークフローでは概念的に単純化され、デバッグが容易になる場合もあります。
いつ使用するか： 決定論的な複数ステップの変換 (たとえば、設計ドキュメントをスキャフォールディングされたコードに変換し、次にテスト、次に最適化する)。
トレードオフ: 広範な調査 (調査、ブレインストーミング) を必要とするタスクには不自然であり、1 つのリンクが壊れるとパイプライン全体が停止する可能性があります。
サブエージェントは単なるロールベースのプロンプトと何が違うのでしょうか?
1) 個別のコンテキストウィンドウ
各サブエージェントは、それぞれの役割に関連する交換、ファイル、メタデータを格納する独自のコンテキストバッファを持ちます。これにより、メインセッションのコンテキストがノイズの多い中間メッセージによって汚染されることを防ぎ、また、各機能の履歴を保存（または制限）することも可能です。このようにして、Claude Codeは、すべてを1つのプロンプトに詰め込むことによるトークンコストや認知的オーバーヘッドを負担することなく、特殊なタスクのために長寿命で高シグナルのコンテキストを保持できます。
2) システムプロンプトとペルソナ
サブエージェントは、役割、動作、制約を定義するシステムレベルの指示（例：「リファクタリングスペシャリストとしてのみ動作し、シェルコマンドを実行しない」や「pytest 形式でユニットテストを生成し、パブリックインターフェースのみを使用する」など）に基づいて作成されます。これらの指示はサブエージェントのジョブ記述のような役割を果たし、Claude Code のランタイムによって実行時に強制的に適用されます。
3) ツールのバインディングと権限のスコープ
重要な実用上の違いは、サブエージェントは特定のツール（ファイルシステム、プロセス実行、外部API、特権データセットなど）へのアクセスを許可または拒否できることです。これにより、サブエージェントは次のような点で強力になります。 最小特権 設計：ドキュメントジェネレータは任意のコマンドの実行をブロックできる一方、CIサブエージェントには隔離されたサンドボックスが与えられます。多くのコミュニティ投稿では、サブエージェントをモデルコンテキストプロトコル（MCP）またはフックベースのMCPサーバーと組み合わせることで、シークレットとI/Oへの安全なアクセスを管理することが推奨されています。
4) モデルの選択とコストパフォーマンスのトレードオフ
サブエージェントはモジュール式であるため、タスクの複雑さに応じて異なる基盤モデルを割り当てることができます。深層推論には高性能なSonnetモデルを、高速で反復的なタスクには軽量なHaikuモデルを使用します。この異種混合のデプロイメントにより、レイテンシ、トークンコスト、そして能力のバランスを取ることができます。Anthropicの製品アップデートとコミュニティ記事では、コスト効率の高いスケーリングを実現するために、小規模なモデルの並列デプロイメントが強調されています。
5) コミュニケーションパターン
サブエージェントは、構造化されたメッセージまたはファイルを介してオーケストレーター（またはサブエージェント同士）と通信します。典型的なパターンは次のとおりです。
- 構造化されたJSONペイロードを返す（プログラムによるオーケストレーションに推奨）
- 共有ワークスペース内のスコープファイルへの書き込み、
- または、信頼スコアと根拠を含む最終的なフォーマットされたメッセージをオーケストレーターに送り返します。
コミュニティの実験では、チームは曖昧さを避けるために、明示的で機械可読な引き継ぎを好むことが示されています。
パフォーマンス上の利点
サブエージェントは単なるデザインの美しさだけではなく、正しく使用すると実用的なパフォーマンスと品質の利点ももたらします。
1) 並列処理によるウォールクロック時間の短縮
複数のワーカーを同時にディスパッチすることで（例えば、リポジトリフォルダごと、マイクロサービスごと、またはデータチャンクごとに1つのワーカー）、オーケストレーターは大規模な複合タスクの完了に必要な経過時間を短縮します。バグレポートのトリアージ、多数のモジュールのドキュメント生成、複数のサービスの監査といったユースケースに最適です。ワークロードが真に並列化可能な場合、開発者のワークフローが大幅に高速化されます。
各ロールに独自のコンテキストを与えることで、プロンプトの肥大化を防ぎ、無関係な履歴ノイズによる幻覚リスクを軽減できます。つまり、コンテキスト関連の失敗が減り、特殊なタスクの出力がより一貫性を持つということです。コミュニティのレポートやAnthropic独自の調査によると、マルチエージェント構成は、幅優先タスクにおいてモノリシックエージェントよりも優れたパフォーマンスを発揮することが多いことが示されています。Anthropicの社内評価では、リードエージェント＋サブエージェントのアーキテクチャを用いたリサーチスタイルのタスクにおいて、劇的な改善が報告されています。
注意：並列処理は、サブタスクが独立しているときに最大の効果を発揮します。ワーカーが常に互いを待機したり、大きな状態を共有したりする必要がある場合、効果は減少します。
2) コンテキストの活用が向上し、トークンの無駄が減る
ワーカーは、中間検索結果を単一のグローバルコンテキストに詰め込むのではなく、関連するものだけを自身のウィンドウ内に保持し、抽出した出力を返します。これにより、オーケストレーターのトークン消費量が削減され、コンテキスト制限に達するリスクも軽減されます。これは、大規模なコードベース、長いログ、または巨大なドキュメントリポジトリを扱う際に大きなメリットとなります。SDKの圧縮/要約機能は、長時間実行されるエージェントの実効メモリをさらに拡張します。
3) 専門家のアドバイスによる精度の向上
狭いスコープのスペシャリストとして構築されたサブエージェントは、システムプロンプトとツールセットを介して調整することで、セキュリティチェック、コードスタイル、コンプライアンス抽出といったドメインにおける精度を最適化することができます。エージェントの許容アクション空間と期待される出力が制限されるため、スコープが狭いプロンプトでは幻覚症状が軽減される傾向があります。組織は、ジェネラリストにすべてを任せるのではなく、ドメイン特化型のサブエージェントを使用することで、自動コードレビューなどのタスクにおいてより高品質な出力が得られると報告しています。
チームが実際にサブエージェントを使用する方法 - ワークフローの例
以下に、より抽象的な内容にならないように具体的な例を示します。
例 A - パイプラインのリファクタリング (オーケストレーター + スペシャリスト)
- Orchestrator は「コンポーネント X のリファクタリング」リクエストを受け取ります。
- オーケストレーターコール
analysis-subagent(書き込み権限なし) 複雑性のホットスポットとリスクのある依存関係を特定します。 - オーケストレーターコール
refactor-subagent(ブランチのようなサンドボックスに権限を書き込む) リファクタリングされたファイルを生成します。 - オーケストレーターコール
test-gen-subagent(コード上では読み取り専用) ユニット テストを生成します。 - オーケストレーターはCIを実行します
ci-runner-subagent（サンドボックス実行）し、人間によるレビューのために結果を集約します。
このパターンは各フェーズを分離し、リスクを抑制し、監査証跡を整理します。
例B — リサーチ + プロトタイプ（パイプライン）
literature-subagent参照をスクレイピングして要約します (ファイルの書き込みなし、Web アクセスは規制されています)。prototype-subagent要約から最小限の PoC を構築します。benchmark-subagentサンドボックスでマイクロベンチマークを実行し、結果を報告します。
このチェーンにより、責任を明確に保ちながら、研究タスクの連続性が強化されます。
ベストプラクティスとパターン
設計と構成
- 小さくて狭い役割から始めましょう。 各サブエージェントに明確な1つのジョブを担当させます。責任範囲を限定することでデバッグがはるかに容易になります。
- バージョン管理
.claude/agents/フォルダにコピーします。 サブエージェントの定義をコードのように扱い、レビュー、テスト、バージョンの固定を行います。これにより、ドリフトが軽減され、監査が容易になります。 - ツールとモデルを意図的にピン留めします。
model: inheritメインの会話と一貫した動作が必要な場合は、バックグラウンドスキャン用の低コストのモデルエイリアスを指定します。ツールをロックダウンして、攻撃対象領域を最小限に抑えます。
運用パターン
- 確定的な自動化には明示的な呼び出しを使用します。 CI ジョブまたはフックを実行している場合は、予測可能な結果を確実に得るために特定のサブエージェントを呼び出します。
- 対話型セッションでは自動委任を使用します。 探索的な作業では、クロードに摩擦を減らすためのサブエージェントを選択させますが、
descriptionフィールドは、自動化が予期せずトリガーされないように慎重に設定してください。 - 統合のための構造化された出力を設計します。 サブエージェントにファイルへの書き込みを強制するか、オーケストレーターが読み取れる JSON を生成します。これにより、削減手順と監査が簡素化されます。
テスト、監視、ガバナンス
- 代表的な評価を構築します。 サブエージェントが失敗する場所を追跡し、それらの失敗モードを再現するテストを構築します。Anthropicは、代表的なテストセットと反復的な改善を推奨しています。
- トークンとツールの使用状況を監視します。 各サブエージェントの使用状況を計測し、コストの暴走やレート制限の状態を検出するためのアラートを追加します。
サブエージェントを使用しない場合
サブエージェントは強力ですが、必ずしも適切なツールであるとは限りません。
- 簡単なタスク: 短い一回限りのプロンプトや些細な変換の場合、サブエージェントは不必要な複雑さを追加します。
- 厳しいレイテンシ制約: オーケストレーションのラウンドトリップによってオーバーヘッドが追加されます。単一ターンで非常に低レイテンシの応答が必要な場合は、モノリシック アプローチの方が簡単な場合があります。
- インフラがほとんどない小規模チーム: シークレット、可観測性、サンドボックスのためのツールがなければ、サブエージェントは運用リスクを高める可能性があります。コミュニティの記事では、小規模な構成から始め、モジュール性が必要になった時点でサブエージェントを追加することが推奨されています。
Claude code cliを使用するのが最も推奨される場所
CometAPI が強力な Claude Code cli を完全にサポートするようになったことをお知らせします。 Claude Code で Comet API モデルを使用するには、Claude Code をインストールし、取得した Comet API キーとベース アドレスで認証するだけです。
CometAPI を通じて claude コードを使用するのはなぜですか?
主要な人工知能機能: 開発者向けに特別に構築されたモデルを使用して、コードを簡単に生成、デバッグ、最適化できます。
- 柔軟なモデル選択: 当社の包括的なモデル範囲により、よりシームレスな開発が可能になります。
- シームレスな統合：APIはいつでも利用可能です。Claude Codeを既存のワークフローにわずか数分で直接統合できます。
- **CometAPI経由でClaude Codeを使用すると、コストをさらに節約できます。**CometAPIが提供するClaude APIは公式価格より20%オフで、公式による最新モデルにアップデートされています。
Claude Code cliを使用する準備はできましたか？ APIガイド 詳細な手順については、
AIに関するヒント、ガイド、ニュースをもっと知りたい方は、フォローしてください。 VK, X および Discord!
も参照してください CometAPI 経由で Claude コードをインストールして実行する方法
結論 — なぜサブエージェントが今重要なのか
サブエージェントは、エージェント型ワークフローの実現可能性をチームにとって現実的なものにします。役割、権限、コンテキスト、コスト、並列化について、明示的に、かつファーストクラスオブジェクトとして推論できるようになります。サブエージェントを適切に使用すれば、開発速度の向上、複数ステップのタスクの品質向上、そしてより予測可能なガバナンスを実現できます。その反面、これらのサブエージェントは本番環境のソフトウェアと同様に設計、テスト、監視する必要がありますが、その投資によって迅速なエンジニアリングが信頼性の高いエンジニアリングへと変わります。
