Claude Subagent 完全ガイド

はじめに

Claude Code で複雑なタスクを処理する際、こんな困りごとに遭遇したことはありませんか？メインの会話コンテキストがどんどん長くなり、AIが以前の重要な情報を「忘れ」始め、レスポンスの品質が徐々に低下していく——。

Subagent（サブエージェント）は、まさにこの問題を解決するために生まれました。

Skills が Claude への「ワークマニュアル」だとすれば、Subagent はあなたが雇った「専任スタッフ」です——独自のデスク（コンテキスト）を持ち、特定の種類の仕事に専念し、完了したらあなたに結果を報告します。

Subagent を理解する

あなたが会社の CEO だと想像してください。会社が小さいうちは、すべての業務を自分で処理します。しかしビジネスが拡大するにつれ、専任スタッフを雇い始めます：経理が財務を担当し、人事が採用を担当し、エンジニアが開発を担当する。各スタッフは自分のデスクで仕事をし、タスクを処理したらあなたに報告します。

Subagent は Claude Code の中で、まさにこのような役割を果たしています。

技術的に言えば、Subagent は専門化されたAIアシスタントであり、以下の特徴を持っています：

なぜ独立コンテキストが必要なのか

これは Subagent の最も核心的な設計思想であり、深く理解する価値があります。

通常の会話では、すべての情報が同じコンテキストに蓄積されます。Claude にコードベースを検索させ、ファイルを分析させ、そして修正を行わせると、これらの中間プロセスすべてがコンテキストスペースを占有します。会話が深まるにつれてコンテキストはますます混雑し、Claude は初期の重要な情報を「忘れ」始める可能性があります。

Subagent はこの状況を変えます：

メイン会話（ハイレベルな目標に集中）
│
├── ユーザー：このモジュールのパフォーマンスを最適化して
│
├── Claude：分析してみます...
│   │
│   └── [Explore Subagent を呼び出し]
│       │ 独立コンテキストで：
│       ├── 関連ファイルを検索
│       ├── コード構造を分析
│       ├── パフォーマンスのボトルネックを特定
│       └── 結果を返す：3つの最適化ポイントを発見...
│
└── Claude：分析の結果、3つの最適化ポイントが見つかりました...

Subagent の分析プロセスはメイン会話を汚染しません。メイン会話は精製された結果のみを受け取り、明確さと集中力を維持できます。

Anthropic がベストプラクティスで推奨しているように：

内蔵 Subagent タイプ

Claude Code には、すぐに使える3つの内蔵 Subagent が付属しています：

これらの内蔵エージェントは、タスクの種類に応じて自動的に呼び出されます。

私の理解と実践

公式の3つの内蔵 Subagent をよく観察すると、共通点に気づくでしょう：すべてがリサーチとプランニング系のタスクです。Explore はコードベースの探索を担当し、Plan は計画の策定を担当し、General-purpose でさえ主にリサーチと分析に使用されます。コードを書くための専用のものはありません。

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

分業モデル

私の使い方はシンプルです：Subagent がリサーチ、プランニング、レビューなどの「情報収集」の仕事を担当し、メインエージェントが実際の実行を担当します。

Subagent（リサーチャー）         メインエージェント（実行者）
     │                           │
     ├── コードベース構造の探索      │
     ├── 依存関係の分析              │
     ├── 実装計画の策定              │
     └── 精製されたコンテキストを返す ──→ コンテキストに基づいてタスクを実行
                                  │
                                  ├── コードの記述
                                  ├── ファイルの修正
                                  └── テストの実行

なぜ Subagent にコードを書かせないのか

複数の subagent にコードを書かせるのが好きな人もいますが、私はあまり信頼できないと思っています。理由は単純です：コンテキストが著しく不足しているからです。

Subagent のコンテキストは独立しており、メイン会話で何が議論されたか、どんな決定がなされたか、どんな制約があるかを知りません。コードを書かせるということは、背景情報がまったくない状態で新入社員に独立してタスクを完了させるようなものです——出力されるコードはおそらくあなたの期待に合わないでしょう。

逆に、Subagent を「リサーチャー」と位置づけるのは合理的です：

• リサーチタスク自体はそれほど多くのコンテキストを必要としない
• 返すのはコードではなく情報であり、メインエージェントが完全なコンテキストに基づいてその情報を活用できる
• リサーチ結果に偏りがあっても、メインエージェントが修正できる

私の日常的な使い方

1. 新しいタスクを始める前に：Explore エージェントに関連コードの構造を素早く把握させる
2. 複雑なタスクの計画：Plan エージェントに要件を分析させ、実装ステップを策定させる
3. コードレビュー：Review エージェントにコード品質とセキュリティ問題をチェックさせる
4. 実際のコーディング：メインエージェントが収集したコンテキストに基づいてコードを書く

これが私が現在使用しているエージェントリストです：

このようにすることで、メインエージェントのコンテキストウィンドウがクリーンに保たれ、「自分が知る必要のある情報」だけが含まれ、「Subagent の検索プロセスで生成された大量の中間結果」は含まれません。

Subagent の使い方

利用可能なエージェントを確認する

/agents コマンドを使用して、現在の環境で利用可能なすべての Subagent を確認できます：

/agents

これにより、内蔵エージェントと設定済みのカスタムエージェントが一覧表示されます。

自動委任

ほとんどの場合、どの Subagent を使用するか手動で指定する必要はありません。Claude はタスクの種類に応じて適切なエージェントを自動的に選択します：

• コード探索タスク → Explore Subagent
• 計画の策定が必要 → Plan Subagent
• 複雑なマルチステップタスク → General-purpose Subagent

明示的な呼び出し

特定のエージェントを明確に使用したい場合は、プロンプトで直接指定できます：

Explore エージェントを使って authentication を含むすべてのファイルを検索して

または：

サブエージェントを起動してこのモジュールの依存関係を分析して

Subagent はどこにあるか

内蔵エージェント

Claude Code に付属する3つの内蔵エージェント（Explore、Plan、General-purpose）は、設定不要ですぐに使えます。

コミュニティリソース

wshobson/agents - 高品質な Subagent テンプレートライブラリ。コードレビュー、テスト実行などの一般的なエージェントを含みます：

移動

Claude Plugin Hub - プラグインマーケットプレイス。さまざまなエージェントやプラグインを見つけることができます：

移動

カスタム Subagent の作成

内蔵エージェントやコミュニティリソースの使用に加えて、独自の Subagent を作成することもできます。

設定ファイルの場所

設定フォーマット

各 Subagent は YAML frontmatter とシステムプロンプトを含む Markdown ファイルです：

---
name: code-reviewer
description: Reviews code for security and style issues. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer focusing on:
- Security vulnerability detection
- Code style and best practices
- Performance optimization

## Review Output
1. **Critical Issues**: Security, correctness
2. **Warnings**: Style, performance
3. **Suggestions**: Refactoring opportunities

フィールド説明

ツール権限

エージェントの役割に応じて最小限必要な権限を設定します：

高度な機能

Subagent は独立した個体として、メインエージェントのほとんどの機能にアクセスできます：

MCP ツールアクセス

tools フィールドを省略すると、すべての MCP ツールが自動的に継承されます。明示的に指定する場合のフォーマットは：

tools: Read, Grep, mcp__github__create_issue, mcp__linear__list_issues

Skills ナレッジ

Subagent に特定の Skill のナレッジを使用させたい場合は、システムプロンプトの本文で説明します：

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Follow the guidelines in the code-standards skill.

When reviewing:
- Apply project coding standards
- Check for security issues

これにより、Subagent は実行時に関連する Skill のガイダンスを参照します。

権限モード

制限事項

• 他の Subagent を呼び出すことはできない（無限再帰の防止）
• ステップバイステップの計画はサポートされていない

ベストプラクティス

• 単一責任：各エージェントは1つの明確な目標に集中する
• 最小権限：必要なツールのみを付与する
• 明確な説明：description が自動呼び出しの品質を決定する。「いつ使うか」を明確に記述する
• バージョン管理：プロジェクトレベルの設定を Git にコミットし、チーム共有を容易にする

おわりに

Subagent の核心的な価値は、メインエージェントが作業に集中できるようにすることです。Subagent を実行者ではなくリサーチャーと位置づければ、Claude Code の効率が大幅に向上することに気づくでしょう。

Claude Code の基本的な使い方にまだ慣れていない場合は、まず『私の Claude Code ベストプラクティス』を読んで、コアコマンドとワークフローを理解することをお勧めします。

さらに読む

• 《Claude システムアーキテクチャ全解析》— Claude システム全体における Subagent の位置づけ
• 《Claude Skills とは》— Skills と Subagent の違いと相互補完関係