Subagent Fan-out
子代理扇出
Overview
当一个任务包含多个独立部分时，为每个部分生成一个子代理，而不是在主线程中逐一探索所有内容。每个子代理会返回一个简短、结构化的摘要；编排者只保留聚合结果，而不保留被探索的文件。这是大型任务中节省 token 收益最高的单一模式。
概述
When a task has several independent parts, spawn one subagent per part instead of exploring everything in the main thread. Each subagent returns a small, structured summary; the orchestrator only ever holds the aggregates, not the explored files. This is the single highest-leverage token-saving pattern for large tasks.
When to use
- A task touches multiple independent modules/directories/files.
- Several unrelated questions must be answered (e.g. "find X in service A, Y in service B, Z in service C").
- Broad codebase exploration where a single
Explorewould still return too much. - Independent refactors/fixes that don't share state.
何时使用
- 任务涉及多个相互独立的模块/目录/文件。
- 需要回答多个互不相关的问题（例如“在 A 服务中找 X、在 B 服务中找 Y、在 C 服务中找 Z”）。
- 大范围的代码库探索，即便单次
Explore仍会返回过多内容。 - 不共享状态的独立重构/修复。
Do not use it for tightly coupled work that needs shared, evolving context — a single agent with full context is then cheaper.
不要将其用于需要共享、持续演进上下文的紧耦合工作——此时使用具备完整上下文的单个代理反而更省。
Workflow
- Decompose. Split the task into independent subtasks with no shared mutable state. Each must be self-contained.
- Brief. Write one self-contained brief per subtask (see template). Include: goal, where to look, what to return, format, length cap, and "do not paste full file contents."
- Route. Use
model:"lite"for search/classification;defaultonly if synthesis is needed inside the subagent. Setmax_turnsto bound cost. - Run.
run_in_background:truefor independent agents and continue other work; or issue them in one message to run in parallel. - Aggregate. Collect the structured returns; produce one synthesis. Re-read a specific file only if a subagent's pointer is insufficient.
工作流
- 分解。 将任务拆分为无共享可变状态的独立子任务。每个子任务必须自包含。
- 编写简报。 为每个子任务编写一份自包含简报（见模板）。包含：目标、查找位置、返回内容、格式、长度上限，以及“不要粘贴完整文件内容”。
- 路由。 搜索/分类使用
model:"lite"；仅当子代理内部需要综合推理时才用default。设置max_turns以控制成本。 - 运行。 对独立代理使用
run_in_background:true并继续其他工作；或在一个消息中下发以并行运行。 - 聚合。 收集结构化返回结果，产出一份综合结论。仅当子代理的指针不足以说明问题时，才重新读取特定文件。
Brief template
You are investigating <scope>. Do NOT modify anything.
Goal: <what to find/decide>.
Look in: <paths / glob patterns>.
Return (under <N> words, JSON or tight bullets):
- files: list of relevant paths with line numbers
- symbols: key function/class names
- answer: the decision-relevant conclusion
Do NOT paste full file contents; cite paths only.
A deterministic generator exists: scripts/make_briefs.py turns a task + subtask list into N ready-to-send briefs (to files or stdout).
存在一个确定性生成器：scripts/make_briefs.py 可将“任务 + 子任务列表”转换为 N 份可直接下发的简报（写入文件或输出到 stdout）。
Cost controls
- Always set
max_turns(e.g. 8–15) so a stuck subagent can't loop. - Prefer
model:"lite"for fan-out; reservereasoning/defaultfor genuinely hard subtasks. - Cap each return length in the brief; aggregates stay small.
成本控制
- 始终设置
max_turns（如 8–15），避免卡住的子代理陷入循环。 - 扇出优先使用
model:"lite"；仅在子任务确实困难时才使用reasoning/default。 - 在简报中限制每次返回的长度，使聚合结果保持精简。
Edge cases
- Coupled subtasks: if part B needs part A's live output, run A first, then B — don't pretend they're independent.
- Over-splitting: more than ~6 subagents adds coordination overhead; batch related small items into one brief.
- Subagent blind spots: they lack main-context continuity; brief fully and request exact return shape.
边界情况
- 耦合子任务： 若 B 部分需要 A 部分的实时输出，先运行 A，再运行 B——不要假装它们相互独立。
- 过度拆分： 超过约 6 个子代理会增加协调开销；将相关的小项合并到一份简报中。
- 子代理盲区： 它们缺少主上下文的连续性；请编写完整简报并明确要求精确的返回格式。
Resources
scripts/make_briefs.py— generate N self-contained briefs from a task + subtask list. Execute, don't load.references/briefs.md— more brief templates and aggregation patterns.
资源
scripts/make_briefs.py—— 从“任务 + 子任务列表”生成 N 份自包含简报。执行它，而非加载它。references/briefs.md—— 更多简报模板与聚合模式。references/error-handling.md—— 本技能脚本（make_briefs.py）的参数 / 路径 / 写权限报错指引。
