编排模式参考与反模式防御
编排模式参考与反模式防御
学习目标
- 理解 5 种已批准编排模式的适用场景和成本
- 识别 4 种编排反模式并知道替代方案
- 掌握编排决策流程
- 理解 Claude Code 平台如何强制执行部分反模式预防
前置知识
本章涉及多 Agent 路由与编排模式的通用原理，建议先阅读：
下文直接聚焦 agent-skills 的编排模式目录定义。
项目实践
治理规则
agent-skills 的编排模式目录有一条核心治理规则：
用户（或斜杠命令）是编排者。Persona 不调用其他 Persona。
这条规则在 AGENTS.md、agents/README.md 和 references/orchestration-patterns.md 中反复出现，是整个编排设计的基石。
五种已批准的编排模式
| # | 模式 | 结构 | 成本 | 适用场景 | 示例 |
|---|---|---|---|---|---|
| 1 | 直接调用 | user → persona → report → user | 1 次往返 | 单视角单工件 | ”审查这个 PR” → code-reviewer |
| 2 | 单人斜杠命令 | /cmd → persona(with skill) → report | 同直接调用 | 重复工作流 | /review → code-reviewer with review skill |
| 3 | 平行扇出 + 合并 | /cmd → N personas → merge → verdict | N 并行上下文 + 1 合并 | 独立调查 | /ship → 3 角色并行 |
| 4 | 用户驱动的顺序流水线 | user runs /spec → /plan → /build | 每步 1 上下文 | 有依赖关系，需人工判断 | 完整生命周期 |
| 5 | 研究隔离 | main → research sub-agent → digest → main | 1 隔离上下文 | 大量阅读不污染主上下文 | ”查找所有废弃 API 调用点” |
验证清单（采用模式 3 前）：
- 可以同时运行所有子 Agent 而没有顺序问题？
- 每个角色产生的是不同类型的发现，而非同一发现的不同角度？
- 合并步骤能装入主 Agent 的剩余上下文？
- 用户的等待时间足够长以至于并行性实际可感知？
如果任一回答是”否”，回退到直接调用或单人命令。
四种反模式
| 反模式 | 结构 | 为什么失败 | 替代方案 |
|---|---|---|---|
| A: 路由角色 | work → router → persona → router(paraphrase) → user | 纯路由无领域价值，两次转述导致信息丢失 + 2× token | 完善斜杠命令和意图映射 |
| B: 角色调用角色 | code-reviewer 内部调用 security-auditor | 破坏单一视角，转述丢失上下文 | 在报告中推荐后续审计 |
| C: 顺序编排器复述 | 自动按序调用 /spec → /plan → /build | 丢失人工检查点，每步转述导致漂移，token 翻倍 | 保持用户为编排者 |
| D: 深层角色树 | /ship → pre-ship → quality → code-reviewer | 每层增加延迟无决策价值，调试变多层调查 | 编排深度最多 1 层 |
决策流程
工作是否是一个视角对一个工件？├── 是 → 直接调用。停止。└── 否 → 同样的组合会重复吗？ ├── 否 → 临时直接调用。停止。 └── 是 → 子任务是否独立？ ├── 否 → 用户驱动的顺序斜杠命令（模式 4）。 └── 是 → 平行扇出 + 合并（模式 3）。 用验证清单检查。 如果任何检查失败 → 回退到单人命令（模式 2）。平台强制约束
Claude Code 平台通过架构设计自动阻止了部分反模式：
| 约束 | 阻止的反模式 |
|---|---|
| ”Subagent 不能生成 Subagent” | B（角色调用角色）、D（深层角色树） |
| “Team 不能嵌套” | D（深层角色树）在 Agent Teams 层面 |
意义：即使 contributors 不小心构建了反模式，它们也会因为平台约束而无法加载。这不是偶然——agent-skills 的编排设计有意利用了平台的硬约束来防止常见的架构错误。
Agent Teams 实战案例：竞态假设调试
agent-skills 在 references/orchestration-patterns.md 中提供了一个 Agent Teams 的完整实战案例：
场景：结账偶尔挂起约 30 秒，每 50 次会话约 1 次，无日志错误。
为什么这不是 /ship 的任务：
/ship（子 Agent） | Agent Teams | |
|---|---|---|
| 子 Agent 看到 | 同一个 diff，不同视角 | 共享任务列表，彼此的消息 |
| 输出 | 三份独立报告 → 一个合并 | 对抗性辩论 → 共识根因 |
| 适用时机 | 对已知工件的判决 | 在假设之间找到工件 |
/ship 是判决；Agent Teams 是调查。
触发提示：
用户报告结账在上周发布后偶尔挂起约 30 秒。日志中无错误。
创建一个 Agent Teams 来调试这个，使用竞争假设。生成三个队友，使用已有的角色类型：
- code-reviewer — 调查结账代码路径中的竞态和阻塞调用 - security-auditor — 调查最近的 auth 检查和同步网络调用 - test-engineer — 提出区分假设的测试并检查覆盖缺口
让他们直接互相发消息挑战彼此的理论。新模式的准入标准
向编排目录添加新模式的门槛很高：
- 至少在真实工作中使用过两次
- 能指出仓库中证明它的具体工件
- 能解释为什么现有模式不够用
- 能描述它的反模式阴影（人们会错误地构建什么）
过早的目录条目会成为没人遵循的理想化文档。
问题与规避
| 陷阱 | 表现 | 对策 |
|---|---|---|
| 创建路由角色 | ”让一个角色决定用什么角色” | 路由是斜杠命令的工作，不是角色 |
| 模式 3 验证不通过却强行使用 | 子任务有顺序依赖 | 回退到模式 4（用户驱动的流水线） |
| Agent Teams 用于常规审查 | 成本远高于必要 | 常规审查用 /ship（子 Agent） |
| 新准入标准不满足就添加 | 文档与实际行为脱节 | 先在实践中验证至少两次 |
设计取舍
为什么将用户定位为编排者，而不是自动化编排？
自动化的 LLM”生命周期编排器”会：(a) 在步骤间丢失细微差别（需要总结交接），(b) 跳过捕获方向错误的人工检查点，(c) 通过转述使 token 成本翻倍。用户驱动的编排保留了人类在关键节点的判断力，同时消除了额外编排层的 token 开销。
为什么只批准 5 种模式？
限制模式数量防止了编排复杂度的无限增长。如果每次遇到新的编排需求都添加新模式，目录会变成一份没人遵循的理想化文档。5 种模式覆盖了 agent-skills 遇到的所有实际编排场景。
参考来源
- 源码验证:
references/orchestration-patterns.md— 完整的编排模式目录（~370 行） - 源码验证:
agents/README.md— 角色关系和决策矩阵 - 源码验证:
AGENTS.md— 编排规则的定义