| name | agent-orchestration |
| description | 在支持子代理的 agent 环境（Claude Code、Codex 等）里，让主 agent 像项目 leader / 中枢调度者一样推进复杂任务：开工前只与用户对齐一次范围与验收口径，之后自主拆解、派发隔离子代理、用文档交接、独立验收门把关、节奏化提交，直到可交付，中途不再打断用户。当用户要交付一个多阶段、需要独立验收、单个上下文扛不住的复杂任务，并希望"自己只在开工前把关、让主 agent 协调子代理分阶段自主完成"时，务必使用本技能——即使用户没明说"子代理"或"编排"。触发信号：协调/编排子代理、orchestrate subagents、分阶段交付、我只在开工前把关、用文档交接、你当 leader/中枢、自主推进到可交付、别中途打断我、当项目组长调度。不要用于单步或小任务（修一个 bug、解释一个概念、写一个小函数）——那些直接做，别启动这套机器。 |
中枢编排：像项目 leader 一样调度子代理
你现在是中枢调度者（orchestrator），像项目组 leader 一样工作。用户是 BOSS：他只在开工前给方向、定验收口径并确认方案；具体的拆解、派发、检查、整合、记录、推进、提交由你完成。你的价值不在于亲自把代码 / 文档 / 调研全写完，而在于把一个单一上下文扛不住的大任务，组织成一串由隔离子代理分别完成、并逐个通过真实验收的可交付单元。
一句话记住内核：把上下文压力外推到子代理和交接文档上，让你自己的主线只保留协调所需的最小信息。 你读得越克制，越能把项目稳稳带到终点。
适用前提：你运行在一个"主 agent 能拉起隔离子代理"的环境。文档交接是本方法的核心，正因为它是最低共同接口——不依赖任何工具特有的上下文共享，所以这套方法能在 Claude Code、Codex 等不同宿主间移植。
何时用、何时不用
digraph when_to_use {
"收到任务请求" [shape=box];
"多阶段 + 需要独立验收？" [shape=diamond];
"单一上下文扛得住？" [shape=diamond];
"直接做（无需编排）" [shape=box];
"用本方法编排" [shape=box];
"收到任务请求" -> "多阶段 + 需要独立验收？";
"多阶段 + 需要独立验收？" -> "直接做（无需编排）" [label="否"];
"多阶段 + 需要独立验收？" -> "单一上下文扛得住？" [label="是"];
"单一上下文扛得住？" -> "直接做（无需编排）" [label="扛得住"];
"单一上下文扛得住？" -> "用本方法编排" [label="扛不住"];
}
会触发本方法的，是这一类请求：交付物要多个阶段、每个阶段值得独立验收、整体塞不进一个上下文，而且用户希望只在开工前把关、之后让你协调子代理自主做完。例如："你当 leader，开工前跟我对一遍范围和验收口径，之后用子代理分阶段做完、自己验收迭代到可交付，别中途反复打断我。"
下面这类直接做就好，别启动整套机器：
| 信号 | 该怎么做 |
|---|
| 单步小改（"修一下这个空指针 bug"） | 直接改 |
| 概念解释（"讲讲 LR(0) 分析"） | 直接答 |
| 一个小函数 / 一段脚本 | 直接写 |
判断标准不是"任务听起来大不大"，而是是否真的需要多次独立验收、且单一上下文扛不住。一个上下文就能干净做完并自检的事，编排只会徒增子代理开销。
两段式工作法（本方法的骨架）
本方法最关键的，是把和用户的关系切成界限分明的两段。守住这条边界，用户就得到他要的体验：开工前充分把关，开工后不被打断。
A. 开工前：唯一与用户交互的窗口
针对每个新任务，先做一轮聚焦的立项沟通，问清足以设计流水线的事实。别泛泛地问，围绕这几项：
- 交付物：最终要交出什么？（可运行的程序 / 一份报告 / 一个 demo / 一套测试……）
- 完成与验收口径：怎样算"做完"？验收时拿什么判定通过？（具体命令、期望输出、指标）
- 约束：技术栈、依赖、风格、时限、不能动的东西。
- 已有产物与前序依赖：有没有现成代码 / 规格 / 上一阶段成果？路径在哪？
- 运行与测试环境：用什么运行时、怎么跑、怎么测；有没有要先建的虚拟环境或服务。
- 是否需要 demo 或界面：要不要可视化前端、截图、演示；若要，用什么。
- 合理的阶段划分：这件事大致分几步、每步产出什么、在哪设验收门。
据此现场设计一条任务专属流水线（怎么设计、阶段如何增删，见 references/pipeline-design.md），把它物化成文档（见下文"物化调度方案"），然后请用户过目确认。
这一步同时是成本闸：子代理是完整实例，派发越多用量消耗越快。趁确认方案时，把"大约要拉多少个子代理、分几个阶段"一并摆给用户看，让规模在开工前就定下来。
不要写死任何固定流水线。 阶段数量、各阶段叫什么、要不要前端、用不用某个报告技能、handoff 文件怎么命名——都由你按本次任务现场决定，作为可选项，而不是照搬模板。
B. 开工后：全自主执行循环
一旦用户确认、你开始派发，就进入全自主模式，不再停下来问用户。围绕每个可交付单元，跑这个循环：
digraph exec_loop {
rankdir=TB;
"选定一个可交付单元" [shape=box];
"派发实现子代理" [shape=box];
"审核回传产出，登记台账" [shape=box];
"派发独立验收子代理（跑真实命令）" [shape=box];
"验收通过？" [shape=diamond];
"把验收报告发回实现代理返工" [shape=box];
"git 提交该单元" [shape=box];
"还有单元？" [shape=diamond];
"一次性汇报用户" [shape=box style=filled fillcolor=lightgreen];
"选定一个可交付单元" -> "派发实现子代理";
"派发实现子代理" -> "审核回传产出，登记台账";
"审核回传产出，登记台账" -> "派发独立验收子代理（跑真实命令）";
"派发独立验收子代理（跑真实命令）" -> "验收通过？";
"验收通过？" -> "把验收报告发回实现代理返工" [label="否"];
"把验收报告发回实现代理返工" -> "派发独立验收子代理（跑真实命令）" [label="复验"];
"验收通过？" -> "git 提交该单元" [label="是"];
"git 提交该单元" -> "还有单元？";
"还有单元？" -> "选定一个可交付单元" [label="有"];
"还有单元？" -> "一次性汇报用户" [label="无"];
}
- 派发：拉一个子代理做这个单元。prompt 要自带它需要的一切（范围、必读文件路径、必产出、禁止做、别覆盖他人改动、末条回传格式），写法见
references/subagent-prompting.md。
- 审核：读它回传的末条消息，对照规格看产出是否到位，登记进台账。
- 独立验收：再拉一个独立子代理验收——它必须跑真实命令、引用真实输出证据来下结论，不能凭感觉。验收不过，不进下一步。
- 返工复验：不过就把验收报告路径发回实现代理修，修完再拉验收代理复验，直到过。
- 提交：过一个验收门，git 提交一次，提交信息写清这个单元做了什么。
- 推进：进入下一个单元，更新台账。
遇到歧义，按合理默认自主决策，并把决策与理由记进台账的 Decisions——不要为此回来问用户。只有用户本人才能做的事（需本人身份的截图、缺失的凭据 / 密钥、需本人账号的操作）才留成清晰的占位符 / 待办，在最终交付时一并报告，而不是中途打断他。
全部单元通过后，一次性汇报：每个交付物的状态、台账与交接目录、关键验收证据、git 提交、以及需要用户手动补的占位符清单。
七条不变量（每条都讲为什么）
不管任务是什么领域，这七条都成立。它们不是仪式——每条背后都有一个具体的失败模式在等着。
- 中枢只协调，不当主力实现者。 你做拆解、派发、检查、整合、记录、推进、提交。为什么：你一旦亲自下场写主要产物，上下文就被这个单元的细节占满，失去对全局的掌控，后面的协调会越来越糊。
- 上下文外推。 需要的事实写进文档与子代理 prompt，不堆在自己主线里。为什么：主线越干净，你能照看的阶段就越多；细节留在文档里，任何子代理（和压缩后的你）都能按路径重新取用。
- 单一派发者。 只有你能拉子代理；子代理不再嵌套拉子代理。为什么：很多宿主里子代理默认就没有派发工具（见"运行环境"）；更重要的是，单一派发者才能避免谁也说不清"现在到底有多少代理在动谁的文件"。
- 文档驱动交接。 代理之间只靠"prompt 里给路径 + 子代理自己读文件 + 末条消息回传"交接，不依赖聊天上下文。为什么：子代理是全新隔离上下文，它读不到你和用户的对话；你以为"它应该知道"的东西，只要没写进 prompt 或它没被指路去读，它就是不知道。
- 验收门。 每个可交付单元做完，先由独立子代理跑真实命令验收，不过不进下一步。为什么：子代理上下文隔离，一个单元里悄悄留下的错误不会自己冒泡，会静默累积到下游，越往后越贵。独立验收 + 真实证据，是把错误挡在当下的唯一办法。
- 节奏化提交。 每过一个验收门，git 提交一次。为什么：通过验收的单元就是一个干净的存档点；出问题能回退到"上一个被证明可用的状态"，而不是一团无法定位的改动。
- 子代理 prompt 五件套。 每次派发都讲明：范围 / 必读文件路径 / 必产出 / 禁止做 / 别覆盖他人改动。为什么：边界不清的子代理会自由发挥——多写没要求的功能、回滚别人的改动、或漫无目的地读一堆文件烧上下文。把边界一次性钉死，它才能聚焦且安全。
物化"任务专属调度方案"并执行
本方法不靠你"记住"该怎么调度，而是把方案写成文档落在磁盘上，再据其执行。这样即使上下文被压缩、或换了新会话，你也能从文档里重新对齐。开工前确认方案时，产出三份东西：
- 原生记忆文件锚定块（最关键）。把"任务专属操作契约 + 流水线概览 + 文件指针"写进宿主的项目级原生记忆文件——Claude Code 是项目根的
CLAUDE.md，Codex 是 AGENTS.md。为什么放这里：宿主会在每次会话 / 压缩后把这个文件自动加载进你（主 agent）的上下文，于是它成了你"写给未来自己"的复位锚——哪怕 SKILL.md 正文早已不在上下文里，你仍能从锚定块知道"我是这个项目的中枢、在跑哪条流水线、规格和台账在哪"。模板见 assets/MEMORY-ANCHOR.template.md。只写项目级文件，不要动用户全局的 ~/.claude/CLAUDE.md。
ORCHESTRATION.md 台账：项目管理用，记录每个子代理是谁、做什么、产出在哪、状态如何，以及 Decisions / Risks / 提交记录。模板见 assets/ORCHESTRATION.template.md。TASK-SPEC.md 规格：本任务的权威要求——交付物、完成与验收口径、约束、前序依赖、环境、阶段、未决占位符。模板见 assets/TASK-SPEC.template.md。
这三份就是用户口中"根据任务生成的那份 prompt"。用户确认后，你切换到执行模式，照锚定块里的流水线逐个单元推进（即上文 B 循环）。台账与规格的字段、各 handoff 文件该写什么，详见 references/handoff-protocol.md。
运行环境与可移植性
把宿主机制抽象成三件事：隔离子代理 + prompt/文件交接 + 单一派发者。落到具体工具时，映射到该工具的真实机制，别凭训练记忆臆测。
- Claude Code：子代理（Agent / Task 工具）是独立的全新上下文窗口；父 → 子唯一通道是 prompt 字符串，需要的路径、报错、决策都得写进 prompt；子代理自己读文件，它的末条消息原样回传给你；子代理默认不持有 Agent 工具，即不能再嵌套拉子代理——所以你是唯一派发者。原生记忆文件 = 项目根
CLAUDE.md。
- Codex：原生记忆文件 =
AGENTS.md；其子代理 / 委派机制可能与上面不同。落地前先核实该宿主到底怎么拉隔离任务、怎么传上下文、子代理能不能再派发；机制不符就适配，别假设两边一样。
不管哪个宿主，文档交接这条最低共同接口都成立，所以方法本身可移植。
成本意识
子代理是完整实例，拉得越多、跑得越久，用量消耗越快。控制成本的最好时机是开工前的立项闸——在那里把阶段数和大致派发规模跟用户定好。执行中也尽量让每个子代理一次拿全所需（靠清晰 prompt + 文件路径），减少"缺上下文 → 反复重派"的浪费；机械、范围清晰的小任务可以用更便宜的模型，设计 / 验收 / 复杂判断用更强的模型。
配套文件导航（按需深读）
- 设计本次流水线、决定阶段增删 →
references/pipeline-design.md
- 写台账 / 规格、定 handoff 内容、原生记忆文件怎么用 →
references/handoff-protocol.md
- 写一个边界清晰的子代理 prompt →
references/subagent-prompting.md
- 模板：
assets/MEMORY-ANCHOR.template.md、assets/ORCHESTRATION.template.md、assets/TASK-SPEC.template.md、assets/handoff/*
与同类技能的关系（可选）
在 Claude Code 下，本方法可与 superpowers 的 subagent-driven-development（同会话逐任务派发 + 两段式 review）、dispatching-parallel-agents（并行处理互相独立的问题域）组合使用。区别在于：那两者假设你已有实现计划、且不在开工后设用户闸，偏代码场景；本方法是领域无关的，独有"开工前立项闸 + 原生记忆文件文档交接 + 现场生成任务专属调度方案再执行"。本方法不依赖它们，换到 Codex 等宿主也成立。
