本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

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使わせるツールの一覧
modelsonnet、opus、haiku、fable など
permissionModeそのサブエージェントの権限モード
effort考える深さ
isolationworktree にすると独立した作業ツリーで動く
backgroundtrue で常に背後で動かす(既定でも背後で始まる)
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月時点)

READ NEXT

次はこれを読む

Claude Code 集中講座の次の回へ

Claude Codeのフックで、整形忘れを減らす

Claude Code 集中講座の第13回。編集後の整形を例に、決まったタイミングでコマンドを実行するフックを学びます。設定の読み方と、スキルや規約との使い分けも整理します。

続きを読む →
設定ファイルを開いた画面の前で、こちらを向いて座っている女性の開発者

よくある質問

サブエージェントは何のためにありますか
長い調査や大量の検索の結果で、本流の会話が埋まるのを防ぐためです。別の文脈で作業させ、結論だけを本流へ返します。第8回で扱ったとおり、会話が長くなるほど返答の質は落ちるので、埋めなくてよいものは外へ出すのが効きます。
サブエージェントの編集は巻き戻せますか
多くの場合は戻せません。公式ドキュメントによれば、通常のサブエージェントの編集はセッションのチェックポイントに入らないため、`/rewind` では戻りません。Git で戻すことになります。前面で走るフォークのスキルだけが例外です。
自分で定義するには何が要りますか
`.claude/agents/` にマークダウンのファイルを1つ置きます。前書きに `name` と `description` が必須で、使えるツール、モデル、権限モードなどを任意で指定できます。本文がそのサブエージェントのシステムプロンプトになります。