agent-team-orchestration

Agent Team Orchestration

使用清晰的角色、结构化的任务流程和质量关卡来运行多 Agent 团队的生产实践指南。

快速入门：最精简的双 Agent 团队

一个构建者和一个审查者。这是最简单且实用的团队。

1. 定义角色

Orchestrator (you) — Route tasks, track state, report results
Builder agent     — Execute work, produce artifacts

2. 分配任务

1. Create task record (file, DB, or task board)
2. Spawn builder with:
   - Task ID and description
   - Output path for artifacts
   - Handoff instructions (what to produce, where to put it)
3. On completion: review artifacts, mark done, report

3. 添加审查者

Builder produces artifact → Reviewer checks it → Orchestrator ships or returns

这就是核心循环。下文内容都在此基础上扩展。

核心概念

角色

每个 Agent 都有一个主要角色。角色重叠会造成混乱。

角色	用途	模型建议
协调者	分派工作、跟踪状态、确定优先级	高推理能力的模型（负责判断）
构建者	产出成果——代码、文档、配置	机械性工作可使用高性价比模型
审查者	验证质量、指出遗漏	高推理能力的模型（发现构建者遗漏的问题）
运维	定时任务、站会、健康检查、任务分派	可靠的前提下选择成本最低的模型

→ 定义新团队或添加 Agent 时，请阅读 references/team-setup.md。

任务状态

每项任务都会经历明确的生命周期：

Inbox → Assigned → In Progress → Review → Done | Failed

规则：

• 状态转换由协调者负责——不要依赖 Agent 更新自己的状态
• 每次状态转换都要添加评论（谁、做了什么、为什么）
• 失败也是有效的终态——记录失败原因，然后继续推进

→ 设计任务流程或排查卡住的任务时，请阅读 references/task-lifecycle.md。

交接

工作在 Agent 之间传递时，交接消息应包含：

1. 已完成的工作——变更或输出摘要
2. 成果所在位置——确切的文件路径
3. 验证方式——测试命令或验收标准
4. 已知问题——任何未完成或有风险之处
5. 后续事项——接手 Agent 要执行的明确下一步操作

糟糕的交接："完成了，检查一下文件。" 良好的交接："已在 /shared/artifacts/auth/ 构建认证模块。运行 npm test auth 进行验证。已知问题：尚未实现速率限制。下一步：审查者检查错误处理的边界情况。"

审查

跨角色审查可以防止质量下滑：

• 构建者审查规格——“是否可行？还缺少什么？”
• 审查者检查构建成果——“是否符合规格？边界情况呢？”
• 协调者审查优先级——“现在做这项工作是否合适？”

跳过审查环节，质量会在 3-5 项任务内下滑。每次都是如此。

→ 设置 Agent 通信渠道时，请阅读 references/communication.md。 → 有关经过验证的多步工作流，请阅读 references/patterns.md。

参考文件

文件	适合在何时阅读……
team-setup.md	定义 Agent、角色、模型和工作区时
task-lifecycle.md	设计任务状态、状态转换和评论时
communication.md	设置异步/同步通信和成果路径时
patterns.md	实现特定工作流时（规格→构建→测试、并行研究、升级处理）

常见陷阱

分配任务时未明确成果输出路径

Agent 产出了出色的成果，但你却找不到。务必在分配任务的提示词中指定确切的输出路径。使用结构清晰、易于预测的共享成果目录。

没有审查环节＝质量下滑

“这是个小改动，跳过审查吧。”这样做三次，错误就会层层累积。每项成果至少要由一位未参与产出的人检查。

Agent 不评论任务进度

沉默的 Agent 会造成协作盲区。要求 Agent 在开始、遇到阻塞、交接和完成时发表评论。如果 Agent 不再回复，就假定它被卡住了。

分配任务前未确认 Agent 的能力

安排无法使用浏览器的 Agent 进行基于浏览器的测试；安排只能处理文本的模型处理图像任务。分派任务前先检查能力。

编排器负责执行工作

编排器负责路由和跟踪，不负责构建。你一旦开始“顺手快速处理这件事”，就会失去对团队其他成员的掌控。

何时不应使用此技能

• 单 Agent 配置 — 只需遵循标准的 AGENTS.md 约定。团队编排会增加单 Agent 不需要的开销。
• 一次性任务委派 — 直接使用 sessions_spawn。此技能适用于需要多次交接的持续工作流。
• 简单的问题路由 — 如果你只是把问题转交给某位专家，那只是条消息，而不是工作流。

此技能适用于持续的团队工作流——即 Agent 需要在多个任务中相互依赖彼此输出的重复协作模式。