エージェントパターン

問題: サブエージェントは機能するが、毎回同じ形状に頼ってしまう。並列呼び出しを適当にやって、戻ってきたものを手動で繋ぎ合わせる。エージェントの作業を整理するより良い方法があり、選ぶ形状によって出力が持ちこたえるか崩れるかが決まります。

6つのオーケストレーションパターンが実際の Claude Code の作業で繰り返し登場します。それぞれが異なる種類のジョブに適しています。選択を誤るとトークンが漏れ、ファイルが衝突し、回答がブレます。正しく選べば、大量のエージェントがほぼ監督なしで難しい作業をこなします。

パターン選択ガイド

素早く選ぶだけなら、このルールを使ってください。

ジョブがこのように見える場合...	これから始める...
1つの中心スレッドが計画全体を把握し続ける必要がある	オーケストレーター
多くの独立した調査を1つの統合に束ねる	ファンアウト / ファンイン
コードを別の目でチェックする必要がある	バリデーションチェーン
異なるタスクタイプが異なるスペシャリストに属する	スペシャリストルーティング
品質が1回ではなく複数回のパスで向上する	プログレッシブリファインメント
作業中にバックグラウンドで何かを監視する	ウォッチドッグ

パターンをイデオロギーのように扱うのは誤りです。パターンは作業負荷の形状です。目の前の調整問題に合ったものを選んでください。

このページはオーケストレーション形状が未決な時に読んでください。サブエージェント、スラッシュコマンド、エージェント定義、リポジトリ全体のルールの選択でまだ迷っている場合は、エージェントの基本から始めてください。作業負荷が共有タスクリストとメールボックスを通じて複数の Claude セッションが直接協調する必要がある場合は、Claude Code Agent Teamsに進んでください。

オーケストレーターパターン

1つの中心スレッドが全体を仕切り、スペシャリストに作業を渡します。コード自体には触れません。計画、委譲、レビュー、ルーティングが仕事のすべてです。

いつ使うか: フロントエンド、バックエンド、データベースをまたぐ機能。誰かが全体像を頭に保持する必要があるもの全般。

Claude Code での動作: プライマリチャットが指揮者になります。仕様を読み、計画を作成し、Task ツールでスペシャリストを生成します。結果が戻ってきたらレビューし、次の手を即座に決定します。

You are the orchestrator. For this feature request, create a plan that:
1. Breaks the work into domain-specific tasks
2. Identifies dependencies between tasks
3. Dispatches each task to a sub-agent with explicit file scope
4. Reviews outputs before marking complete

Do NOT write implementation code yourself. Coordinate only.

CLAUDE.md がこの配線の自然な置き場所です。ルーティングルールはそのファイルに置き、指揮者はそれをコントラクトとして扱います。堅牢なセットアップでは、サブエージェントが1行書く前にタスク依存グラフ全体が決定されます。

使わない場合: 1つのエージェントが1回のパスで完了できる小さなジョブ。ユーティリティの追加、タイプミスの修正。オーケストレーションの管理コストが持ち帰る価値を上回ります。

ファンアウト / ファンインパターン

多くのエージェントが並列で出て行き、全員が報告します。1つのスレッドが結果を1つの回答にまとめます。

いつ使うか: リサーチのスイープ。マルチファイル分析。各エージェントが独自の入力で重複なく動作するもの全般。独立したモジュール全体のコードレビュー。何かを決定する前にコードベースの各コーナーからインテルを収集する場面。

Claude Code での動作: 同じメッセージで複数の Task ツール呼び出しを発行して並列サブエージェントを起動します。それぞれが独自のファイルを開くか独自の懸念を追います。すべてのエージェントが返ってきたら、中心スレッドが断片を繋ぎ合わせます。

Complete these 4 tasks using parallel sub-agents:

1. Read src/api/ and list all endpoints missing input validation
2. Read src/auth/ and identify any hardcoded secrets or weak patterns
3. Read src/db/ and check for missing indexes on frequently queried columns
4. Read src/utils/ and flag any functions with no error handling

After all agents report back, synthesize findings into a prioritized action list.

ファンアウトフェーズはエージェントが状態を共有しないため高速です。ファンインフェーズが本当の価値を生みます。オーケストレーターが単独のエージェントには見えなかった発見間のつながりを捉えます。弱い認証パスと入力バリデーションのギャップは、それぞれの報告がそう読めなくても、合わさると実際の脆弱性になることがあります。

使わない場合: 複数のエージェントが重複するファイルを編集する必要があるジョブ。共有コードへの並行書き込みはマージコンフリクトに直進します。作業が本当に独立していない場合は、シーケンシャルチェーンが正しい選択です。

バリデーションチェーンパターン

ビルダーエージェントがコードを書きます。別のバリデーターエージェントがそれを検査します。役割が交わることはありません。

いつ使うか: 本番環境の変更。セキュリティに敏感な作業。間違った回答が実際のコストを生む場面。バグのリリースが絶対に許されない時にこのパターンを使ってください。

Claude Code での動作: 依存関係で繋がれた2つのタスク。ビルダーが先にコードを出荷します。完了後、バリデーターが差分を開いてテストを実行し、ファイルには一切触れずにレポートを提出します。

TaskCreate(
  subject="Build payment webhook handler",
  description="Create Stripe webhook handler in src/api/webhooks/stripe.ts.
  Handle checkout.session.completed, payment_intent.failed events.
  Verify webhook signatures. Include error handling."
)

TaskCreate(
  subject="Validate payment webhook handler",
  description="Read src/api/webhooks/stripe.ts. Verify:
  - Webhook signature verification exists
  - Both event types handled with proper responses
  - Error handling covers malformed payloads
  - No hardcoded secrets
  Report issues only. Do NOT modify any files."
)

TaskUpdate(taskId="2", addBlockedBy=["1"])

addBlockedBy リンクがバリデーターを誠実に保ちます。ビルダーが完了するまで待機し、白紙の状態で入ります。共有された前提なし。継承された盲点なし。だからこそチェックが実際に問題を検出します。

バリデーターが問題を発見すると、ビルダーにルーティングされる修正タスクを開きます。次に新しいバリデーターがその修正の後にキューされます。出力が正しくなるまでループが絞り込まれます。

使わない場合: 速度が正確さを上回るプロトタイピング。専用バリデーターはタスクあたりの計算量をほぼ2倍にします。コードが試作段階なら、1体のエージェントの方が少ないトークンで速く達成できます。

スペシャリストルーティングパターン

各タスクをそのジョブを知るドメインエキスパートにルーティングします。フロントエンドの作業はフロントエンドスペシャリストに。マイグレーションはデータベースエキスパートに。各エージェントが独自の規約、指示、ツール制限を持ちます。

いつ使うか: 複数の明確なドメインを持つ大きなリポジトリ。レイヤーごとに確立された規約を持つチーム。一般的な指示がコードベース全体で曖昧で一貫性のない出力を出し続ける場面。

Claude Code での動作: .claude/agents/ にスペシャリストエージェントを設置するか、ルーティングルールを CLAUDE.md に固定します。オーケストレーターがタスクを検査し、ドメインをタグ付けし、適切なエキスパートに渡します。

<!-- In CLAUDE.md -->

## Agent Routing Table

| Task Domain | Route To            | File Scope           |
| ----------- | ------------------- | -------------------- |
| React/UI    | frontend-specialist | src/components/      |
| API routes  | backend-engineer    | src/api/, src/lib/   |
| Database    | database-specialist | src/db/, migrations/ |
| Security    | security-auditor    | Any (read-only)      |
| Tests       | quality-engineer    | tests/, **tests**/   |

.claude/agents/ で定義されたすべてのスペシャリストは自動的に CLAUDE.md を継承します。コーディング標準も一緒に付いてきます。エージェント自身のファイルが残りを追加します。フレームワークの選択、命名規則、そのレイヤーに合わせたエラーハンドリング。

拡張は安価です。新しいドメインは新しいエージェントファイルとルーティングテーブルの新しい行を意味します。何も書き直しません。カスタムエージェントガイドに YAMLフロントマターでスペシャリストを定義する方法が書かれています。

使わない場合: 1つのエージェントがすでに全体のコンテキストを十分に持っている小さなコードベース。行き先が1つしかない場合、ルーティングのオーバーヘッドは何も生みません。

プログレッシブリファインメントパターン

大まかなドラフトから始めます。複数回の編集パスを経ます。各ラウンドは1つの品質軸に集中します。

いつ使うか: コンテンツ作業、複雑なアーキテクチャ、1回のショットで正しく仕上げるのが非現実的なジョブ。ブログ記事、API スキーマ、複数の制約を同時に満たす必要があるコンフィグファイルに対してきれいに機能します。

Claude Code での動作: 前の出力を読んで1つの側面を改善するエージェントをシーケンスとしてキューします。

Phase 1 - Draft: "Generate the initial API schema for a task management
system. Include all entities, relationships, and basic validation rules."

Phase 2 - Security review: "Review this schema. Add authentication
requirements, permission checks, and input sanitization rules.
Don't change the core structure."

Phase 3 - Performance review: "Review the schema for performance.
Add indexes, identify N+1 query risks, suggest denormalization
where read performance matters."

Phase 4 - Final validation: "Verify the schema is consistent.
Check that all referenced entities exist, foreign keys are valid,
and naming conventions are uniform."

各フェーズが狭い視点を持ちます。ドラフトエージェントは完全性を気にします。セキュリティがガードレールを追加します。パフォーマンスがチューニングします。バリデーションが一貫性をチェックします。どのエージェントも一度に全ての懸念を抱えさせられません。

実際の開発者の作業方法を反映しています。コードは最初のパスで本番環境に出せる状態にはなりません。ドラフト、正確さの修正、パフォーマンスのチューニング、仕上げという手順を踏みます。このパターンはそれぞれのパスをそれに合わせた形のエージェントに渡します。

使わない場合: 1回のショットで結果を出さなければならないジョブ、段階的な改善ができない場合。最初のドラフトがすでに基準をクリアしているシンプルな作業にも意味がありません。

ウォッチドッグパターン

バックグラウンドエージェントが座って条件を監視します。発火すると、ウォッチドッグが報告またはアクションを起こします。メインの作業の傍らで動き、邪魔をしません。

いつ使うか: ドリフトが忍び込む長いセッション。コンテキストの健全性の監視、リファクタリング中のリグレッションの検出、別の作業に集中している間のビルドの失敗の監視。

Claude Code での動作: Ctrl+B でウォッチドッグをバックグラウンドに送り、作業を続けます。エージェントがリズムよくトリガーをチェックします。何かが発火すると、結果がタスクリストに直接出てきます。

Background task: Monitor the test suite while I refactor the auth module.
Every time I complete a change, run the test suite for src/auth/.
If any test fails, immediately create a task with:
- Which test failed
- The assertion error
- Which file I likely broke based on the test name

良い例がコンテキスト回復フックに存在します。それはインフラ自体に組み込まれたウォッチドッグで、コンテキストの使用量を追跡し、ウィンドウが埋まり始めた瞬間に回復を発火させます。エージェントの健全性フックと進捗フックも同様に動作します。

ウォッチドッグは非同期ワークフローとペアにした時に最もペイします。バックグラウンドのエージェントが単独で実行され、準備ができた時に結果が目の前に出てきます。

使わない場合: 監視コストが監視対象の価値を上回る短いセッション。2分のタスクに30秒ごとにポーリングするウォッチドッグを付けてもトントンです。