サブエージェントルーティング

問題: メインの Claude Code セッションは一日中サブエージェントを生成します。並列で実行すべきとき、連鎖させるべきとき、バックグラウンドに送るべきときの判断力が組み込まれていません。CLAUDE.md にルーティングルールがなければ、ただ1つを選びます。多くの場合、間違った選択をします。

すぐ使えるヒント: このルーティングブロックを CLAUDE.md に追加してください：

## Sub-Agent Routing Rules
 
**Parallel dispatch** (ALL conditions must be met):
 
- 3+ unrelated tasks or independent domains
- No shared state between tasks
- Clear file boundaries with no overlap
 
**Sequential dispatch** (ANY condition triggers):
 
- Tasks have dependencies (B needs output from A)
- Shared files or state (merge conflict risk)
- Unclear scope (need to understand before proceeding)
 
**Background dispatch**:
 
- Research or analysis tasks (not file modifications)
- Results aren't blocking your current work

メインスレッドはこのブロックを読み、自分でよりスマートなハンドオフをするようになります。

メインスレッドがルーターです

多くの人が見落としているポイントです。Claude Code は1つのモデルではありません。小さなチームであり、あなたのメインチャットがリーダーです。そのリーダーが専門サブエージェントに作業を渡します。下流のすべては、リーダーに仕事の渡し方をどれだけ教えたかによって機能します。

Task ツールには3つの実行モードがあります。それぞれ異なる種類の作業に適しています：

ルールを省略すると、リーダーは遅く、慎重な、一つずつの実行に戻ります。安全ですが、遅い。

並列: ドメインで分割

並列ディスパッチは、コードベースの異なる部分にまたがる作業に適しています。リーダーが境界線を認識できるよう、ドメインマップを CLAUDE.md に入れてください：

## Domain Parallel Patterns
 
When implementing features across domains, spawn parallel agents:
 
- **Frontend agent**: React components, UI state, forms
- **Backend agent**: API routes, server actions, business logic
- **Database agent**: Schema, migrations, queries
 
Each agent owns their domain. No file overlap.

厳格なルール: 並列は、エージェントが異なるファイルに触れる場合のみ機能します。リーダーはドメインの境界線を把握して、作業をクリーンに分割する必要があります。

順次: 互いに依存するチェーン

作業によっては、順番があるものもあります。ステップ2にはステップ1が生成したものが必要です。リーダーはその線を保持しなければなりません。

よく使うチェーンを CLAUDE.md に列挙してください。そうすれば、リーダーはそれを認識し、チェーンを並列で実行しようとするのをやめます。

バックグラウンド: あなたをブロックしないリサーチ

リサーチ的なタスクは自動的にバックグラウンドに落とすべきで、あなたは作業を続けられます。サブエージェントの実行中に Ctrl+B を押すか、最初からルールを設定してください：

## Background Execution Rules
 
Run in background automatically:
 
- Web research and documentation lookups
- Codebase exploration and analysis
- Security audits and performance profiling
- Any task where results aren't immediately needed

実行中のものを確認したいときはいつでも /tasks を実行してください。エージェントが完了すると結果が浮かび上がります。非同期ワークフローガイドに詳細があります。

サブエージェントの動作設定

ルーティングは1つの層です。Claude Code はサブエージェントの動作を直接制御するノブも提供します。

サブエージェントモデルを選択する

CLAUDE_CODE_SUBAGENT_MODEL は、Claude Code がサブエージェントに使用するモデルを指定します。この1つの変数が、他のほぼ何よりもコストと速度のダイヤルを動かします：

# Use a lighter model for sub-agents to save tokens
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"

クリーンな分割: ハードな思考のためにメインスレッドに Opus、集中したフォローアップ作業のためにサブエージェントに Sonnet。トークン消費が減り、各サブエージェントジョブはすでにスコープが明確になっているため、作業は完成します。

.claude/agents/ にスペシャリストを固定する

毎回新しい Task 呼び出しを起動する代わりに、.claude/agents/ に YAML フロントマター付きの Markdown ファイルとして名前付きスペシャリストを保存してください。Claude のオーケストレーターが自動的に見つけます。

.claude/agents/ には、リポジトリとともに保存され、チームに提供されるプロジェクトエージェントが含まれます。~/.claude/agents/ には、すべてのプロジェクトで使用するユーザーエージェントが含まれます。

ここのエージェントは CLAUDE.md を継承するため、規則、コーディングルール、プロジェクトの特性をすでに知った状態で表示されます。

パーミッションルールでエージェントをロックダウンする

パーミッションファイルの Task(AgentName) ルールは、どのサブエージェントを実行できるかを決定します：

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

--disallowedTools フラグは起動時に同じことをします：

claude --disallowedTools "Task(Explore)"

トークン消費を抑えたり、本番リポジトリから自律的な探索をロックアウトするのに便利です。

間違った呼び出しが本当のバグです

サブエージェントのトラブルのほとんどは実行ではありません。それを開始した呼び出しです。リーダーは曖昧な指示、コンテキスト不足、明確な終了条件なしでサブエージェントを送り込みます。サブエージェントは手持ちのもので最善を尽くします。

悪い呼び出し: 「認証を修正して」

良い呼び出し: 「ログイン成功後に /dashboard の代わりに /login にリダイレクトされる OAuth リダイレクトループを修正してください。src/lib/auth.ts の auth ミドルウェアを参照してください。」

差はコンテキストです。サブエージェントは自分の短命なウィンドウで実行されます。実行中に立ち止まって意図を聞き返すことができません。リーダーは最初から完全な呼び出しを書くための厳格なルールが必要です。

多くの CLAUDE.md ファイルはここで止まります。ルーティングは処理されます。呼び出しの品質は処理されません。しっかりした設定は両方をカバーします：すべてのディスパッチは、完全なコンテキスト、明確な指示、リンクされたファイル、具体的な完了の定義を持ちます。

よくあるオーケストレーションミス

過度な並列化: 小さな機能に10個の並列エージェントはトークンを消費し、調整作業を増やします。小さな関連タスクを1つのエージェントにグループ化してください。

並列化不足: 独立した4つのパスが並列で実行できるのに、順番に実行されています。ドメインの独立性を探してください。

曖昧な呼び出し: スコープ、ファイル、期待される出力なしに「機能を実装して」。

次のステップ

これらのルーティングルールだけで、リーダーが仕事を渡す方法が改善されます。その上にさらにプロレベルのオーケストレーションがあります：

• 4つのコアピースをすべてのディスパッチに強制するコンスティチューショナル呼び出し要件
• タスクタイプをスペシャリストエージェントにマッピングするエージェントルーティングテーブル
• 順次チェーンを通じて状態を引き継ぐコンテキストハンドオフプロトコル
• マルチステップ作業を追跡するためのセッションベースの調整

ルーティングルールから始めてください。今日 CLAUDE.md に貼り付けてください。明日、リーダーはより良いレーンを選ぶようになります。より深いパターンについては、タスク分散とエージェントファンダメンタルズをお読みください。