Claude Codeのエージェント設計パターン — 分割の判断基準と報告フォーマットの作り方

サブエージェントに切り出すかは3点で決まる

ある作業をサブエージェントへ切り出すべきかどうかは、独立性・コンテキスト量・検証可能性の3点を順に見れば判断できます。3つとも満たすなら切り出す価値があり、1つでも欠けるとメインで直接やったほうが速い、という関係になっています。

独立性は、その作業が他の作業の途中結果を必要としないかどうかです。サブエージェントは起動時に渡されたプロンプトだけを入力として動き、メインの会話履歴も他の子の状態も見えません。前段の出力を前提にする工程を並べると、独立しているがゆえに整合が取れなくなります。

コンテキスト量は、作業の過程で読み込む情報と、最終的に必要な情報の差です。50本のファイルを読んだ末に必要なのが3行の結論なら、差は大きく、切り出す価値があります。逆に1ファイル読んで1つの値を取り出すだけなら差はほぼゼロで、起動のオーバーヘッドだけが乗ります。

検証可能性は、返ってきた結果の正しさをメイン側で判断できるかどうかです。「ファイルパスと行番号」「テストの合否」「該当件数」は、必要なら再確認できます。「このコードは読みやすいと思います」のような評価は、根拠が子のコンテキストの中にしか残っていないため、メインでは検証しようがありません。

3点のうち検証可能性は、後から効いてくる割に見落とされがちです。切り出すと決めたら、その時点で「何をどんな形で返させるか」まで一緒に決めておく。この順序が設計を安定させます。

サブエージェントの定義ファイルの書き方そのものはサブエージェントの作り方にまとまっています。ここでは、作ると決めた後の設計判断に絞ります。

分担の型は4つに収れんする

実務で繰り返し現れる分担は、ほぼ次の4つに収まります。それぞれ切り出す理由が違うため、設計の力点も変わります。

調査のfan-out(1つの依頼を複数の子へ枝分かれさせる形)は、独立した観点をそれぞれ別の子に投げる型です。読み取りしかしないため衝突の心配がなく、最も気軽に使えます。設計上の要点は観点の切り分けで、重なると同じファイルを複数の子が読み直す無駄が出ます。

多視点レビューは、1つの差分を観点ごとに別の子へ渡す型です。1体に「品質を確認して」と投げると観点が毎回ぶれますが、セキュリティ・互換性・可読性のように分けると、指摘の粒度が揃います。独立したコンテキストで見るため、実装した本人が自己レビューするより見落としを拾いやすい性質もあります。

大量変換は、同じ規則を多数のファイルへ適用する型です。書き込みを伴うので、担当ファイルが重ならないことの確認が前提になります。ファイル単位で綺麗に割れるなら並列化でき、割れないなら1体に順次処理させます。

検証の分離は、テストや実機確認のログをメインから隔離する型です。並列化の旨味は小さく、狙いはコンテキストの保護に絞られます。失敗したときだけ詳細が欲しくなる工程なので、報告は合否と失敗箇所に絞り、詳細が要るときだけメインから改めて実行すれば足ります。並列実行そのものの具体パターンはサブエージェント完全活用で扱っているので、ここでは触れません。

4つの型は排他ではなく、1つの作業の中で順に現れます。調査でfan-outし、実装で大量変換を回し、最後に多視点レビューと検証をかける。どの局面にいるかを意識すると、その時点で並列にしてよいかが自然に決まります。

報告フォーマットを決めると成果が安定する

サブエージェント運用でいちばん効くのに、いちばん省略されがちなのが報告フォーマットの指定です。指定しなければ、子は毎回それらしい散文を返します。散文はメインで読み直す必要があり、複数体を束ねると形式の違いが統合の手間になります。

設計の考え方はシンプルです。メインが次の判断に使う情報だけを、機械的に読める形で返させます。具体的には次の3つを指示文に書き込みます。

1. 返す項目(何を含めるか)
2. 返さない項目(何を含めないか)
3. 該当が0件のときの返し方

3つ目が抜けると、該当なしの場合に「調査しましたが見つかりませんでした。念のため周辺も確認したところ……」という長い弁明が返ってきます。「該当なしとだけ返す」と一行足すだけで防げます。

事実収集に使う報告フォーマット

報告は次の表だけで返してください。前置き・総括・所感は不要です。
 
| ファイル:行 | 該当する記述 | 確度(確実/推定) |
 
- 推定の行には、なぜ推定なのかを「該当する記述」列に1文で書く
- 該当が0件なら「該当なし」とだけ返す

確度の列を分けているのは、子が推測と事実を混ぜて返すのを防ぐためです。メイン側は「確実」の行をそのまま採用し、「推定」の行だけ再確認すればよくなります。確度を1列足すコストで、検証すべき対象が絞り込めます。

レビューに使う報告フォーマット

指摘は次の形式で、重要度順に並べてください。
 
[Must|Want|Nit] ファイル:行 — 指摘内容(1〜2文)
                 修正案(あれば1文)
 
- Must は「マージ前に直さないと壊れる」もののみ
- 指摘が0件なら「指摘なし」とだけ返す
- コード全体の要約は書かない

3段階の定義を指示文の中で与えているのが要点です。Must・Want・Nitという言葉だけ渡すと、子ごとに閾値が変わります。「マージ前に直さないと壊れる」という判定条件を書いておけば、複数体のMustを横並びにしても意味が揃います。

変換作業に使う報告フォーマット

処理が終わったら次の3行だけ返してください。
 
処理件数: N件
スキップ: M件(理由ごとに件数)
要確認: ファイルパスの一覧(判断に迷った箇所のみ)
 
変更後のコードは貼らないでください。差分はメイン側で確認します。

「変更後のコードは貼らない」は、大量変換では特に効きます。50ファイルを変換した子が全ファイルの差分を返してくると、コンテキストを節約するために切り出した意味が消えます。差分の確認はメイン側のgit diffで足ります。

報告フォーマットが効く理由

3つの例に共通するのは、報告が次の行動に直結する単位になっていることです。表の行はそのまま確認対象のリストになり、Mustの一覧はそのまま修正タスクになり、要確認のパスはそのまま目視対象になります。散文の報告は、読んでからこの変換を人間かメインエージェントが行う必要があり、その分だけ手数とコンテキストを消費します。

もう1つの効果は、子の振る舞いが安定することです。返す形が決まっていると、子は形式を満たすために必要な作業を逆算します。「ファイル:行」を求められた子は、記憶で答えず実際に該当箇所を特定しにいきます。フォーマットの指定は、暗黙のうちに作業の厳密さも指定していることになります。

ツール権限とモデルは責務から逆算する

サブエージェント定義ではtoolsでツールを制限でき、modelで使うモデルを指定できます。この2つは、責務を決めた後に逆算して埋める項目です。

toolsを指定すると、書かれていないツールは使えなくなります。調査専任ならRead・Grep・Globだけで足り、書き込み系を外しておけば、並列で何体走らせてもファイルが壊れる経路がありません。権限の制限は、注意深さではなく仕組みで衝突を防ぐ手段として働きます。逆に、必要なものを書き忘れると動かないため、責務に必要な最小集合を意識して展開します。

子がさらに別の子を呼べるかどうかもtoolsで決まります。toolsにAgentを含めない限り、サブエージェントは他のサブエージェントを起動できません。Agentを含め、さらに環境変数CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで許可する階層数を指定すると、入れ子の起動が可能になります(v2.1.172以降・最大5階層)。入れ子は階層が深くなるほど報告が要約を重ねて劣化するため、2階層までに留めるのが扱いやすい範囲です。

modelの選び方は、判断の性質で分かれます。

軽量モデルで済む作業を上位モデルに投げるとコストが乗り、逆に微妙な判断を軽量モデルに投げると精度が落ちます。前者は無駄で済みますが、後者は結果が信用できなくなるため影響が大きくなります。判定軸を指示文に書き切れたかどうかが、軽量モデルへ落とせるかの目安になります。

ほかにisolation(編集をgit worktreeへ隔離するか)、memory、maxTurnsといったフィールドも定義で指定できます。書き込みを伴う子にはisolation: worktreeを付けておくと、起動時に一時的なworktreeへ作業領域が切り替わり、複数体を並列にしてもファイルが踏み合いません。

descriptionは呼ばれ方そのものを決める

定義ファイルに切り出したサブエージェントは、descriptionを根拠に選ばれます。Claudeは各エージェントの説明文を読んで「今この責務を呼ぶべきか」を判断するため、説明が抽象的だと、似た定義が複数あるときに選択がぶれます。呼ばれないエージェントは、中身がどれだけ丁寧でも動きません。

書き分けのコツは、責務・入力・出力・観点数の4つを1文に詰めることです。

# 選択がぶれる書き方
description: コードをレビューします
 
# 判別できる書き方
description: 差分コードをセキュリティ・互換性・命名の3観点でレビューし、
  指摘を Must / Want / Nit に分類して ファイル:行 付きで返す。
  新規実装の設計相談には使わない。

最後の一行のような否定形も効きます。「何に使わないか」を書いておくと、責務が近い定義との境界がはっきりし、誤って呼ばれる頻度が下がります。定義を増やすほど、この境界の記述が重要になります。

ここまでの設計は、エージェント1体ごとの話です。複数体をどう束ね、どんな順序で走らせるかというメイン側の運用はオーケストレーター設計にまとめています。

切り出さないほうがよいケース

分割が裏目に出るパターンも、いくつか決まった形があります。

段階的に詰めていく作業は切り出しに向きません。「書いてみて、見て、次を決める」進め方は、判断のたびにメインへ戻る必要があり、投げて1通返す構造と噛み合いません。この種の作業をサブエージェントに渡すと、渡した時点の想定のまま最後まで走り切って、途中で分かれ道があったこと自体が報告されずに終わります。

責務が重なる子を並べるのも避けたいところです。「コードレビュー担当」と「品質チェック担当」のように説明が近い定義が複数あると、どちらを呼ぶかの選択がぶれます。サブエージェントはdescriptionを読んで選ばれるため、責務・入出力・観点が1文で判別できる粒度に書き分けます。名前が似ているだけで実質が同じなら、統合したほうが運用は安定します。

1〜2回のツール呼び出しで終わる作業も、切り出す価値がありません。ファイルを1つ読む、grepを1回かける、といった作業では、プロンプトを書く手間と起動のオーバーヘッドが本体を上回ります。

最後に、結果の正しさをメインで確かめられない作業です。冒頭の検証可能性がここに戻ってきます。「いい感じに整えておいて」のような依頼は、返ってきた報告が正しいかどうかを判断する材料がなく、結局メインで全部読み直すことになります。切り出す前に、報告を受け取った自分が何をもって合格と判断するかを1文で言えるか確かめておくと、この失敗は避けられます。

よくある質問

汎用エージェントと専用エージェントはどう使い分けますか

その責務を繰り返し使うかどうかが分かれ目です。一度きりの調査なら、汎用のサブエージェントに詳しいプロンプトを渡せば足ります。同じ観点のレビューを毎回走らせるなら、定義ファイルに切り出したほうがプロンプトを書き直す手間が消え、観点の揺れもなくなります。切り出す判断の全体像はClaude Code Sub-agents完全ガイドの早見表が参考になります。

報告フォーマットを厳しくすると情報が落ちませんか

落ちます。ただし落ちるのは、メインが次の判断に使わない情報です。想定外の発見を拾いたい場合は、フォーマットの最後に「上記に収まらない重要な発見があれば、最大3行で追記してよい」と逃げ道を1つだけ用意します。無制限の自由記述にしないことが要点です。

同じ責務のエージェントを複数体走らせる意味はありますか

観点や対象を変えるなら意味があります。同じ観点・同じ対象で複数体を走らせても、返ってくる内容が似通うため統合のコストだけが増えます。多視点レビューが有効なのは、体数を増やしているからではなく、観点を分けているからです。

子に渡すプロンプトはどれくらい詳しく書くものですか

前提は省略せずに全部書きます。子はメインの会話履歴を見られないため、こちらが当然と思っている条件ほど抜けやすくなります。対象のファイルパス、すでに決まっている方針、触ってはいけない範囲、そして報告フォーマット。この4つが入っていれば、プロンプトが長くなっても手戻りより安く済みます。逆に「さっきの件で」「例のファイルを」といった指示語は、子には解決できません。

サブエージェントが期待と違う動きをするときは何を疑いますか

まずプロンプトに前提が書かれているかを確認します。メインで共有したはずの情報も、子には渡っていません。編集中のファイル、直前の調査結果、採用済みの設計判断は、毎回プロンプトへ明示的に含める必要があります。次に疑うのはtoolsの指定漏れで、必要なツールが許可リストから抜けていると、子は代替手段でそれらしく処理を進めてしまいます。

まとめ

サブエージェントの設計は、独立性・コンテキスト量・検証可能性で切り出す対象を決め、分担の型を選び、報告フォーマットを固定する、という順序で組み立てられます。この3段階のうち、成果の差が最も大きく出るのは報告フォーマットです。何を返させるかを決めることは、何をやらせるかを決めることとほぼ同義になります。

作り始めるなら、読み取り専用の調査エージェントに表形式の報告を指定するところからが手堅い入口です。そこで報告設計の勘所を掴んでから、レビューや変換のように書き込みと判断が絡む責務へ広げていくと、権限とモデルの選び方も自然に決まってきます。