agent-skills 多角色编排模式实战：并行扇出、顺序流水线与 Agent Teams 的选型指南

本文以 agent-skills 仓库的 references/orchestration-patterns.md 为骨架，系统讲解 AI 编码 Agent 编排的 5 种被认可的协作模式、4 种反模式与一套决策流程，并结合仓库中真实的角色定义（agents/ 目录）与斜杠命令（commands/ship.toml 等）剖析"用户即编排者"这一核心原则的落地方式。读完你可以掌握：为一次多 Agent 协作选对模式（直接调用、单角色命令、并行扇出、顺序流水线、研究隔离）、在 Claude Code 中正确配置 Subagents 与实验性的 Agent Teams，以及避免路由器角色、角色互相调用等常见设计错误。

核心规则：用户（或斜杠命令）是编排者

该文档开宗明义给出全仓库的编排总纲：

the user (or a slash command) is the orchestrator. Personas do not invoke other personas. Skills are mandatory hops inside a persona's workflow.

即：用户或斜杠命令才是编排层；角色（persona）之间不允许互相调用；技能（skill）是角色工作流内部必须经过的环节。这条规则在仓库多个入口文件中被反复强化：

• AGENTS.md 的 "Orchestration: Personas, Skills, and Commands" 一节把仓库划分为三层——Skills（skills/<name>/SKILL.md，how，带步骤与退出条件的工作流）、Personas（agents/<role>.md，who，带视角与输出格式的角色）、Slash commands（when，用户可见的入口），并明确"本仓库唯一认可的多角色编排模式是带合并步骤的并行扇出"；
• docs/agents.md 进一步给出三层职责表（Skill / Persona / Command），并在"Rules for personas"中规定：每个角色文件必须以 Composition 块结尾，声明自己的编排位置。

可以对照仓库中一个真实角色来验证这条规则。agents/code-reviewer.md 末尾的 Composition 块写着：

- Invoke directly when: the user asks for a review of a specific change, file, or PR.
- Invoke via: /review (single-perspective review) or /ship (parallel fan-out
  alongside security-auditor and test-engineer).
- Do not invoke from another persona. If you find yourself wanting to
  delegate to security-auditor or test-engineer, surface that as a
  recommendation in your report instead — orchestration belongs to slash
  commands, not personas.

也就是说，角色发现自己"想"转调另一个角色时，正确做法是在报告里建议后续审计，把第二次调用的决定权交还给用户或斜杠命令。这正是反模式 B（后文详述）的第一道防线。

五种被认可的编排模式

模式 1：直接调用（无编排）

单个角色、单一视角、单一产物，是默认选项也是最便宜的选项：

user → code-reviewer → report → user

适用条件：工作是对单一产物的一种视角审视，且能用一句话描述清楚。典型示例：

• "Review this PR" → code-reviewer
• "Find security issues in auth.ts" → security-auditor
• "What tests are missing for the checkout flow?" → test-engineer

成本：一次往返（one round trip）。这是所有编排模式必须对比的基线——任何更复杂的编排都要先回答"比直接调用贵多少、换来什么"。

模式 2：单角色斜杠命令

用一个斜杠命令把"单个角色 + 项目技能"打包，省掉用户每次重新解释流程的麻烦：

/review → code-reviewer (with code-review-and-quality skill) → report

适用条件：同一个单角色调用以相同的设置反复发生。本仓库中的实例包括 /review、/test、/code-simplify（以及面向 Web 应用性能审计的 /webperf）。

从源码看，这类命令确实只是"保存好的提示词"：commands/review.toml 的正文只做了两件事——调用 code-review-and-quality 技能、要求按五个轴（正确性、可读性、架构、安全、性能）输出 file:line 级发现；commands/code-simplify.toml 则是"调用 code-simplification 技能 + 逐步简化 + 每步跑测试"的固定流程。成本与直接调用相同，因为斜杠命令本质上只是一段被保存的 prompt。

文档给出一个反信号（anti-signal）：如果斜杠命令的正文大部分内容是"决定该调哪个角色"，删掉它，让用户直接调角色。

模式 3：并行扇出 + 合并（Parallel fan-out with merge）

多个角色并发处理同一份输入，各自产出独立报告，最后由主 Agent 的上下文完成一个合并步骤，综合成单一决策：

                    ┌─→ code-reviewer    ─┐
/ship → fan out  ───┼─→ security-auditor ─┤→ merge → go/no-go + rollback
                    └─→ test-engineer    ─┘

适用条件（四条必须同时满足）：

• 子任务真正独立（无共享可变状态、无顺序依赖）；
• 每个子 Agent 都能从自己独立的上下文窗口中受益；
• 合并步骤足够小，能留在主上下文里完成；
• 墙钟延迟（wall-clock latency）敏感。

仓库实例：/ship。commands/ship.toml 是模式 3 的标准实现，结构上分三个阶段：

• Phase A — 并行扇出：并发派生 code-reviewer（五轴审查）、security-auditor（OWASP Top 10、密钥处理、认证授权、依赖 CVE）、test-engineer（覆盖率与缺口分析）三个子 Agent。命令中明确要求"把三个子 Agent 工具调用放在同一个 assistant turn 里发出，以保证并行执行——顺序调用会让这个命令失去意义"；
• Phase B — 主上下文合并：由主 Agent（而非任何子角色）把三份报告综合为 Code Quality / Security / Performance / Accessibility / Infrastructure / Documentation 六个维度的结论；
• Phase C — 决策与回滚：输出 Ship Decision: GO | NO-GO 报告模板，含 Blockers、Recommended fixes、Acknowledged risks、Rollback plan（触发条件、回滚步骤、恢复时间目标）以及三份完整专项报告。

规则上，/ship 还约束：三个角色必须并行、角色之间不得互调、任何 GO 决策前必须有回滚计划、任一角色报出 Critical 发现时默认 NO-GO；并且给出了跳过扇出的判据——仅当改动不超过 2 个文件、diff 少于 50 行且不涉及 auth/payments/数据访问/配置时才可跳过，否则默认扇出。这与文档"合并步骤要留在主 Agent"的设计完全一致。

成本：N 个并行子 Agent 上下文 + 1 轮合并。比直接调用贵，但墙钟更快，且由于每个子 Agent 只聚焦单一视角，报告质量更高。

采用前的验证清单（原文档原样保留，缺一不可）：

• [ ] 所有子 Agent 能否同时运行而不产生顺序问题？
• [ ] 每个角色产出的是不同类型的发现，而不是同一发现的不同角度？
• [ ] 合并步骤能否装进主 Agent 剩余的上下文？
• [ ] 用户等待时间是否长到并行真的能被感知？

任何一项回答"否"，就回退到直接调用或单角色命令（模式 2）。

模式 4：顺序流水线 = 用户驱动的斜杠命令

用户按既定顺序运行斜杠命令，在命令之间携带上下文（或提交历史）。没有编排 Agent——用户本人就是编排者：

user runs:  /spec  →  /plan  →  /build  →  /test  →  /review  →  /ship

适用条件：工作流存在依赖（每一步需要上一步的产物），且步骤之间的人工判断有增值。仓库实例就是整个 DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP 生命周期，对应命令分别是 commands/spec.toml、commands/planning.toml、commands/test.toml、commands/review.toml、commands/ship.toml。

可以推断这条流水线各环节是"产物驱动"的：例如 spec.toml 要求把规格保存为项目根的 SPEC.md 并经用户确认；planning.toml 则要求"读取既有 SPEC.md"、进入只读 plan 模式、按依赖图垂直切片任务，产物落在 tasks/plan.md 与 tasks/todo.md。正是这些落盘产物（而非任何隐式记忆）充当了步骤之间的上下文载体——这也是"用户即编排者"能成立的技术前提。

成本：每步一个子 Agent 上下文；编排层零成本，因为根本没有编排 Agent。

为什么不用 LLM 自动编排整条生命周期？ 文档给出了三条理由：(a) LLM "生命周期编排者"在步骤间交接时必须做摘要，会丢失细微信息；(b) 跳过人工检查点，无法及早发现方向性错误；(c) 每步都要"编排者转述 + 子 Agent 执行"两轮，token 成本翻倍。

模式 5：研究隔离（上下文保护）

当任务需要阅读大量不应污染主上下文的材料时，派生一个研究型子 Agent，只返回摘要：

main agent → research sub-agent (reads 50 files) → digest → main agent continues

适用条件：

• 主会话需要保持在下游任务上；
• 调查结论远小于它消耗的材料体积；
• 主 Agent 在调查之后还需要留有余量来思考决策。

典型例子："在整个 monorepo 里找出这个废弃 API 的全部调用点"、"总结这 30 份 ADR 对缓存说了什么"。

成本：一个隔离的子 Agent 上下文。只要替代方案是把几百个文件塞进主上下文，它就划算。

在 Claude Code 上的落地：优先使用内置的 Explore 子 Agent 而不是自定义研究角色——它跑在 Haiku 上、被拒绝写/编辑工具，正是为这个模式设计的。只有当 Explore 不适用（例如需要模型无法自行推断的领域特定系统提示）时，才定义自定义研究子 Agent。

Claude Code 兼容性映射

该目录是"编排无关"（harness-agnostic）的，但多数读者在 Claude Code 上运行。文档给出了各模式到 Claude Code 原语的映射，以及平台替我们强制执行规则的位置。

角色放在哪里

插件的子 Agent 放在插件根目录的 agents/ 下。本仓库是一个插件（见 .claude-plugin/plugin.json，其中声明 commands 指向 ./.claude/commands 与 ./commands，skills 指向 ./skills），因此 agents/code-reviewer.md、agents/security-auditor.md、agents/test-engineer.md 在插件启用时会被自动发现，无需任何路径配置。

Subagents vs Agent Teams

Claude Code 有两种并行原语。模式 3（并行扇出 + 合并）映射到 Subagents；如果需要彼此通信的队友，则使用 Agent Teams：

	Subagents	Agent Teams
协调方式	主 Agent 扇出，子 Agent 只回报结果	队友互相发消息、共享任务列表
上下文	每个子 Agent 独立上下文窗口	每个队友独立上下文窗口
适用场景	产出报告的独立任务	需要讨论的协作型工作
状态	稳定（Stable）	实验性（Experimental）——需要 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
成本	较低	较高——每个队友都是独立的 Claude 实例

文档强调本仓库的角色两种模式都支持：作为子 Agent 派生时（如 /ship），它们向主会话汇报；作为队友派生时（"Spawn a teammate using the security-auditor agent type…"），它们可以直接互相质疑对方的发现。角色定义完全相同，变化的只是派生上下文。

一个容易踩坑的细节：角色 frontmatter 中的 skills 与 mcpServers 字段，在角色作为子 Agent 运行时生效，但作为队友运行时被忽略——队友与常规会话一样，从项目和用户设置加载技能与 MCP server。若某角色依赖某个特定技能或 MCP server，应在会话级配置它，保证两种模式下都可用。

平台强制执行的规则

目录里有两条规则不只是约定——Claude Code 直接强制：

• "Subagents cannot spawn other subagents"（官方文档原话）。因此反模式 B（角色调角色）和反模式 D（深层角色树）在 Claude Code 上结构上不可能存在；
• "No nested teams"——队友不能派生自己的 team，同样的反模式在 team 层面也被阻断。

这意味着你可以放心采用本目录的模式而不必担心贡献者误建反模式——它们会直接加载失败。

内置子 Agent

在定义自定义子 Agent 之前，先确认内置角色是否已覆盖该职责：

内置角色	用途
Explore	只读代码库搜索与分析。模式 5（研究隔离）用它。
Plan	plan 模式下的只读研究。
general-purpose	需要探索 + 修改的多步骤任务。

原则是：不要重新定义这些内置角色，而是在它们之上叠加专业角色（如 code-reviewer、security-auditor、test-engineer）。

插件 Agent 的 frontmatter 限制

插件子 Agent 不支持 hooks、mcpServers、permissionMode 三个 frontmatter 字段——它们会被静默忽略。若未来某个角色需要这些字段，用户需要把该文件复制到 .claude/agents/ 或 ~/.claude/agents/。

插件 Agent 中确实生效的字段为：name、description、tools、disallowedTools、model、maxTurns、skills、memory、background、effort、isolation、color、initialPrompt。可按角色设置 model 来优化成本，例如 test-engineer 的覆盖率扫描用 Haiku、code-reviewer 用 Sonnet、security-auditor 用 Opus。

并行派生多个子 Agent

在 Claude Code 上，模式 3 的并行扇出要求在同一个 assistant turn 中发出多个 Agent 工具调用；分开在不同 turn 里发会退化为串行执行。commands/ship.toml 已对此显式说明，文档要求：任何新的编排命令都应写明这一点。

实战案例：用 Agent Teams 做"竞争假设"式调试

这部分展示何时应该选 Agent Teams 而不是 /ship 的子 Agent 扇出。两种模式远看相似——都派生同样三个角色——但价值来源完全不同。

场景

结账流程偶尔在完成后卡顿约 30 秒，大约每 50 次会话出现一次，日志没有报错，始于上周发布之后。

若干互斥且都符合症状的根因假设：

1. 新支付确认流程中的竞态条件；
2. 某个认证检查偶发落入一次缓慢的同步网络调用；
3. 一条随购物车规模扩展的查询缺少索引；
4. 某个不稳定第三方 API，SDK 在超时前静默重试。

单个 Agent 会挑第一个"看起来合理"的理论然后停止深挖；而 /ship 式扇出中每个角色独立汇报、报告互不相见，没有任何机制能证伪错误的理论。这正是 Agent Teams 官方文档描述的用例："多个独立调查者积极尝试互相证伪时，存活下来的理论才更可能是真正的根因。"

为什么这不是 /ship 的活

	/ship（子 Agent）	Agent Teams
子 Agent 看到什么	同一份 diff，不同镜片	共享任务列表 + 彼此的消息
产出	三份独立报告 → 一次合并	对抗式辩论 → 共识根因
何时选	对已知产物要一个结论（verdict）	要在假设中找出那个产物（artifact）

一句话概括：/ship 是裁决，Agent Teams 是调查。

一次性配置

Agent Teams 是实验特性，在 ~/.claude/settings.json 中开启：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

要求 Claude Code v2.1.32 或更高版本。本仓库的角色会被自动拾取——无需手写任何 team 配置文件。

触发提示词

在 lead 会话中以自然语言输入：

Users report checkout hangs for ~30 seconds intermittently after last
week's release. No errors in logs.

Create an agent team to debug this with competing hypotheses. Spawn
three teammates using the existing agent types:

  - code-reviewer  — investigate race conditions and blocking calls
                     in the checkout code path
  - security-auditor — investigate auth checks, session handling,
                       and any synchronous network calls added recently
  - test-engineer  — propose tests that would distinguish between the
                     hypotheses and check coverage gaps in checkout

Have them message each other directly to challenge each other's
theories. Update findings as consensus emerges. Only converge when
two teammates agree they can disprove the others'.

lead 通过引用既有角色名派生三个队友。角色正文会被追加（append）到每个队友的系统提示末尾（叠加在 lead 安装好的 team 协调指令之上）；上面的触发提示词则成为他们的任务。docs/agents.md 的 "Claude Code interop" 一节对此有对应说明：队友模式下 persona 文本不是替代系统提示，而是叠加在 SendMessage、任务列表等协调指令之上的附加指令。

运行过程中发生了什么

1. 每个队友在独立上下文窗口中，从自己的视角探索代码库；
2. 队友之间直接用 message 互发发现，lead 无需中继；
3. 共享任务列表随时可见——in-process 模式下按 Ctrl+T，split 模式下在 tmux 窗格中；
4. 当 code-reviewer 发现一处本应顺序执行的 Promise.all 时，它发消息让 security-auditor 确认认证调用不属于该竞态；对方核查后回复——要么确认竞态是真凶，要么给出反证；
5. test-engineer 为占上风的那个理论设计一个聚焦的集成测试，团队用它验证后再宣布共识；
6. lead 综合收敛后的结论呈现给你。

期间你可以用 Shift+Down 循环切换、直接输入，随时打断某个跑偏的调查者。

何时清理

调查落到根因后，告诉 lead：

Clean up the team

务必通过 lead 清理，而不是通过某个队友（官方文档：队友缺少清理所需的完整 team 上下文）。

成本预期

三个 Sonnet 队友跑约 10–15 分钟的调查，费用明显高于同样三个角色被 /ship 作为子 Agent 派生。其合理性在于结论质量——在生产环境排障、错误修复代价高昂的场景，多花的 token 物有所值；常规 PR 审查则仍用 /ship。

该场景下的反模式

不要把这套流程改写成 /debug 斜杠命令去扇出子 Agent。子 Agent 之间不能发消息——你会丢掉让整个模式成立的对抗式辩论。如果这类工作流反复出现，把上面的触发提示词沉淀为一条文档化的 snippet，而不是包装成误用子 Agent 的斜杠命令。

何时不用 Agent Teams

• 对已知 diff 要一个生产级结论 → 用 /ship（子 Agent）；
• 对单一产物要一种专业视角 → 直接调用角色；
• 顺序生命周期（spec → plan → build）→ 用户驱动的斜杠命令（模式 4）；
• 重读取、小摘要的研究 → 内置 Explore 子 Agent。

只有当队友必须互相质疑才能得出正确答案时，才动用 Agent Teams。

反模式目录

A. 路由器角色（"meta-orchestrator"）

一个职责是"决定该调哪个角色"的角色：

/work → router-persona → "this needs a review" → code-reviewer → router (paraphrases) → user

为什么失败：纯路由层、零领域价值；多出两次转述 → 信息损耗 + 约 2 倍 token 成本；用户本来就知道自己要 review，可以直接调 /review；它只是重复了斜杠命令与 AGENTS.md 意图映射已经在做的工作。

正确做法：新增或打磨斜杠命令，并在 AGENTS.md 中记录"意图 → 命令"映射。

B. 角色调用角色

例如 code-reviewer 内部看到 auth 代码就自动调用 security-auditor。

为什么失败：角色被设计为只产单一视角，链式调用破坏了这一点；调用方传递的摘要会丢掉被调方需要的上下文；失败模式成倍增加（输出格式听谁的？规则听谁的？）；成本对用户隐形。

正确做法：调用方角色在报告中建议做后续审计，由用户或斜杠命令执行第二遍。这一点在 agents/code-reviewer.md 的 Composition 块中已作为硬性规则写出；在 Claude Code 上，该模式还会被平台直接阻断（子 Agent 不能派生子 Agent）。

C. 替你转述的顺序编排者

一个 Agent 代替用户依次调用 /spec、/plan、/build。

为什么失败：丢失能捕捉"方向性错误"的人工检查点；每次交接都在做上下文摘要，长流水线累积漂移；每步"编排者轮次 + 子 Agent 轮次"使 token 成本翻倍；在最需要判断力的节点剥夺了用户的主导权。

正确做法：保持用户为编排者，在 README.md 中记录推荐顺序，由用户自己依次调用。

D. 深层角色树

/ship 调 pre-ship-coordinator，后者调 quality-coordinator，后者再调 code-reviewer。

为什么失败：每一层都增加延迟与 token 却不产生决策价值；调试变成多层排查；叶节点角色在多次摘要后丢失上下文。

正确做法：编排深度最多为 1（斜杠命令 → 角色），合并在主 Agent 中进行。

决策流程：为新编排工作流选型

考虑任何新的编排工作流时，走一遍下面这棵决策树（原文档 "Decision flow" 原样保留）：

Is the work one perspective on one artifact?
├── Yes → Direct invocation. Stop.
└── No  → Will the same composition repeat?
         ├── No  → Direct invocation, ad hoc. Stop.
         └── Yes → Are sub-tasks independent?
                  ├── No  → Sequential slash commands run by user (Pattern 4).
                  └── Yes → Parallel fan-out with merge (Pattern 3).
                           Validate against the checklist above.
                           If any check fails → fall back to single-persona
                           command (Pattern 2).

docs/agents.md 中另有一棵等价的"决策矩阵"，把第三问细化为"子任务是否独立（无共享可变状态、无顺序依赖）"，并直接映射到 /ship（并行扇出）或 /spec → /plan → /build → /test → /review（顺序命令）。两棵树可以互为交叉验证：先问"单一视角？"，再问"会重复吗？"，最后问"子任务独立吗？"。

何时向该目录新增模式

该文档对自身演进设了四道门槛——只有全部满足后才允许新增条目：

1. 你在真实工作中至少用过两次该模式；
2. 你能指出仓库中一个具体产物来演示它；
3. 你能解释为什么现有模式不适用；
4. 你能描述它的"反模式影子"（人们会错误地建成什么样子）。

文档的理由一针见血：过早进入目录的条目会变成没人遵循的愿景文档（aspirational documentation）。这条元规则本身值得任何想维护多 Agent 实践的团队借鉴——模式目录应当是经验沉淀，而不是设计先行。

小结：三层职责 + 深度上限 1

回到仓库源码层面，这套编排体系的落地形态可以概括为：

• Skill 层（skills/*/SKILL.md）：带步骤与退出条件的工作流，被角色或命令在内部强制调用；
• Persona 层（agents/*.md，如 agents/code-reviewer.md、agents/security-auditor.md、agents/test-engineer.md、agents/web-performance-auditor.md）：单一视角 + 单一输出格式，文件末尾必有 Composition 块；
• Command 层（commands/*.toml，如 commands/ship.toml）：唯一的合法编排点，其中只有 /ship 是多角色编排（并行扇出 + 合并），其余均为"模式 2"式单角色包装。

配合 Claude Code 的平台约束（子 Agent 不能派生子 Agent、team 不可嵌套），该体系把"深度最多 1 层、合并留在主上下文、用户保留全部检查点"从约定变成了不可违背的结构。对于要在自己的项目中引入类似多 Agent 工作流（或维护本仓库插件，当前版本见 plugin.json，0.6.8）的开发者，这份目录的价值正在于此：它不仅告诉你有哪些模式可用，更告诉你何时停下——单一视角就直接调用，会重复才写命令，独立才允许并行，需要对抗才启动 Team。