ガイド更新日
Claude Codeのサブエージェントに調査を分ける
この記事で分かること
Claude Code 集中講座の第12回。関数の呼び出し元を調べる例から、サブエージェントへの頼み方を考えます。渡す情報、返してほしい結果、分ける作業の選び方を整理します。

目次 読みたいところから
関数の呼び出し元を探すために、いくつものファイルを読んでもらう。調査のあとに使いたいのは、呼び出し元の一覧と、その根拠です。途中で読んだ内容が会話に積み重なると、進めていた作業の条件を追いにくくなります。
サブエージェントは、別の会話の文脈で調査などを進める作業者です。調べる範囲と返してほしい結果を決めて、作業を分けます。
別の文脈で動く作業者
サブエージェントは、独立した文脈で動く作業者です。本流とは別の文脈を持つので、そこで何をどれだけ読んでも、本流の文脈は増えません。
終わると、結果だけが本流へ返ります。
主な組み込みは3つ
自分で定義しなくても、最初から使えるものがあります。
| 種類 | 何をするか | 使える道具 |
|---|---|---|
| Explore | コードベースの検索と把握 | 読み取りだけ |
| Plan | プランモード中の調査 | 読み取りだけ |
| general-purpose | 複数の手順にまたがる作業 | 全部 |
上の2つには、書く道具がありません。調べるだけの作業者には、書く道具を渡さない。第5回で見た「範囲を先に狭める」という考え方が、ここにも現れています。
何が渡り、何が渡らないか
サブエージェントを使うときに知っておくべきなのは、渡らないもののほうです。
渡るものは、前書きのあとの本文から作られるシステムプロンプト、Claude からの依頼、CLAUDE.md の階層と Git の状態(どちらも Explore と Plan を除く)、前もって読み込むよう指定したスキルです。
渡らないものは、会話の履歴、本流の自動メモリ、これまでに呼ばれたスキル、そして本流の文脈の大きさです。
会話の履歴が渡らないことが、効き目の源であり、同時に制約でもあります。「さっき話したあの件」は通じません。依頼の文に必要なことを全部書く必要があります。第7回で整理した3つ、文脈と制約と完了の条件が、ここではより効きます。
自分で定義する
.claude/agents/ にマークダウンのファイルを置くと、自分のサブエージェントになります。
---
name: code-reviewer
description: 変更をレビューする。差分の確認を頼まれたときに使う。
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
---
あなたはこのリポジトリのレビュー担当です。
振る舞いの変化と、足りていないテストに重点を置いて指摘してください。
必須なのは name と description の2つです。名前は一意の識別子で、: は使えません。説明文は、いつ任せるべきかを書く場所で、第10回のスキルと同じくここが呼ばれるかどうかを決めます。
任意の指定でよく使うものを挙げます。
| 項目 | 何を決めるか |
|---|---|
tools | 使わせるツールの一覧 |
model | sonnet、opus、haiku、fable など |
permissionMode | そのサブエージェントの権限モード |
effort | 考える深さ |
isolation | worktree にすると独立した作業ツリーで動く |
background | true で常に背後で動かす(既定でも背後で始まる) |
memory | 自分専用の自動メモリを持たせる |
置き場所は .claude/agents/ がプロジェクト用、~/.claude/agents/ が個人用です。
呼び方は3通り
自動。作業の内容と description が合えば、Claude が自分で使います。
名指し。@ を打って候補から選ぶか、@agent-code-reviewer のように打つと、そのサブエージェントを指定できます。
セッション全体。--agent code-reviewer を付けて起動するか、設定に書きます。
巻き戻しが効かないことを忘れない
第8回で挙げた制約を、ここでもう一度出します。
公式ドキュメントによれば、通常のサブエージェントの編集は、セッションのチェックポイントに入りません。/rewind を選んでも戻りません。Git で戻すことになります。
例外は、前面で走るフォークのスキルです。第10回で触れた context: fork を background: false で走らせた場合、あなたの回の中で作業ツリーを編集するので、巻き戻しの対象になります。
つまり、書かせるサブエージェントを使うときは、その前にコミットしておくのが安全です。これは面倒に見えますが、逆に言えば、コミットの粒度を依頼の単位に揃えておけば自然に満たされます。
分けてよい作業、分けてはいけない作業
分けてよいのは、結論が短くまとまる作業です。調査、検索、レビュー、特定の条件に合うファイルの列挙。どれも、途中で読んだものは要らず、結果だけが要ります。
分けてはいけないのは、本流の判断とかみ合っている作業です。「この設計でよいか一緒に考える」をサブエージェントに投げると、会話の履歴が渡らないので、それまでの検討が全部抜け落ちます。同じ議論をもう一度することになります。
判断の目安は、その作業を人に頼むとして、背景の説明にどれくらいかかるかです。1段落で足りるなら分けられます。30分の説明が要るなら、分けないほうが速く終わります。
会話全体を引き継がせたいとき
背景の説明が長い場合の逃げ道が1つあります。フォークです。
フォークのサブエージェントは、本流の会話全体を引き継ぎます。システムプロンプト、ツール、モデル、そしてメッセージの履歴です。/subtask から始められます。
使いどころは、「いまの流れのまま、別のやり方も試してみたい」という場面です。第8回の /branch が会話そのものを分岐させるのに対し、フォークは作業だけを分けて結果を本流へ返します。
並べたときに何が起きるか
サブエージェントを複数動かすと、同時に複数の作業が進みます。速くなるように見えますが、そうとは限りません。
読む側が1人だからです。3つのサブエージェントが同時に結果を返しても、それを読んで判断するのはあなたです。出てくる速さが上がっても、読む速さは変わりません。
第14回で並行作業をまとめて扱いますが、結論を先に書いておくと、並べて効くのは「待ち時間が長く、結果が短い」作業だけです。調査は向きます。実装は向きません。
調査依頼の下書き
関数の呼び出し元を調べる依頼を想定し、対象の関数、探す範囲、返してほしい一覧と根拠を書きます。本文の説明と比べ、作業者に渡らない前提が残っていないか読み直してください。
調査結果だけ受け取って元の作業を続けられるかが、分け方を考える目安です。
次の回
編集後の整形のように、決まったタイミングで実行したい手順には、コマンドを動かす設定を使います。「Claude Codeのフックで、整形忘れを減らす」へ進めます。
参照した公式情報
- Anthropic「Subagents」「Checkpointing」「Skills」(code.claude.com/docs、2026年11月時点)
- Anthropic「Commands」(code.claude.com/docs、2026年11月時点)
よくある質問
- サブエージェントは何のためにありますか
- 長い調査や大量の検索の結果で、本流の会話が埋まるのを防ぐためです。別の文脈で作業させ、結論だけを本流へ返します。第8回で扱ったとおり、会話が長くなるほど返答の質は落ちるので、埋めなくてよいものは外へ出すのが効きます。
- サブエージェントの編集は巻き戻せますか
- 多くの場合は戻せません。公式ドキュメントによれば、通常のサブエージェントの編集はセッションのチェックポイントに入らないため、`/rewind` では戻りません。Git で戻すことになります。前面で走るフォークのスキルだけが例外です。
- 自分で定義するには何が要りますか
- `.claude/agents/` にマークダウンのファイルを1つ置きます。前書きに `name` と `description` が必須で、使えるツール、モデル、権限モードなどを任意で指定できます。本文がそのサブエージェントのシステムプロンプトになります。
