agent-orchestration

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 提交、以及需要用户手动补的占位符清单。

七条不变量（每条都讲为什么）

不管任务是什么领域，这七条都成立。它们不是仪式——每条背后都有一个具体的失败模式在等着。

1. 中枢只协调，不当主力实现者。 你做拆解、派发、检查、整合、记录、推进、提交。为什么：你一旦亲自下场写主要产物，上下文就被这个单元的细节占满，失去对全局的掌控，后面的协调会越来越糊。
2. 上下文外推。 需要的事实写进文档与子代理 prompt，不堆在自己主线里。为什么：主线越干净，你能照看的阶段就越多；细节留在文档里，任何子代理（和压缩后的你）都能按路径重新取用。
3. 单一派发者。 只有你能拉子代理；子代理不再嵌套拉子代理。为什么：很多宿主里子代理默认就没有派发工具（见"运行环境"）；更重要的是，单一派发者才能避免谁也说不清"现在到底有多少代理在动谁的文件"。
4. 文档驱动交接。 代理之间只靠"prompt 里给路径 + 子代理自己读文件 + 末条消息回传"交接，不依赖聊天上下文。为什么：子代理是全新隔离上下文，它读不到你和用户的对话；你以为"它应该知道"的东西，只要没写进 prompt 或它没被指路去读，它就是不知道。
5. 验收门。 每个可交付单元做完，先由独立子代理跑真实命令验收，不过不进下一步。为什么：子代理上下文隔离，一个单元里悄悄留下的错误不会自己冒泡，会静默累积到下游，越往后越贵。独立验收 + 真实证据，是把错误挡在当下的唯一办法。
6. 节奏化提交。 每过一个验收门，git 提交一次。为什么：通过验收的单元就是一个干净的存档点；出问题能回退到"上一个被证明可用的状态"，而不是一团无法定位的改动。
7. 子代理 prompt 五件套。 每次派发都讲明：范围 / 必读文件路径 / 必产出 / 禁止做 / 别覆盖他人改动。为什么：边界不清的子代理会自由发挥——多写没要求的功能、回滚别人的改动、或漫无目的地读一堆文件烧上下文。把边界一次性钉死，它才能聚焦且安全。

物化"任务专属调度方案"并执行

本方法不靠你"记住"该怎么调度，而是把方案写成文档落在磁盘上，再据其执行。这样即使上下文被压缩、或换了新会话，你也能从文档里重新对齐。开工前确认方案时，产出三份东西：

1. 原生记忆文件锚定块（最关键）。把"任务专属操作契约 + 流水线概览 + 文件指针"写进宿主的项目级原生记忆文件——Claude Code 是项目根的 CLAUDE.md，Codex 是 AGENTS.md。为什么放这里：宿主会在每次会话 / 压缩后把这个文件自动加载进你（主 agent）的上下文，于是它成了你"写给未来自己"的复位锚——哪怕 SKILL.md 正文早已不在上下文里，你仍能从锚定块知道"我是这个项目的中枢、在跑哪条流水线、规格和台账在哪"。模板见 assets/MEMORY-ANCHOR.template.md。只写项目级文件，不要动用户全局的 ~/.claude/CLAUDE.md。
2. ORCHESTRATION.md 台账：项目管理用，记录每个子代理是谁、做什么、产出在哪、状态如何，以及 Decisions / Risks / 提交记录。模板见 assets/ORCHESTRATION.template.md。
3. 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 等宿主也成立。