Claude Code Subagent の概念の紹介

はじめに

Claude Code を使用して複雑なタスクを処理する場合、このようなジレンマに遭遇したことがあるかもしれません。主な会話のコンテキストはますます長くなり、AI は以前の重要な情報を「忘れ」始め、応答の品質は徐々に低下します。

Subagent はこの問題を解決するために生まれました。

Skills がクロードの「作業マニュアル」である場合、Subagent はあなたが雇用する「フルタイム従業員」です。彼らは独自の独立したワークステーション (コンテキスト) を持ち、特定の種類の作業に集中し、完了後に結果をあなたに報告します。

サブエージェントについて

あなたが会社の CEO であると想像してください。会社が小さいときは、すべてを自分で処理します。しかし、ビジネスが拡大するにつれて、財務担当の会計士、採用担当の人事担当者、開発担当のエンジニアなど、フルタイムの従業員を雇用し始めます。各従業員は自分のステーションで勤務し、タスクの完了後にあなたに報告します。

クロード コードではサブエージェントがまさにこの役割を果たします。

技術的な観点から見ると、サブエージェントは次の特徴を持つ特殊な AI アシスタントです。

なぜ独立したコンテキストが必要なのでしょうか?

これは Subagent の核となる設計コンセプトであり、深く理解する必要があります。

通常の会話では、すべての情報が同じコンテキストに積み重ねられます。クロードにコード ベースを検索させ、ファイルを分析して変更を加えると、この中間処理すべてがコンテキスト スペースを占有します。会話が進み、文脈が混み合うにつれて、クロードは以前の重要な情報を「忘れ」始める可能性があります。

サブエージェントの変更は次のとおりです。

主对话（专注于高层目标）
│
├── 用户：帮我优化这个模块的性能
│
├── Claude：我来分析一下...
│   │
│   └── [调用 Explore Subagent]
│       │ 在独立上下文中：
│       ├── 搜索相关文件
│       ├── 分析代码结构
│       ├── 识别性能瓶颈
│       └── 返回：发现 3 个优化点...
│
└── Claude：根据分析，我发现 3 个优化点...

サブエージェントの分析プロセスは、メインの会話を汚染しません。メインの対話では、明確さと焦点を維持しながら、洗練された結果のみが得られました。

組み込みサブエージェントのタイプ

Claude Code は、最も一般的な使用シナリオをカバーする 3 つの強力な組み込みサブエージェントを提供します。

サブエージェントを探索する

ターゲティング: コードベースの高速な読み取り専用探索。

特徴:

• Haiku モデルを使用する (高速、低遅延)
• 厳密に読み取り専用 - ファイルの作成、変更、削除はできません
• 利用可能なツール: Glob、Grep、Read、Bash (読み取り専用操作)

使用する場合: 「この機能はどこに実装されていますか?」などの探索的な質問をするとき。 「エラーはどのように処理されますか?」クロードは自動的に Explore Subagent を呼び出します。

詳細レベル:

サブエージェントを計画する

位置付け: コードベースを調査し、実装計画を準備します。

特徴:

• Sonnet モデルを使用します (より強力な推論機能)
• 探索ツールのみ: Read、Glob、Grep、Bash
• 計画モードで自動的に呼び出されます

使用する場合: 計画モードに入り、計画を提案する前にクロードに調査を行う必要がある場合、Plan Subagent は自動的に情報を収集し、調査結果に基づいて計画を提案します。

汎用サブエージェント

ポジショニング: 複雑な複数ステップのタスクを処理します。

特徴:

• ソネットモデルを使用
• すべてのツールへのアクセス (読み取りと書き込みを含む)
• 探索と変更が必要な複雑なタスクに適しています

使用する場合: タスクに複数のステップが含まれる場合、変更する前に検索が必要な場合、または最初の検索が失敗する可能性があり、複数の戦略を試行する必要がある場合。

私の理解と実践

3 つの公式組み込みサブエージェントを注意深く観察すると、それらはすべて調査および計画タスクであるという共通点が 1 つあることがわかります。 Exploreはコードベースの探索を担当し、Planは計画の作成を担当し、汎用も主に調査と分析に使用されます。これらはいずれも、コードを書くために特別に設計されたものではありません。

これは、Subagent についての私の理解を裏付けています。 Subagent の中心的な価値は、「クリーンなコンテキスト」ではなく、メイン エージェントが物事の実行に集中できるようにすることです。

分業モード

私の利用方法は非常にシンプルで、サブエージェントが調査・計画・検討といった「情報収集」の作業を担当し、メインエージェントが実際の実行を担当します。

Subagent（调研员）          主 Agent（执行者）
     │                           │
     ├── 探索代码库结构            │
     ├── 分析依赖关系              │
     ├── 制定实施计划              │
     └── 返回精炼的上下文 ──────────→ 基于上下文执行任务
                                  │
                                  ├── 编写代码
                                  ├── 修改文件
                                  └── 运行测试

Subagent にコードを書かせてみてはいかがでしょうか?

メイン エージェントに複数のサブエージェントをスケジュールしてコードを作成させることを好む人もいます。これは信頼できないと思います。理由は簡単です: コンテキストが大幅に欠落しています。

サブエージェントのコンテキストは独立しています。主要な会話で何が議論され、どのような決定が下され、どのような制約が課されたのかはわかりません。コードの作成を依頼することは、新入社員に背景情報をまったく持たずにタスクを完了するよう依頼するようなものです。作成されたコードは期待と一致しない可能性があります。

それどころか、Subagent を「研究者」として位置づける方がはるかに合理的です。

• 研究タスク自体には多くのコンテキストは必要ありません
• コードの代わりに情報が返され、メイン エージェントが完全なコンテキストに基づいて使用できます。
• 調査結果に偏りがあった場合でも、主体エージェントが修正できる

私の毎日の使い方

1. 新しいタスクを開始する前に: Explore エージェントが関連するコードの構造をすぐに理解できるようにします。
2. 複雑なタスクの計画: 計画エージェントに要件を分析させ、実装手順を策定させます
3. コード レビュー: レビュー エージェントにコードの品質とセキュリティの問題をチェックさせます
4. 実際のコーディング: メイン エージェントは、収集されたコンテキストに基づいてコードを作成します。

私が現在使用しているエージェントのリストは次のとおりです。

この利点は、メイン エージェントのコンテキスト ウィンドウがクリーンなままであり、「サブエージェントの検索プロセス中に生成された中間結果の束」ではなく、「知る必要がある情報」だけが表示されることです。

他の関数との比較

Subagent vs Skills

これは最も一般的な混乱です。主な違い: スキルはクロードに知識を注入します。サブエージェントは独立したワーカーを作成します。

比喩的に言えば、スキルはトレーニング資料のようなもので、クロードが何かを行う方法を学ぶことができます。サブエージェントはフルタイムの従業員のようなもので、自分のワークステーションで独立してタスクを完了し、結果を報告します。

この 2 つは組み合わせることができます。コード レビュー Subagent はコード仕様をロードして、「専門家 + 専門知識」の複合効果を達成することができます。

サブエージェントとスラッシュ コマンド

スラッシュ コマンドはショートカット キーであり、/review と入力すると、事前定義された操作がトリガーされます。サブエージェントは、複雑な複数ステップのタスクを自律的に実行できる独立したワーカーです。

Subagent vs Plugin

プラグインは「コンテナ」の概念であり、サブエージェントを含めることができます。

Plugin（容器）
├── Commands（快捷命令）
├── Skills（知识包）
├── Agents（子代理）← 这就是 Subagent
└── Hooks（事件钩子）

プラグインの agents/ ディレクトリでサブエージェントを定義し、プラグインとともに配布できます。

エージェントのデザイン パターン

Anthropic は、6 つの主要な Agentic 設計パターンを公式ドキュメントにまとめています。これらのパターンを理解すると、サブエージェント システムをより適切に設計するのに役立ちます。

これらのモードは組み合わせて使用できます。たとえば、コード品質システムでは次の両方が使用される場合があります。

• 並列化: セキュリティ スキャンとパフォーマンス分析を同時に実行します。
• オーケストレーター兼ワーカー: マスター クロードは複数の専門化されたサブエージェントを調整します
• Evaluator-Optimizer: 生成直後にコードをレビューします

主な利点

コンテキスト保護

Subagent の最大の価値は、メインの会話のコンテキストを保護することにあります。コード検索やファイル分析などの中間処理がメインダイアログに蓄積されないため、メインダイアログは常に高レベルの目標に焦点を当てることができます。

専門化機能

詳細な手順と適切なツールを使用して構成された、特定のドメインに特化したサブエージェントを作成できます。特化したサブエージェントは、汎用のクロードよりも特定のタスクで優れたパフォーマンスを発揮します。

柔軟な権限制御

各サブエージェントは異なるツール アクセス権を持つことができます。たとえば、探索クラス Subagent には読み取り専用権限のみが与えられ、変更クラス Subagent には書き込み権限のみが与えられます。このきめ細かい制御により、セキュリティが向上します。

再利用性

Subagent を作成すると、プロジェクト間で再利用したり、プラグインを介してチームと共有したりできます。

サブエージェントを使用する場合

サブエージェントの使用に適したシナリオ:

• タスクを実行するには独立したコンテキストが必要です
• タスクは複雑な複数ステップのワークフローです
• メインの会話とは異なるツールセットが必要です
• タスクの実行には時間がかかる場合があります

サブエージェントの使用に適さないシナリオ:

• シンプルなワンタイムクエリ
• メインダイアログとの緊密な対話が必要です
• ミッションはすぐに完了できます

一般的なアプリケーション シナリオ

コードレビュー

代码审查 Subagent
├── 专门的审查提示
├── 只读工具（Read, Grep, Glob）
└── 输出：结构化的审查报告

コードを完成させると、主要な開発作業を妨げることなく、コード レビュー サブエージェントに独立したコンテキストでコードをレビューさせることができます。

デバッグ分析

调试 Subagent
├── 错误分析专家提示
├── 读写工具
└── 输出：根因分析 + 修复方案

エラーが発生した場合、デバッグ サブエージェントはエラーの原因を深く分析し、さまざまな仮説を試し、最終的に修復の提案を提供します。

コードベースの探索

探索 Subagent
├── Haiku 模型（快速）
├── 只读工具
└── 输出：代码结构概览

新しいプロジェクトに初めて取り組む場合、Explore Subagent を使用すると、大量の検索結果でメインの会話を混乱させることなく、コード ベースをすばやくマッピングできます。

学習リソース

公式リソース

コミュニティリソース

概要

Claude Code Subagent は本質的に、特化されたコンテキストに依存しない AI アシスタントです。コンテキストを分離することで複雑なタスクにおける情報過多の問題を解決し、主要な会話を常に明瞭かつ集中的に保ちます。

3 つのキーワードを覚えておいてください。

概念を理解したら、次の記事「Claude Code Subagent Practical Guide」で、カスタム Subagent の作成、ツール権限の構成、および実際のプロジェクトでのベスト プラクティスを実践してください。

Subagentがロードできるスキルについて知りたい場合は、「【クロードスキルとは】(/ja/docs/notes/claude-skills/concept)」をご覧ください。 Subagentをパッケージ化して配布したい場合は、「【クロードコードプラグインとは】(/ja/docs/notes/claude-plugin/concept)」をご覧ください。