サブエージェントの設計と活用

このレッスンで学ぶこと

• .claude/agents/にサブエージェントを定義し、実際に呼び出すまでの一連の手順を身につける
• 並列実行を実装し、複数のサブエージェントを同時に走らせる
• メインエージェントがタスクをどう分解してサブエージェントに振るかを設計する
• 複数のサブエージェントから返ってきた結果を統合するパターンを身につける

前提条件

• 実践コース Lesson 9（コンテキスト管理を最適化する）で、サブエージェントへの委譲がコンテキスト節約に役立つことを理解していること
• ガイド「サブエージェント活用完全ガイド」で役割分担の設計思想に触れていると理解がスムーズです（必須ではありません）

サブエージェントを定義する

サブエージェントはYAMLフロントマター付きのMarkdownファイルです。保存場所によって誰が使えるかが決まります。

実際に、コードレビュー専用のサブエージェントを定義してみましょう。

mkdir -p .claude/agents

---
name: api-reviewer
description: APIエンドポイントの実装をレビューする。REST設計の一貫性、エラーハンドリング、入力検証の不足をチェックする。エンドポイントの実装後やAPIレビューを依頼されたときに使用する。
tools: Read, Grep, Glob
model: sonnet
---

あなたはAPI設計に精通したレビュアーです。指定されたエンドポイントの実装を、
以下の観点でレビューしてください。
 
1. **RESTfulな一貫性**: リソース名・HTTPメソッド・ステータスコードが規約に沿っているか
2. **入力検証**: リクエストボディ・クエリパラメータの検証が漏れていないか
3. **エラーハンドリング**: 想定されるエラーケースに対して適切なステータスコード・メッセージを返しているか
 
指摘は「深刻度（High/Medium/Low）」「該当ファイル・行番号」「問題点」「修正案」の
4項目で報告してください。問題がなければ「問題は見つかりませんでした」と明記してください。

api-reviewerサブエージェントを使って、src/api/users.ts のレビューをして

@api-reviewer src/api/users.ts をレビューして

並列実行を実装する

複数の独立した調査・検証を同時に進めたいとき、サブエージェントを並列に呼び出すことで待ち時間を圧縮できます。実装する際は、まず「本当に並列化できるか」をタスクの依存関係から判断する必要があります。

判断基準: 依存関係を先に洗い出す

並列実行を指示する前に、対象のタスクが互いの結果を必要としないかを確認します。たとえば「フロントエンドのコンポーネント構成を調査する」と「バックエンドのAPI一覧を調査する」は互いに独立しているため並列化できますが、「APIを設計する」と「そのAPIを呼ぶフロントエンドコードを書く」は前者の結果が後者の入力になるため並列化できません。

実装パターン: 1つの指示で複数領域を投げる

並列実行は特別なコマンドではなく、1回のプロンプトで複数の独立した調査を依頼するだけで実現します。

以下の3つの調査を、それぞれ別のサブエージェントを使って並列に実施して。
 
1. src/auth/ 配下の認証フローの実装方式
2. src/api/ 配下のAPIエンドポイント一覧とその認可要件
3. src/components/ 配下で認証状態を参照しているコンポーネント一覧
 
それぞれ「調査対象のファイルパス」「実装の要点」を箇条書きで報告して。

Claudeはこれを受けて、3つの独立したサブエージェント（多くの場合general-purposeまたはExplore）をバックグラウンドで同時に起動し、すべてが完了した時点で結果をまとめて返します。

カスタムサブエージェントを使った並列実行

定義済みのサブエージェントを複数同時に使うこともできます。たとえば、フロントエンド用・バックエンド用のレビューサブエージェントをそれぞれ定義しておけば、次のように依頼できます。

frontend-reviewerとbackend-reviewerサブエージェントを使って、
今回のPRの変更をそれぞれの観点から並行してレビューして

それぞれが独立したコンテキストで動作するため、フロントエンドの指摘がバックエンドレビューの視点に引っ張られる、といった汚染が起きません。

タスク分解の設計: メインエージェントはどう振るべきか

並列実行も逐次実行も、土台にあるのは「タスクをどう分解し、どのサブエージェントに何を振るか」という設計判断です。実践的な分解の進め方を見ていきます。

ステップ1: タスクを「閉じた単位」に切り出す

サブエージェントへの委譲が有効なのは、入力と出力が明確で、途中経過をメインに残す必要がないタスクです。たとえば「ログイン機能を実装する」という大きなタスクをそのままサブエージェントに投げるのではなく、次のように分解します。

graph TD
    T["タスク: ログイン機能を実装する"]
    A["調査: 既存の認証関連コードの棚卸し<br/>（閉じている → 委譲可能）"]
    B["設計: APIとセッション管理方式の決定<br/>（対話が必要 → メインで実施）"]
    C["実装: ログインフォームとAPI呼び出し<br/>（設計確定後なら委譲可能）"]
    D["検証: 実装後のセキュリティレビュー<br/>（閉じている → 委譲可能）"]
 
    T --> A --> B --> C --> D
 
    style A fill:#e8f4fd,stroke:#1a73e8
    style D fill:#e8f4fd,stroke:#1a73e8
    style B fill:#fff3e0,stroke:#e65100

「調査」と「検証」は入力と出力が明確なので委譲に向き、「設計」はユーザーとの対話を通じて方向性を詰める必要があるためメインエージェントが担います。

ステップ2: 委譲メッセージを自己完結させる

サブエージェントはメインの会話履歴を見られません。タスクを振るときの指示は、「初めてプロジェクトに参加したメンバーに依頼する」つもりで、背景情報込みで自己完結させます。

悪い指示:
「さっき話してた認証の調査、サブエージェントでやって」
 
良い指示:
「src/auth/配下の認証フローを調査して。
具体的には、トークンのリフレッシュ処理がどう実装されているか、
既存のOAuthユーティリティ（src/auth/oauth/配下）があればその使われ方も含めて。
報告はファイルパスと行番号付きの箇条書きで」

ステップ3: 出力フォーマットを指定して、統合しやすくする

複数のサブエージェントの結果を後で統合することを見越して、報告フォーマットを揃えておくと統合作業が楽になります。「ファイルパスと深刻度を明記する」「箇条書きで3項目以内に要約する」といった指定は、次のステップの結果統合に直接効いてきます。

結果統合のパターン

複数のサブエージェントから返ってきた出力を、メインエージェントがどうまとめるかには、いくつかの典型パターンがあります。

パターン1: 単純集約

並列調査のように、各サブエージェントの担当領域が重ならない場合は、単純にセクションを分けて並べるだけで十分です。

## 認証フロー（auth-investigator調査結果）
- トークンリフレッシュは src/auth/refresh.ts で実装
- ...
 
## APIエンドポイント（api-investigator調査結果）
- 認可が必要なエンドポイントは12個
- ...

パターン2: 突き合わせ統合

複数のサブエージェントの結果に矛盾や重複がありうる場合（たとえば2つのレビューサブエージェントが同じファイルを別の観点で見た場合）は、メインエージェントが内容を突き合わせ、優先順位をつけて1つの結論にまとめる必要があります。

frontend-reviewerとbackend-reviewerの指摘を統合して。
両方が同じファイルに言及している場合は、深刻度が高い方を優先して
1つのレビューサマリーにまとめて。重複する指摘は1つにまとめること。

このとき、メインエージェントに「どう統合するか」の方針を明示しておくことが重要です。指定がないと、単に指摘を連結しただけの冗長な報告になりがちです。

パターン3: パイプライン統合（逐次実行の結果を引き継ぐ）

「調査 → 実装 → レビュー」のように逐次実行する場合、前段の結果は次段への入力としてメインエージェントが要約・整形してから渡します。

graph LR
    S1["サブエージェントA<br/>調査結果"]
    M1["メインエージェントが<br/>要点を整形"]
    S2["サブエージェントB<br/>整形済み要点を入力に実装"]
    M2["メインエージェントが<br/>diffを整形"]
    S3["サブエージェントC<br/>diffをレビュー"]
 
    S1 --> M1 --> S2 --> M2 --> S3
 
    style M1 fill:#fff3e0,stroke:#e65100
    style M2 fill:#fff3e0,stroke:#e65100

メインエージェントが各段階で「次のサブエージェントに何を渡すべきか」を取捨選択することで、調査結果の生データがそのまま後段に積み上がっていくことを防げます。この設計が、3つのサブエージェントを使うマルチエージェントパイプラインの基礎になります（詳しくはLesson 10: マルチエージェントパターンで扱います）。

実践: 定義から並列実行・統合までを通しでやってみる

ここまでの内容を1つの流れとして実践してみましょう。

---
name: frontend-investigator
description: フロントエンドのコンポーネント構成・状態管理を調査する。UI変更の影響範囲を把握したいときに使用する。
tools: Read, Grep, Glob
---
 
src/components/ と src/hooks/ を中心に、指定されたテーマについて
コンポーネント構成と状態管理の実装方法を調査し、ファイルパス付きで報告してください。

frontend-investigatorとbackend-investigatorを使って、
「ユーザープロフィール編集機能」に関連する実装をそれぞれ並列に調査して。

両方の調査結果を踏まえて、プロフィール編集機能をどう拡張すればよいか、
変更が必要なファイルの一覧として整理して。

この流れを実際に動かしてみると、「待ち時間の短縮」と「視点の独立性」という並列実行の効果を体感できます。

まとめ

このレッスンでは、サブエージェントを実際に定義し、並列実行を組み立て、タスクを分解してサブエージェントに振り、複数の結果を統合するという一連の実践フローを学びました。

• サブエージェントは.claude/agents/にMarkdownファイルとして定義し、nameとdescriptionが委譲判断の鍵になる
• 並列実行は「タスク同士が独立しているか」を見極めたうえで、1回のプロンプトで複数領域を投げるだけで実現できる
• タスク分解では「閉じたタスク」をサブエージェントに、対話が必要な部分はメインエージェントに残す
• 結果統合には単純集約・突き合わせ統合・パイプライン統合の3パターンがあり、用途に応じて統合方針を明示する

サブエージェントを使いこなせるようになったら、次はその仕組みをプログラムから直接操作するAgent SDKに進みます。Lesson 8: Agent SDKの基礎では、Claude Code CLIの裏側にある仕組みをコードから利用する方法を学びます。