Claude Code のサブエージェント：文脈の分離、オーケストレーターとレビュアー、不要なケース

Claude Code のサブエージェントとは

サブエージェントは、メインのエージェントが個別の課題のために起動する、もう一つのエージェントのインスタンスです。独自の文脈ウィンドウ、独自のシステムプロンプト、許可されたツールの一覧を持ちます。メインのエージェントは課題の説明を渡し、サブエージェントはファイルを読んだりコマンドを実行したりして自律的に作業し、戻ってくるのは最終的なメッセージだけです。

ここで重要なキーワードは分離です。サブエージェントが途中で読んだもの（数十のファイル、長いテスト出力、行き止まりの仮説）はすべて、そのサブエージェントの文脈にとどまり、メインのセッションの文脈には入りません。メインのエージェントが受け取るのは短い結果です。「関数 X にエラーがあり、原因は以下で、影響する箇所は三つある」。

Claude Code のサブエージェントは、マルチエージェント・システムという一般的な考え方の特殊な例です。「考える、作る、確かめる」という一つのループの代わりに、それぞれが役割と責任を持つノードからなるグラフが現れます。

文脈の分離が必要な理由

文脈ウィンドウはエージェントの主要な資源です。そこには CLAUDE.md の指示、対話の履歴、読んだコード、コマンドの出力が同時に入ります。エージェントが原因探しに30分を費やすと、文脈は無関係なファイルと、そのうち一行だけが重要なログで埋まります。

その結果は、長くエージェントと働いたことがある人にはおなじみです。モデルはプロジェクトのルールを保持しにくくなり、詳細を取り違え、履歴が自動で圧縮されると重要なものを失います。サブエージェントは構造的にこれを解決します。面倒な作業は別の文脈で行われ、回答の後に捨てられます。

• 検索と調査。「決済関数を呼び出している箇所をすべて見つけて、その仕組みを説明して」は、サブエージェントに向いた典型的な課題です。
• ノイズの多い検証。テストの実行と失敗の解析をサブエージェントに任せ、失敗の原因の一覧を受け取ります。
• 大きな文書の読解。数百ページの仕様書から必要なのは数個の事実だけなら、サブエージェントに抽出させます。

サブエージェントの設定：.claude/agents フォルダ

自分のサブエージェントは、YAML ヘッダー付きの Markdown ファイルで定義します。プロジェクトのファイルはリポジトリの .claude/agents/ にあり、git を通じてチーム全員が使えます。個人用のものは ~/.claude/agents/ に置けば、すべてのプロジェクトで動きます。Claude Code で /agents コマンドを使えば、対話的に作成と編集もできます。

---
name: code-reviewer
description: コードの変更にエラーやプロジェクトのルール違反がないかを確認する。課題の完了後、コミットの前に使う。
tools: Read, Grep, Glob, Bash
---
あなたはコードレビュアーです。何かを修正する必要はありません。

1. 変更を確認する: git diff。
2. 各変更にロジックのエラー、エラー処理、
   セキュリティ（SQL、出力のエスケープ、秘密情報）の問題がないか確認する。
3. AGENTS.md のルールと照合する。
4. 指摘の一覧を返す: ファイル、行、問題、なぜ重要か。
   指摘がなければ、そのように書く。

各フィールドの意味は次のとおりです。

ファイルの本文はサブエージェントのシステムプロンプトです。サブエージェントはあなたの対話の履歴を見ないので、役割や回答の形式について知る必要があることは、プロンプトかメインのエージェントが渡す課題に書いておかなければなりません。

サブエージェントの呼び出し方

課題が description に合致すれば、メインのエージェントは自分でサブエージェントを選ぶことがあります。ただ、明示的に頼むほうが確実です。「code-reviewer サブエージェントを使って変更を確認して」。説明文に「積極的に使う」のような言葉を入れると、リマインドなしで呼ばれる確率は上がりますが、保証はされません。

調査用のサブエージェント

ほぼどのプロジェクトにも作っておく価値がある二つ目のファイルは、読み取り専用の調査役です。コードについての質問に答えますが、何も変更しません。

---
name: explorer
description: コードベースで、何がどこにあり、どう動くかの質問に答える。多くのファイルを読んで短い答えを得たいときに使う。
tools: Read, Grep, Glob
---
あなたはコードを調査するだけで、何も変更しません。
返すもの: 質問への短い答え、その根拠となるファイルと行の一覧、
確認できなかったこと。

このサブエージェントは、課題の初めに特に役立ちます。メインのエージェントは、すべてを手当たり次第に読んで文脈を消費することなく、必要な場所の地図を手にできます。その後は具体的なファイルを使って作業を進められます。

「オーケストレーターと実行者」の方式

最も一般的なマルチエージェントの方式は、一人のオーケストレーターが計画と全体像を保持し、個々のステップを実行者に割り振るものです。オーケストレーターはコード全体を自分では読まず、課題を定式化し、結果を受け取り、次に何をするかを決めます。

1. オーケストレーターは課題を独立した部分に分け、それぞれに自己完結した指示を書きます。目的、探す場所、完了の基準、回答の形式です。
2. 実行者は、自分の文脈の中で指示を実行します。
3. オーケストレーターは回答を集め、部分同士が噛み合っているかを確かめ、次のステップを実行するか、前のステップに戻るかを決めます。

この方式の弱点は、課題の受け渡しです。サブエージェントは、書かれたことしか知りません。「前に話したバグを直して」という指示は、議論を見ていない相手には空っぽです。良い指示は、初めてリポジトリを開いた新しい同僚に向けた課題のように読めるものです。

実行者が返すべきもの

回答の形式を前もって決めておきましょう。ファイルの一覧、出力、見つかった原因、確認できなかったこと。短く構造化された回答はオーケストレーターの文脈を節約し、「確認できなかったこと」の項目は、根拠のない確信から守ってくれます。実行者も、どのエージェントと同様、成功を報告したがる傾向があるからです。

独立したレビュアー：裁く者と実行する者を分ける理由

同じエージェントがコードを書き、自分で検証すると、裁判官と被告人が同じ頭を共有することになります。エージェントは自分が何をしたかったかを覚えていて、コードの中に書かれたものではなく自分の意図を見てしまいます。さらに、早く終わらせたいという動機もあります。検証は形式的なものになってしまいます。

独立した文脈のレビュアーは、これらの問題を免れます。決定の履歴は知らず、差分とプロジェクトのルールだけを見て、新鮮な目で結果を評価します。これは実際のチームと同じ原則です。書いた本人が自分のプルリクエストを承認することはありません。

• レビュアーには、読み取りとチェックの実行に必要なツールだけを与えてください。ファイルの編集権限は与えないこと。そうすれば、問題を報告する代わりに「黙って直す」ことを始めません。
• 確認の基準を明示してください。何をエラーとみなすか、どのプロジェクトのルールが必須か。
• 指摘への対応は、オーケストレーターか人間が決めてください。レビュアーが見つけ、実行者が直します。

レビュアーは機械的なチェックの代わりにはなりません。テスト、リンター、型チェックは決定的なノードであり、どんなモデルよりも信頼できます。レビュアーは、機械的なチェックには見えないものを捕まえます。誤ったロジック、取り決めからの逸脱、余計な複雑さです。

サブエージェントの並列実行

Claude Code は複数のサブエージェントを同時に起動できます。課題の部分が本当に独立しているときには、作業が速くなります。例えば、三つのモジュールを調べる、変更を三つの観点（セキュリティ、パフォーマンス、テスト）から確認する、いくつかの情報源から情報を集める、といった場合です。

並列実行は読み取りではうまく機能しますが、書き込みでは機能しません。二人の実行者が同じファイルを同時に編集すると、互いの変更を上書きしてしまい、どちらもそれに気づきません。エージェントのグラフの言葉で言えば、マージのルールがない共有状態です。実践的なルールは次のとおりです。

• 並列にするのは調査、分析、レビューです。重なるファイルへの修正は順番に行います。
• 実行者が本当に並列で書き込むなら、担当領域を分けます。各自が自分のファイルだけで作業するか、自分専用のリポジトリのコピー（例えば別の git worktree）で作業します。
• 結果をまとめるのは一つのノード、つまりオーケストレーターです。実行者同士がまとめることはしません。

サブエージェントが不要な場合

マルチエージェントの構成にはコストがかかります。トークンが増え、時間が増え、受け渡しの途中で情報が失われる場所が増えます。Claude Code のサブエージェントは、いつも割に合うわけではありません。

エージェントのグラフを組む前に、簡単な問いに答えてください。全体の目標に責任を持つのは誰か、変更を拒否して取り消せるのは誰か、成功をどの指標で測るのか。答えがなければ、複数のエージェントは一人の混乱を増やすだけです。

サブエージェントでよくある間違い

曖昧な説明

「コードの助手」という説明では、メインのエージェントがいつ呼ぶべきか判断できません。きっかけを書いてください。「api/ フォルダの変更後、コミットの前に」。

文脈のない指示

サブエージェントがパス、完了基準、制約のない課題を受け取ると、作業の半分を、何を求められているかの推測に費やしてしまいます。指示のテンプレートで解決します。目的、入力、制約、回答の形式を書きます。

広すぎる権限

調査役やレビュアーに、ファイルを編集する権限は必要ありません。tools の制限は、役割をプロンプトのお願いではなく仕組みにする安価な方法です。

検証せずに報告を信じる

サブエージェントの回答にある「すべてのテストが通った」は、主張であって事実ではありません。オーケストレーターは、コマンドの出力、終了コード、具体的な行といった検証可能なものに基づくべきです。

まとめ

Claude Code のサブエージェントは三つの目的に使う道具です。メインの文脈をきれいに保つこと、検証と実行を分けること、独立した作業を並列にすることです。短い Markdown ファイルとして .claude/agents/ に定義し、その働きの質は、役割の説明、ツールの範囲、指示がどれだけ自己完結しているかによってほぼ決まります。課題が小さい場合や対話と強く結びついている場合は、一人のエージェントのほうがいまだに優れています。一つのループから、ノード、辺、共有状態からなるシステムへの移行は、講座で実践的に詳しく扱っています。