nested-subagents

嵌套子代理（Nested Sub-Agents）

嵌套子代理用于生成一棵子代理树，其中每个子代理都可以继续生成子代理，最多 5 层。其动机是上下文管理，而不是并行：每一层都获得全新的上下文窗口，因此深层工作不会耗尽顶层代理的上下文预算。

何时使用

当问题可分解为嵌套层次（研究 → 展开 → 验证 → 综合），而其中每一层都会污染父级上下文时。

当单个代理的上下文窗口不足以容纳所有中间状态时。

当树的叶节点是不同的 subagent_type，需要各自的专用提示时（例如一个叶节点是 pii-detector，另一个是 tester）。

当扁平扇出（一条消息内 Task × N）已经足够时，应跳过此技能——嵌套会增加延迟。

步骤

调用协调器——将 nested-coordinator 作为你的顶层代理生成：

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

协调器先做分解——它在任何 Task 调用之前，通过 TodoWrite 规划出生成树。在批准深层工作前先检查这棵树。

子代理生成子代理——任何 nested-coordinator（或任何在其 YAML frontmatter 中声明 tools: [..., Task] 的代理）都可以自行调用 Task 生成下一层。叶代理（tools 列表中不含 Task）不能。

每一层报告摘要——子代理返回约 200 token 的结构化摘要，而不是完整记录。整个要点就是保持父级上下文干净。

树形被持久化——post-task 钩子在每次生成时把 parent_agent_id 和 depth 写入 AgentDB（ADR-147 P2）。运行后可查询以进行成本归因和模式学习。

深度预算

来源 | 限制

Anthropic API | 5 层（2026-06-09 公布）

Ruflo 默认（pre-task 钩子） | 4 层——预留一级保护带，可在 claude-flow.config.json 中配置

严格模式环境变量 | CLAUDE_FLOW_STRICT_NESTING=true 以强制 ruflo 上限

钩子在上限处返回类型化的 NESTING_DEPTH_EXCEEDED 错误，并在 payload 中携带完整链路，以便父级决定是摘要、交接还是中止。

优势

每层上下文隔离——顶层协调器从不会看到内部杂谈；叶节点摘要逐层向上回传。

无需重新摘要的更深委派——消除了扁平扇出所强制的“在第 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）是 depth-0 的确定性转换——绝不要把它们放进生成树里。

“为了整洁”而嵌套。一个过早的嵌套层会白白浪费延迟和成本，却不会节省上下文。如果一个代理能完成工作，就用一个代理。

从子代理返回完整记录。那会破坏嵌套的全部意义。子代理返回结构化摘要。

技能介绍