はじめに
コードを読み込んだり、大量のログを調べたり——そういう作業を本体の会話でやると、あとで参照しない情報でコンテキストが埋まっていきます。Subagents（サブエージェント）は、そうした作業を別の会話として切り出す仕組みです。
この記事で分かること
- Subagentsとは何か、なぜ本体の会話と分けて動かすのか
- 基本構造とファイルの置き場所
- フロントマターの設定項目（必須・オプション）
- 発火タイミング（自動呼び出し・明示的な呼び出し3パターン）
- 応用編：カスタムコマンド（Skills）との連携パターン
① Subagentsとは何か
Subagentsは、特定の作業を任せる専門のAIアシスタントです。
検索結果やログのような、大量だが読み返さない情報を扱うタスクを本体の会話に持ち込むと、コンテキストを圧迫します。Subagentsに任せれば、その作業は別のウィンドウで完結し、本体には要約だけが返ります。
Claude CodeにはExplore（読み取り専用の高速探索）・Plan（計画立案時の調査）・general-purpose（調査＋実装の両方）という組み込みSubagentsが最初から用意されています。
② 基本構造と置き場所
Subagentは、YAMLフロントマターとMarkdown本文からなる1つのファイルです。
---
name: code-reviewer
description: コードの品質とベストプラクティスをレビューする
tools: Read, Glob, Grep
model: sonnet
---
あなたはコードレビュアーです。呼び出されたら、コードを解析し、
品質・セキュリティ・ベストプラクティスについて具体的で実行可能なフィードバックを提示してください。
フロントマターが設定、その下のMarkdown本文がSubagent専用の指示（システムプロンプト）になります。このYAMLを.claude/agents/code-reviewer.mdとして保存すれば、そのまま使えます。
| 置き場所 | 範囲 | 優先度 |
|---|---|---|
.claude/agents/ |
このプロジェクトだけ | 上位 |
~/.claude/agents/ |
自分の全プロジェクト | 下位 |
同じ名前のSubagentが両方にある場合、.claude/agents/（プロジェクト）が優先されます。実際には、組織の管理設定・起動時にJSONでSubagentを定義する--agents（複数形）フラグ・プラグイン経由も含めた全5段階の優先順位があり、この2つはその中の3位・4位にあたります。
③ フロントマターの設定項目
必須はname・descriptionの2つだけです。
name・descriptionを含めて全16フィールドがあり、残り14個は任意です（2026年7月時点、代表的なものを紹介）。いずれもSubagentを呼び出す側のコマンドの引数ではなく、Subagent定義ファイル自身のYAMLフロントマターに書くフィールドです。
| フィールド | 内容 |
|---|---|
tools |
使えるツールの許可リスト（省略時は全ツールを継承） |
model |
使うモデル（sonnet／opus／haiku等。省略時は本体と同じ） |
permissionMode |
権限確認の挙動（default／acceptEdits等） |
skills |
起動時にあらかじめ読み込ませておくSkills |
④ 発火タイミング
Subagentsは大きく「自動」と「明示的」の2通りで呼び出されます。
| 呼び出し方 | 書き方 | 確実さ |
|---|---|---|
| 自動呼び出し | 何も書かず依頼するだけ | Claudeの判断次第 |
| 自然言語で名指し | 「code-reviewerで見て」 | Claudeが委任するかは判断による |
@メンション |
@code-reviewer ... |
そのSubagentの実行を保証 |
| セッション全体 | claude --agent code-reviewer |
会話全体がそのSubagentになる |
なお、Subagentsを起動するツール自体の名前は現在Agentです。バージョン2.1.63でTaskから改名されましたが、Task(...)という書き方も後方互換のエイリアスとして今も動きます。
⑤ 応用編：カスタムコマンド（Skills）との連携
SkillsとSubagentsは、2つの方向で組み合わせられます。
| 組み合わせ方 | システムプロンプトの出どころ | 何をするか |
|---|---|---|
Skillにcontext: forkを指定 |
指定したSubagentの型から | SKILL.mdの内容がそのままSubagentへの指示になる |
Subagentにskillsフィールドを指定 |
Subagent自身のMarkdown本文 | 指定したSkillsの内容を起動時に読み込んでおく |
前者の例です。
---
name: deep-research
description: トピックを徹底的に調査する
context: fork
agent: Explore
---
$ARGUMENTSについて徹底的に調査してください:
1. GlobとGrepで関連ファイルを見つける
2. コードを読み込んで分析する
3. 具体的なファイル参照つきで発見事項をまとめる
/deep-research ◯◯と呼び出すと、Exploreという読み取り専用のSubagentが独立したウィンドウで調査し、結果だけが本体に返ってきます。
まとめ：まず1つ、既存のSubagentを試す
Subagentsは、大量の情報を扱う作業を本体の会話から切り離し、要約だけを受け取るための仕組みです。まずは組み込みのExploreを、明示的に呼び出してみてください。
@Explore このプロジェクトの認証まわりの実装を調べて