Claude Code実践ガイド
Claude Codeのサブエージェント｜調査を分担させる
長時間の作業をしていると、必ずこうなります。途中で大きな調査が必要になり、その結果で会話が埋まり、本題を見失う。サブエージェントは、この問題への正攻法です。役割の違うAIを「部下」として定義しておき、調査やレビューを丸ごと任せて、結果だけを本体の会話に返してもらいます。上級者向けの機能に見えますが、解決する問題は誰もが毎日踏んでいるものです。
このサイトは Anthropic や Claude の公式サイトではありません。Claudeの基本的な使い方、ChatGPTとの違い、文章作成・長文整理・仕事での活用を初心者向けに整理する非公式ガイドです。機能・料金・提供状況は変更される可能性があるため、重要な判断ではAnthropic公式情報も確認してください。
解決する問題：会話が長くなると賢さが落ちる
Claude Codeは会話の内容を踏まえて動きます。これは利点ですが、副作用があります。
- 調査で読んだ大量のファイル内容が、その後もずっと会話に残る
- 会話が膨らむほど、毎回の処理量が増えて利用枠の消費が跳ね上がる
- 本題と関係ない情報が混ざり、指示の通りが悪くなる
対処として /clear や /compact がありますが、これらは調査が終わった後の後始末です。サブエージェントはそもそも本体の会話を汚さないという、より上流の解決になります。
仕組み：別の会話に投げて、結果だけ受け取る
サブエージェントに作業を投げると、そのエージェントは独立した会話の中で調査や作業を行います。何十ファイル読もうが、その過程は本体の会話には入りません。返ってくるのはまとめられた結果だけです。
人に例えると分かりやすいです。部下に「この件、調べて要点だけ報告して」と頼むのと同じで、調査の過程を全部見せられるわけではありません。報告の粒度をこちらで決められるのが要点です。
定義の考え方
サブエージェントはプロジェクトの .claude/agents/ に定義を置きます。書式を覚える必要はなく、「調査専用のエージェントを作って」と頼めば作成自体を任せられます。設計で意識すべきは次の3点です。
- 役割を1つに絞る──「調査もレビューも実装も」と欲張ると、どの場面で呼ぶべきか曖昧になります。1エージェント1役割が原則です
- 報告の形式を決めておく──「該当ファイルと行番号、問題点、推奨する対処の3点で返す」のように出力を固定すると、受け取った側が使いやすくなります
- 権限を絞る──調査専用なら書き込みを許可しない、という設計ができます。役割を分けること自体が安全策になります
向いている作業・向かない作業
| 向いている | 向かない |
|---|---|
| 大規模コードベースの調査（「この機能はどこで実装されている？」） | その場の短いやり取りで済む作業 |
| 影響範囲の洗い出し（「これを消したら何が壊れる？」） | 方針を相談しながら決めたい作業 |
| 変更内容のレビュー | 途中で細かく軌道修正したい作業 |
| 複数ファイルにまたがる横断チェック | 1ファイルで完結する修正 |
共通するのは「過程は要らない、結論だけほしい」作業かどうかです。逆に、過程を見ながら方向を変えたい作業は本体の会話でやるべきで、サブエージェントに投げると細かい修正が効きません。
実際の使い方の例
大規模なコードベースを扱うとき、次のような分担が定番になります。
- 本体の会話で「この機能を直したい」と伝える
- 関連箇所の特定を調査エージェントに投げる。数十ファイルを読んで、該当箇所の一覧だけが返る
- 本体の会話は、その一覧を受け取って実装に進む。読んだファイルの中身は本体に入っていない
- 実装後、レビューエージェントに変更内容を渡して問題点を指摘させる
この形にすると、本体の会話は「方針の決定と実装」だけに集中し、長時間の作業でも見通しが保たれます。大規模プロジェクトでの進め方は既存コードを改善するページでも扱っています。
使うときの注意
- 報告を鵜呑みにしない──過程が見えないぶん、間違いに気づきにくくなります。結論が方針を左右する調査は、根拠も一緒に報告させてください
- 利用枠は消費する──別の会話とはいえ処理は行われます。「投げれば無料」ではありません（利用枠の仕組み）
- 最初から作り込まない──「会話が膨らんで困った」経験をしてから作る方が、必要な役割が具体的に決まります。先に凝った定義を作っても使われません
AIガイド群
FAQ
Skillsとサブエージェントはどう違いますか？
Skillsは「作業のやり方」を渡す仕組み、サブエージェントは「作業そのものを別の会話に任せる」仕組みです。手順書と担当者の違いと考えると整理しやすいです。
いくつまで定義できますか？
複数定義できますが、増やしすぎると呼び分けが曖昧になります。まずは調査用の1つから始めて、必要になったら足すのが実用的です。
結果が期待と違うときは？
報告形式の指定が曖昧なことが多いです。定義に「何を、どの粒度で返すか」を具体的に書き足してください。人への指示と同じで、出力の型を決めるほど安定します。
チーム全員で共有できますか？
定義をリポジトリに置けば共有されます。プロジェクト固有の調査手順を持つ場合、共有する価値は大きいです。