nested-subagents

ネストされたサブエージェント

各子エージェントがさらに子エージェントを生成できるサブエージェントのツリーを、最大5階層まで生成します。目的は並列処理ではなく、コンテキスト管理です。各階層で新しいコンテキストウィンドウを使うため、深い作業によって最上位エージェントのコンテキスト予算が圧迫されません。

使用する場面

• 問題がネストされた複数のレイヤー（調査 → 展開 → 検証 → 統合）に分解でき、それぞれが親のコンテキストを汚染してしまう場合。
• 単一のエージェントのコンテキストウィンドウでは、すべての中間状態を保持できない場合。
• ツリーのリーフが異なる subagent_type で、それぞれに特化したプロンプトが必要な場合（例：一方のリーフに pii-detector、もう一方に tester）。

フラットな並列展開（1つのメッセージで Task × N）で十分な場合は、このスキルを使わないでください。ネストするとレイテンシーが増加します。

手順

1. コーディネーターを呼び出す — 最上位エージェントとして nested-coordinator を生成します。

   Task({
     subagent_type: "nested-coordinator",
     name: "root-coordinator",
     description: "Decompose and delegate <problem>",
     prompt: "<problem statement, with constraints and expected output shape>"
   })
   

2. コーディネーターが最初に分解する — Task を呼び出す前に、TodoWrite を使って生成ツリーを配置します。深い作業を承認する前にツリーを確認してください。

3. 子が子を生成する — 任意の nested-coordinator（または YAML フロントマターで tools: [..., Task] が宣言されている他のエージェント）は、Task を呼び出して次の階層を生成できます。リーフエージェント（tools リストに Task がないエージェント）は生成できません。

4. 各階層が要約を報告する — 子はトランスクリプト全体ではなく、約200トークンの構造化された要約を返します。親のコンテキストをクリーンに保つことが、この仕組みの要点です。

5. ツリー構造を保持する — post-task フックは、生成ごとに parent_agent_id と depth を AgentDB に書き込みます（ADR-147 P2）。実行後にクエリして、コストの割り当てやパターン学習に活用してください。

深度の上限

ソース	上限
Anthropic API	5階層（2026-06-09発表）
Ruflo のデフォルト（pre-task フック）	4階層 — 1階層分のガードバンド。claude-flow.config.json で設定可能
厳格モードの環境変数	CLAUDE_FLOW_STRICT_NESTING=true で Ruflo の上限を適用

上限に達すると、フックは型付きの NESTING_DEPTH_EXCEEDED エラーを返します。ペイロードには完全なチェーンが含まれるため、親は要約、引き継ぎ、中止のいずれかを判断できます。

メリット

• 階層ごとのコンテキスト分離 — 最上位のコーディネーターは内部のやり取りを参照せず、リーフの要約だけが親へ戻ります。
• 再要約なしで、より深く委任 — フラットな並列展開で強いられる「すべてを収めるためにレベル1で要約する」というアンチパターンを解消します。
• ツリー構造によるコストの割り当て — parent_agent_id の系譜により、エージェント単位の単純な集計ではなく、ツリーごとの支出を正確に把握できます。
• Ruflo の既存オーケストレーターに自然に対応 — ruflo-sparc:sparc-orchestrator（5フェーズ ≈ 5階層）、ruflo-goals:dossier-investigator（エンティティの再帰的な展開）、v3-queen-coordinator（階層型メッシュの最上位）。

アンチパターン（禁止事項）

• リーフエージェントに Task を渡す。 リーフはエージェントを生成してはいけません。代わりに、リーフの subagent_type をコーディネーターの直下に指定してください。
• Tier-1 codemod をコーディネーターでラップする。 codemod（hooks_codemod）は深度0の決定論的な変換です。生成ツリーの中に入れてはいけません。
• 「整理のため」にネストする。 先走って階層をネストすると、コンテキストを節約できないままレイテンシーとコストが増加します。1つのエージェントで作業できるなら、1つのエージェントを使ってください。
• 子からトランスクリプト全体を返す。 それではネストする目的そのものが失われます。子は構造化された要約を返してください。

関連項目

• エージェント：ruflo-agent:nested-coordinator — オーケストレーター
• ADR-147 — 設計上の根拠と4フェーズの段階的導入
• ADR-144 — 認可の伝播では、深度カウンターを AuthScope.delegationDepth として共有
• ADR-099 — dossier investigator（再帰的な並列調査）は、典型的な深い活用例です