# Complex Task > 长程/复杂任务编排工作指导。接收复杂任务后，依次完成验收标准确认、计划拆分与自审、项目文件初始化、子任务文档创建、执行者-评估者 subagent 并行迭代、主 agent 巡检协调、聚合与整体评估，直至满足验收标准后交付。 - Skill: `teamwiseflow/complex-task` (Agent Skill) - Install (CLI): `npx skillmds@latest add teamwiseflow/complex-task` - Raw SKILL.md: https://api.skillmd.com/api/skills/teamwiseflow/complex-task/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: teamwiseflow (https://skillmd.com/u/teamwiseflow) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/teamwiseflow/complex-task --- # Complex Task — 复杂任务执行指导 **触发条件**：任务涉及多个交付阶段、需要协调多个 crew、或估计完成周期超过单次对话的长程任务。 **适用领域**：深度调研、自媒体内容生产、视频生成、故障排查与根因分析、多维度数据处理、配置新的对内/外 crew、开发新的技能等。 ## 核心原则 - 1. 主 agent 只充当 planner 和 project manager，负责与用户确认、治理流程、维护文档、推动执行，不直接承担已拆分子任务的具体生产工作。 - 2. agent 与 subagent 的协作，不应主要依靠对话，而应主要依靠**交付物、任务文档、验收文档、结构化约束和明确 verdict**。 - 3. 计划确定后，所有子任务必须通过 `sessions_spawn` 交给 subagent；主 agent 不得代做任何子任务。 - 4. 每个子任务都必须有一对 subagent：执行者 + 评估者。最终聚合后还必须有一个单独的整体评估 subagent。 - 5. 子任务是否可接受，只能由对应 evaluator subagent 给出 verdict。不能因为“看到了新产物”就自行把状态改成完成。 - 6. 执行 subagent、评估 subagent、整体评估 subagent，都应优先从 `allowAgents` 白名单内选择最合适的 crew；如果 `allowAgents` 为空或没有合适的 crew，则 spawn 给自己。 ## 术语 - **主 agent**：和用户直接交互，负责确认、编排、巡检、变更管理和最终交付。 - **执行者**：某个子任务的 executor subagent，负责依据 `task.md` 产出交付物。 - **评估者**：某个子任务的 evaluator subagent，负责依据 `acceptance.md` 判断该子任务是否可以交付。 - **GAN 模式**：执行者持续产出或修正交付物，评估者持续指出与验收标准之间的缺口；双方围绕产物和约束循环，直到评估者明确给出可交付 verdict。 --- ## Phase 1 — 理解意图，制定验收标准 仔细阅读用户描述，提炼： - **核心目标**：任务要解决什么问题？ - **交付范围**：最终产物是什么形式？ - **明确约束**：时间、资源、风格、平台、字数、数据范围、技术边界等。 - **隐含预期**：用户没明说但明显存在的质量底线。 基于以上分析，起草验收标准清单： ```text 验收标准： AC-1: <可观测、可验证的具体标准> AC-2: ... AC-N: ... ``` 要求： - 每条 AC 必须可观测、可验证。 - 禁止使用“质量好”“尽量完整”“适当优化”等模糊表述。 - 能转成明确指标、检查清单或测试脚本时，优先转成这些形式。 --- ## Phase 2 — 与用户确认验收标准（L2） 向用户呈现： ```text 任务目标：<一句话概括> 验收标准： AC-1: ... AC-2: ... ... 请确认以上验收标准，或告诉我需要调整的部分。 ``` 等待用户明确确认。用户有修改时，更新标准后重新确认。**未经确认，不得进入 Phase 3。** --- ## Phase 3 — 制定执行计划，并用 subagent 自审拆分质量 ### 3-1 任务拆解 将任务拆解为若干**子任务**。每个子任务必须可独立执行、可独立评估、可独立返工。每个子任务至少包含： ```text 子任务 T-N：<子任务名称> 目标：<该子任务解决什么问题> 交付物：<必须产出的具体内容，可量化> 约束：<执行限制、事实边界、质量要求、来源范围等> 验收重点：<本子任务最关键的检查点> 执行者指派： 评估者指派： 模型层级： 依赖：<无 / 依赖 T-X 完成后启动> 执行方式：<并行 / 串行> 返工策略：<被打回后如何继续> ``` 规则： - 只能指派 self 或当前 crew `allowAgents` 白名单内的 crew。 - 不得指派 external crew。 - 子任务之间的接口应尽量落实为文件路径、字段结构、输出格式或检查点。 - 同一个子任务内不要同时混入“探索、决策、执行、整合”四类责任。 ### 3-2 计划自审：必须创建 planning reviewer subagent 在计划落地实施前，必须创建一个独立的 planning reviewer subagent，与主 agent 以 **GAN 模式**完成计划定稿。 做法： 1. 主 agent 先形成一版计划草案。 2. spawn 一个 planning reviewer subagent，向其提供：任务目标、已确认 AC、当前子任务拆分草案、依赖关系、指派方案、返工策略。 3. planning reviewer 只做结构化批评，不参与执行。它必须指出： - 哪些子任务粒度过粗或过细 - 哪些依赖关系不合理 - 哪些交付物与验收重点不匹配 - 哪些子任务边界不清或容易重复劳动 - 哪些约束缺失，导致后续执行者和评估者无法协作 4. 主 agent 根据批评修订计划；如 reviewer 仍指出问题，则继续迭代，直到收敛出可执行计划。 要求： - 计划自审阶段的沟通必须围绕计划文本和约束本身，而不是开放式讨论。 - 未通过计划自审，不得进入 Phase 4 的执行准备。 ### 3-3 Anti-pattern 检查 | # | 反模式 | 检查点 | |---|--------|--------| | A1 | 子任务粒度过粗 | 单子任务是否仍承载多个目标、估计耗时过长？ | | A2 | 依赖关系不清 | 下游是否明确依赖哪个文件、产物或 verdict？ | | A3 | 过度串行 | 无真实依赖的子任务是否错误地排成串行？ | | A4 | 交付物与验收脱节 | 执行者产物是否无法支撑评估者判定？ | | A5 | 文档无法独立执行 | 如果只给 `task.md` / `acceptance.md`，子 agent 是否仍能工作？ | | A6 | 指派对外 crew | 是否有子任务错误地指派了 external crew？ | | A7 | 返工路径缺失 | evaluator 打回后，是否没有明确返工入口？ | | A8 | 过度依赖对话 | 关键信息是否没有提前落到文档与约束中？ | --- ## Phase 4 — 初始化项目文件夹与子任务文档 这一步不必与用户确认，但必须经过 planning reviewer subagent 的审查通过。 当 planning reviewer subagent 认为技术方案和计划都已经足够清晰、可执行时，主 agent 应立即按计划创建项目文件夹： `./projects/-/` ```text ./projects// PROJECT.md tasks.json progress.md subtasks/ T-1/ task.md acceptance.md artifacts/ T-2/ task.md acceptance.md artifacts/ final/ ``` ### 4-1 PROJECT.md ```markdown # Project: <任务名称> **ID**: - **Created**: <日期时间> **Status**: planned ## 目标 <一句话概括任务目标> ## 验收标准 - AC-1: ... - AC-2: ... ## 执行总览 - 子任务数量：N - 并行组：... - 关键依赖：... ``` ### 4-2 tasks.json ```json { "project_id": "-", "created_at": "", "status": "planned", "subtasks": [ { "id": "T-1", "name": "<子任务名称>", "executor_assignee": "", "evaluator_assignee": "", "dependencies": [], "status": "pending", "executor_status": "pending", "evaluator_status": "pending", "verdict": "unknown", "artifact_dir": "./projects//subtasks/T-1/artifacts/", "result_summary": "" } ] } ``` 建议状态流转： - 顶层 `status`：`planned` → `executing` → `aggregating` → `overall_review` → `done` - 子任务 `status`：`pending` → `running` → `awaiting_verdict` → `accepted` | `needs_rework` | `blocked` - `verdict` 只能由 evaluator 或 overall evaluator 的正式结论驱动。 ### 4-3 progress.md ```markdown # Progress Log — <任务名称> ## [<时间戳>] Phase 4: 项目初始化完成 - 项目目录：./projects// - 子任务数量：N 个 - 已创建子任务文档：T-1 ... T-N ``` ### 4-4 为每个子任务创建两个文档 必须在每个子任务目录下创建两个 Markdown： - `task.md`：详细描述子任务内容、目标、上下文、依赖、产物位置、执行约束 - `acceptance.md`：详细描述子任务验收标准、检查方法、拒收条件、评估输出格式 建议模板： ```markdown # task.md ## 目标 ## 输入与上下文 ## 交付物 - 路径：./projects//subtasks/T-N/artifacts/ - 必须包含：... ## 约束 ## 禁止事项 ``` ```markdown # acceptance.md ## 必须满足 - AC-TN-1: ... - AC-TN-2: ... ## 拒收条件 ## 评估输出格式 - verdict: accepted | needs_rework | blocked - findings: - <编号化问题清单> - evidence: - <对应文件 / 事实 / 缺口> ``` --- ## Phase 5 — 执行：每个子任务都以“执行者-评估者”双 subagent 并行推进 ### 5-1 spawn 规范 每个子任务都必须创建两个 subagent： - executor subagent，负责依据 `task.md` 执行 - evaluator subagent，负责依据 `acceptance.md` 评估 关键约束： - 执行者和评估者的协作，应以 `task.md`、`acceptance.md`、`artifacts/` 内产物和结构化 verdict 为中心。 - 允许最小必要澄清，但不得把“靠聊明白需求”当作主要协作方式。 - 如果评估者没有明确给出 `accepted`，该子任务就不能进入可交付状态。 ### 5-2 Executor prompt 要求 executor 至少应收到： - `task.md` 路径 - `acceptance.md` 路径 - 产物目录路径 - 明确要求：优先通过更新交付物解决问题，而不是长篇解释 建议 executor 输出格式： ```text 执行回合： 子任务：T-N 本轮修改产物： - <文件路径> 本轮结果摘要： - <1-3 条> 需评估项： - <请 evaluator 针对哪些标准检查> ``` ### 5-3 Evaluator prompt 要求 evaluator 至少应收到： - `acceptance.md` 路径 - `task.md` 路径 - 产物目录路径 - 明确要求：只根据产物和标准做判断，不为执行者脑补完成度 建议 evaluator 输出格式： ```text 评估回合： 子任务：T-N verdict: accepted | needs_rework | blocked findings: 1. <问题或通过项> 2. ... evidence: - <文件路径 / 事实依据 / 缺失项> next_action: - <执行者下一轮应修改什么> ``` ### 5-4 GAN 式循环 每个子任务都按以下循环推进，直到 evaluator 给出 `accepted`： 1. 执行者依据 `task.md` 产出或修改交付物。 2. 评估者依据 `acceptance.md` 对产物做批判性检查。 3. 如果 verdict 为 `needs_rework`，执行者只针对 findings 返工，不重做无关部分。 4. 如果 verdict 为 `blocked`，主 agent 介入，澄清事实、修正文档或向用户确认。 5. 只有当 verdict 为 `accepted` 时，主 agent 才能把该子任务状态写为 `accepted`。 ### 5-5 巡检：主 agent 必须持续跟进，但不代替评估 Phase 5 的巡检仍然是主 agent 的职责，至少包括两类工作。 **一类：推进卡住的 subagent** - 如果任何执行者或评估者明显卡住了，例如长时间无响应、上游模型挂起、上下文中断，应主动提示简短指令，例如“继续”。 - 巡检的目标是恢复执行，不是替子 agent 完成任务。 **二类：处理问题与偏差** - 如果执行者或评估者发现 `task.md` 或 `acceptance.md` 与事实不符，应向主 agent 提问。 - 主 agent 能判断的，直接答复并同步更新文档。 - 主 agent 拿不准的，必须反馈用户；待用户确认后，及时更新相应文档，再回复相关 subagent。 - 文档一旦更新，必须通知受影响的执行者和评估者，避免双方继续基于旧约束工作。 ### 5-6 状态更新纪律 主 agent 不得： - 因为 `artifacts/` 里出现新文件，就直接把子任务标记为完成。 - 因为执行者自称“已经好了”，就跳过 evaluator verdict。 - 因为主 agent 自己觉得“看起来差不多”，就代替 evaluator 做接受判定。 只有以下动作允许更新子任务状态： - spawn 后，可改为 `running` - 执行者提交产物待审时，可改为 `awaiting_verdict` - evaluator 明确判定通过时，可改为 `accepted` - evaluator 明确判定返工时，可改为 `needs_rework` - 明确存在阻塞且需主 agent 介入时，可改为 `blocked` 巡检记录建议追加到 `progress.md`： ```markdown ## [<时间戳>] 巡检 - T-1: evaluator 判定 needs_rework，已要求执行者继续 - T-2: evaluator 卡住，已发送“继续” - T-3: task.md 与事实冲突，已向用户确认并更新文档 ``` --- ## Phase 6 — 聚合结果 所有子任务都获得对应 evaluator 的 `accepted` verdict 后，主 agent 才能进入聚合阶段。 聚合时： 1. 检查 `tasks.json`，确认所有相关子任务 `status = accepted` 2. 读取各子任务产物，整合为统一最终成果 3. 将项目顶层状态更新为 `aggregating` 4. 在 `./projects//final/` 下生成聚合产物 5. 在 `progress.md` 追加记录 ```markdown ## [<时间戳>] Phase 6: 结果聚合完成 - 已接受子任务：X / N - 聚合产物：./projects//final/ ``` **注意**：在 Phase 6 完成前，不必创建整体评估 subagent。此时各子任务的可接受性，已经由各自 evaluator 负责。 --- ## Phase 7 — 整体评估与返工闭环 Phase 6 聚合完成后，必须再 spawn 一个**独立的 overall evaluator subagent**，专门评估最终整合结果。 它至少应读取： - `PROJECT.md` - 最终成果文件 - 全局 AC - 必要时读取关键子任务的 `acceptance.md` 与产物摘要 其职责： - 判断最终整合结果是否真正满足全局 AC - 识别是“已有子任务未做到位”，还是“需要新增子任务” - 输出结构化 verdict，而不是泛泛而谈 建议输出格式： ```text 整体评估： verdict: accepted | needs_rework findings: 1. <全局缺口> 2. ... impacted_subtasks: - - <需要新增 T-5> rationale: - <为何当前聚合结果仍不满足全局 AC> ``` ### 7-1 若整体评估通过 如果 overall evaluator 明确给出 `accepted`，进入 Phase 8。 ### 7-2 若整体评估未通过 如果 overall evaluator 给出 `needs_rework`，主 agent 必须基于 findings 组织返工： - 如果是已有子任务的缺口：更新对应 `task.md` 或 `acceptance.md` - 如果是新增范围：创建新的子任务目录、`task.md`、`acceptance.md` - 为受影响子任务重新创建或重启执行者与评估者 - 返回 Phase 5 执行，再经过 Phase 6 聚合，最后重新进入 Phase 7 这个循环应持续，直到 overall evaluator 认为可以交付。 如果返工轮次明显增多，主 agent 应主动向用户汇报风险、差距和拟调整方案；但不能跳过 overall evaluator 的最终判定。 --- ## Phase 8 — 交付 当且仅当 overall evaluator 明确接受后： 1. 将 `tasks.json` 顶层 `status` 更新为 `done` 2. 在 `progress.md` 追加最终记录 ```markdown ## [<时间戳>] Phase 8: 任务完成 - 整体评估：accepted - 最终产物：./projects//final/ ``` 向用户交付： ```text 任务完成 项目目录：./projects// 最终产物： <路径 / 摘要> 验收确认： AC-1: ✅ ... AC-2: ✅ ... 整体评估： accepted ``` 交付后执行常规 closeout。 --- ## Anti-patterns — 常见失败模式 | # | 反模式 | 后果 | 应对 | |---|--------|------|------| | P1 | 子任务粒度过粗 | 单个执行者长期失控或难以评估 | 每个子任务只负责一个清晰目标 | | P2 | 过度依赖对话 | 需求漂移、理解不一致、难追责 | 关键约束必须落到 `task.md` / `acceptance.md` | | P3 | 执行者无 evaluator 配对 | 无法形成独立验收闭环 | 每个子任务必须成对 spawn | | P4 | 见产物就改状态 | 误把“有文件”当“可交付” | 只有 evaluator verdict 才能决定接受 | | P5 | 文档与事实脱节 | 子 agent 基于错误约束持续返工 | 一旦发现偏差，主 agent 立即更新文档并广播 | | P6 | 过早整体评估 | 还未完成子任务验收就提前总评 | 只有 Phase 6 后才创建 overall evaluator | | P7 | 指派 external crew | Spawn 失败或流程中断 | 仅指派 self 或 `allowAgents` 白名单内 crew | | P8 | 主 agent 越权代评 | 评估失真，流程失守 | 主 agent 只治理流程，不代替 evaluator 下 verdict | --- ## Plan Mutation Protocol — 执行中计划变更 遇到以下情况，需要修改计划或文档时，遵守正式变更流程。 ### 触发场景 - **子任务文档与事实冲突**：先定位冲突点，必要时向用户确认，再更新 `task.md` / `acceptance.md` - **整体评估发现新缺口**：新增子任务，或拆分现有子任务 - **用户主动修改目标或范围**：先判断是否影响全局 AC；影响则重走对应确认流程 - **关键依赖变化**：调整子任务依赖和执行顺序，并同步受影响的执行者和评估者 ### 变更记录 所有变更必须在 `progress.md` 追加： ```markdown ## [<时间戳>] 计划变更 - 变更原因：<触发场景> - 变更内容：<新增 / 修改 / 取消哪个子任务，或更新哪份文档> - 影响范围：<受影响的子任务 / 评估者 / 聚合结果> - 用户确认：<已确认 / 无需确认> ``` ### 必须重走确认的内容 以下内容一旦已获用户确认，后续若要修改，必须重新与用户确认： - 全局验收标准（AC） - 最终交付物形式 以下内容通常不需要单独等待确认，但发生重大变化时，应及时同步用户： - 子任务总体拆分逻辑 - 关键执行顺序与重大依赖关系