subagents

サブエージェントの連携

タスクを適切なエージェントとスキルの組み合わせにマッチングすることで、outfitter サブエージェントをオーケストレーションします。

オーケストレーションの計画

複雑なマルチエージェントタスクでは、実行前に Plan サブエージェントから開始して、オーケストレーション戦略を調査・設計します。

Complex task arrives
    │
    ├─► Plan subagent (research stage)
    │   └─► Explore codebase, gather context
    │   └─► Identify which agents and skills needed
    │   └─► Design execution sequence (sequential, parallel, or hybrid)
    │   └─► Return orchestration plan
    │
    └─► Execute plan (dispatch agents per plan)

Plan サブエージェントの利点:

• 分離されたコンテキストで実行される — メイン会話のトークンを消費しません
• オーケストレーターのコンテキストを肥大化させることなく、多くのファイルを読み取れます
• 実行用の簡潔な計画を返します

Plan サブエージェントを使用する場面:

• タスクが複数の領域にまたがる場合 (認証 + パフォーマンス + テスト)
• 未知のコードベース領域 — まず調査が必要な場合
• エージェントの順序が重要である場合 (ステップ間の依存関係)
• 慎重な連携が必要な重要な変更

コンテキスト管理

長時間実行されるオーケストレーションでは、context-management スキルを読み込みます。このスキルが教える内容:

• Tasks を存続可能な状態として使用する (コンパクションをまたいで永続化)
• メインコンテキストを保持するためにサブエージェントに委任する
• 進捗を記録するためのコンパクション前チェックリスト
• 複数日にわたる作業のためのセッション間パターン

重要な原則: メイン会話のコンテキストは貴重です。調査と研究はサブエージェントに委任してください — 返ってくるのは要約だけなので、メインコンテキストを簡潔に保てます。

ロールとエージェント

連携では、ロール (どのような機能が必要か) を エージェント (それを実行するのは誰か) にマッピングして使用します。これにより、より適したエージェントが利用可能な場合に置き換えが可能になります。

ベースレイヤーエージェント

ロール	エージェント	目的
coding	engineer	構築、実装、修正、リファクタリング
reviewing	reviewer	コード、PR、アーキテクチャ、セキュリティの評価
research	analyst	調査、研究、探索
debugging	debugger	問題の診断、問題の追跡
testing	tester	動作の検証、証明、確認
challenging	skeptic	複雑さへの異議、前提への疑問
specialist	specialist	ドメインの専門知識 (CI/CD、デザイン、アクセシビリティなど)
patterns	analyst	作業から再利用可能なパターンを抽出

その他の利用可能なエージェント

追加のエージェントが環境で利用可能な場合があります (ユーザー定義、プラグイン提供、または組み込み)。ディスパッチする際は:

1. ロールに最も適した利用可能なエージェントを確認する
2. タスクに合致する場合は、汎用エージェントよりも専門エージェントを優先する
3. より良い選択肢が存在しない場合は、outfitter エージェントにフォールバックする

ロールの置き換え例:

• coding → senior-engineer、developer、engineer
• reviewing → security-auditor、code-reviewer、reviewer
• research → research-engineer、docs-librarian、analyst
• specialist → cicd-expert、design-agent、accessibility-auditor、bun-expert

タスクルーティング

ロールによってルーティングし、そのロールに最適な利用可能なエージェントを選択します:

User request arrives
    │
    ├─► "build/implement/fix/refactor" ──► coding role
    │
    ├─► "review/critique/audit" ──► reviewing role
    │
    ├─► "investigate/research/explore" ──► research role
    │
    ├─► "debug/diagnose/trace" ──► debugging role
    │
    ├─► "test/validate/prove" ──► testing role
    │
    ├─► "simplify/challenge/is this overkill" ──► challenging role
    │
    ├─► "deploy/configure/CI/design/a11y" ──► specialist role
    │
    └─► "capture this workflow/make reusable" ──► patterns role

ワークフローパターン

シーケンシャルハンドオフ

1 つのエージェントが完了し、次へ引き継ぎます:

research (investigate) → coding (implement) → reviewing (verify) → testing (validate)

使用する場面: 明確な段階があり、それぞれに異なる専門知識が必要な場合。

並列実行

複数のエージェントが run_in_background: true を使用して同時に作業します:

┌─► reviewing (code quality)
│
task ──┼─► research (impact analysis)
│
└─► testing (regression tests)

使用する場面: 独立した関心事、時間に敏感な場合、包括的なカバレッジが必要な場合。

チャレンジループ

構築 → 異議 → 改善:

coding (propose) ←→ challenging (evaluate) → coding (refine)

使用する場面: 複雑なアーキテクチャ、過剰設計の防止、重要な意思決定。

調査チェーン

絞り込んでから修正します:

research (scope) → debugging (root cause) → coding (fix) → testing (verify)

使用する場面: バグ報告、本番環境の問題、不明確な症状。

ロール + スキルの組み合わせ

Coding ロール

タスク	スキル
新機能	software-craft、tdd
バグ修正	debugging → software-craft
リファクタリング	software-craft + simplify
API エンドポイント	hono-dev、software-craft
React コンポーネント	react-dev、software-craft
AI 機能	ai-sdk、software-craft

Reviewing ロール

タスク	スキル
PR レビュー	code-review
アーキテクチャレビュー	architecture
パフォーマンス監査	performance
セキュリティ監査	security
マージ前チェック	code-review + scenarios

リサーチロール

タスク	スキル
コードベースの調査	codebase-recon
リサーチの問い	research
不明確な要件	pathfinding
ステータスレポート	status, report-findings

テストロール

タスク	スキル
機能の検証	scenarios
TDD 実装	tdd
統合テスト	scenarios

高度な実行パターン

バックグラウンド実行

並列作業のためにエージェントを非同期で実行します:

{
  "description": "Security review",
  "prompt": "Review auth module for vulnerabilities",
  "subagent_type": "outfitter:reviewer",
  "run_in_background": true
}

TaskOutput で結果を取得します:

{
  "task_id": "agent-abc123",
  "block": true
}

サブエージェントのチェーン

複雑なワークフローのためにエージェントを順番に実行します — 各エージェントの出力が次のエージェントに引き継がれます:

research agent → "Found 3 auth patterns in use"
    ↓
coding agent → "Implementing refresh token flow using pattern A"
    ↓
reviewing agent → "Verified implementation, found 1 issue"
    ↓
coding agent → "Fixed issue, ready for merge"

プロンプトを介してエージェント間でコンテキストを明示的に渡します。

再開可能なセッション

呼び出しをまたいで長時間実行される作業を継続します:

{
  "description": "Continue security analysis",
  "prompt": "Now examine session management",
  "subagent_type": "outfitter:reviewer",
  "resume": "agent-abc123"
}

エージェントは前回の実行から完全なコンテキストを保持します。

ユースケース:

• 複数のトピックにまたがる多段階のリサーチ
• コンテキストを再説明することなく反復的に改善
• 段階的な発見を伴う長いデバッグセッション

モデルの選択

特定のニーズに応じてモデルを上書きします:

{
  "subagent_type": "outfitter:analyst",
  "model": "haiku"  // Fast, cheap for exploration
}

• haiku: 高速な調査、単純なクエリ
• sonnet: バランスの取れた推論 (デフォルト)
• opus: 複雑な分析、微妙な判断

連携のルール

1. 単一の担当者: 各タスク段階は 1 つのロールが担当する
2. 明確な引き継ぎ: エージェント間で成果物を明示する
3. スキルの読み込み: エージェントは必要なスキルのみを読み込む
4. ユーザー設定を優先: デフォルトを適用する前に CLAUDE.md を確認する
5. エージェントは最小限: 順番に実行できるものを並列化しない

意思決定のフレームワーク

エージェントが実装の選択に直面したとき:

1. 既存のパターンを優先 — コードベースにすでにあるものに合わせる
2. シンプルさを優先 — 巧妙さは負債である; シンプルなものは保守可能である
3. 保守性を最適化 — 次の開発者 (またはエージェント) が理解できる必要がある
4. 後方互換性を考慮 — 破壊的変更には明示的な承認が必要である
5. トレードオフを記録 — 選択肢の間で選ぶときは、その理由を記録する

これらの原則はすべてのロールに適用されます。トレードオフが重大な場合、エージェントはオーケストレーターに判断を提起する必要があります。

コミュニケーションスタイル

オーケストレーターとエージェントは次のようにするべきです:

• 進捗を報告する — 各主要なステップで (沈黙しない)
• ブロッカーを即座に報告する — 解決できない問題で空回りしない
• 明確なサマリーを提供する — 委任された作業について (何が完了し、何が残っているか)
• ファイルパスと行番号を含める — コードを参照するとき

進捗のフォーマット:

░░░░░░░░░░ [1/5] research: Exploring auth patterns
▓▓▓▓░░░░░░ [2/5] coding: Implementing refresh token flow

エスカレーションすべきとき

• ブロックされた: エージェントが続行できない → リサーチロールへ回す
• 矛盾する調査結果: 複数のエージェントが意見を異にする → ユーザーに提起する
• スコープの拡大: タスクがロールの領域を超えて広がる → 再ルーティングする
• コンテキストの不足: 情報が不十分 → pathfinding スキルを備えたリサーチロールへ

Git 操作のポリシー

重要: サブエージェントは、並列で実行されているときは git 操作 (commit、push、ブランチ作成) を実行してはなりません (MUST NOT)。

git の状態を扱うのは オーケストレーター のみです。サブエージェントはコードをファイルシステムに書き込み、完了を報告します。

詳細なワークフローと復旧手順については、source-control プラグインを参照してください:

• source-control:multi-agent-vcs — オーケストレーター専用の完全なワークフローパターン
• source-control:graphite-stacks — Graphite 固有のコマンドと復旧

アンチパターン

• すべてのタスクですべてのエージェントを実行する (無駄)
• 「小さな変更」でレビューロールを省略する (リスク)
• デバッグスキルなしでコーディングロールがデバッグする (非効率)
• 依存関係のある並列エージェント (競合状態)
• 複雑な提案に異議を唱えない (過剰な設計)
• git 権限を持つ並列エージェント (スタックの破損)

クイックリファレンス

「X を構築したい」 → コーディングロール + TDD スキル

「この PR をレビューして」 → レビューロール + code-review

「なぜ壊れているのか？」 → デバッグロール + debugging

「このアプローチは過剰か？」 → チャレンジロール + simplify

「これが動作することを証明して」 → テストロール + scenarios

「コードベースは何をしているのか？」 → リサーチロール + codebase-recon

「本番環境にデプロイして」 → スペシャリストロール + ドメインスキル

「このワークフローを再利用可能にして」 → パターンロール + codify