agent-team-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Team Orchestration

Production playbook for running multi-agent teams with clear roles, structured task flow, and quality gates.

用于运行角色清晰、任务流程结构化、具备质量关卡的多Agent团队的生产级操作手册。

Quick Start: Minimal 2-Agent Team

快速开始：最小2-Agent团队

A builder and a reviewer. The simplest useful team.

由一名构建者和一名审查者组成，是最简单的实用团队。

1. Define Roles

1. 定义角色

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

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

2. Spawn a Task

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

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. Add a Reviewer

3. 添加审查者

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

That's the core loop. Everything below scales this pattern.

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

以上就是核心循环，后续所有内容都是对该模式的扩展。

Core Concepts

核心概念

Roles

角色

Every agent has one primary role. Overlap causes confusion.

Role	Purpose	Model guidance
Orchestrator	Route work, track state, make priority calls	High-reasoning model (handles judgment)
Builder	Produce artifacts — code, docs, configs	Can use cost-effective models for mechanical work
Reviewer	Verify quality, push back on gaps	High-reasoning model (catches what builders miss)
Ops	Cron jobs, standups, health checks, dispatching	Cheapest model that's reliable

→ Read references/team-setup.md when defining a new team or adding agents.

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

角色	用途	模型选择指引
Orchestrator（编排者）	分配工作、跟踪状态、确定优先级	高推理能力模型（负责判断类工作）
Builder（构建者）	产出工件——代码、文档、配置文件	机械类工作可使用性价比更高的模型
Reviewer（审查者）	验证质量、反馈遗漏问题	高推理能力模型（发现构建者遗漏的问题）
Ops（运维）	定时任务、站会、健康检查、任务调度	满足可靠性要求的最低成本模型

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

Task States

任务状态

Every task moves through a defined lifecycle:

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

Rules:

Orchestrator owns state transitions — don't rely on agents to update their own status
Every transition gets a comment (who, what, why)
Failed is a valid end state — capture why and move on

→ Read references/task-lifecycle.md when designing task flows or debugging stuck tasks.

每个任务都会遵循定义好的生命周期流转：

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

规则：

编排者负责状态流转——不要依赖Agent自行更新状态
每次状态流转都要附带备注（操作人、操作内容、操作原因）
失败是有效的结束状态——记录失败原因后继续推进其他工作

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

Handoffs

移交

When work passes between agents, the handoff message includes:

What was done — summary of changes/output
Where artifacts are — exact file paths
How to verify — test commands or acceptance criteria
Known issues — anything incomplete or risky
What's next — clear next action for the receiving agent

Bad handoff: "Done, check the files." Good handoff: "Built auth module at
/shared/artifacts/auth/
. Run
npm test auth
to verify. Known issue: rate limiting not implemented yet. Next: reviewer checks error handling edge cases."

当工作在Agent之间流转时，移交消息需要包含：

已完成内容 —— 变更/产出的摘要
工件存放位置 —— 准确的文件路径
验证方式 —— 测试命令或验收标准
已知问题 —— 所有未完成或存在风险的内容
后续动作 —— 为接收方明确下一步操作

反面示例："Done, check the files." 正面示例："Built auth module at
/shared/artifacts/auth/
. Run
npm test auth
to verify. Known issue: rate limiting not implemented yet. Next: reviewer checks error handling edge cases."

Reviews

审查

Cross-role reviews prevent quality drift:

Builders review specs — "Is this feasible? What's missing?"
Reviewers check builds — "Does this match the spec? Edge cases?"
Orchestrator reviews priorities — "Is this the right work right now?"

Skip the review step and quality degrades within 3-5 tasks. Every time.

→ Read references/communication.md when setting up agent communication channels. → Read references/patterns.md for proven multi-step workflows.

跨角色审查可以避免质量下滑：

构建者审查需求规格 —— "这个需求是否可行？还有什么遗漏？"
审查者检查构建产物 —— "是否符合需求规格？有没有覆盖边界场景？"
编排者审查优先级 —— "当前做这项工作是否是最优选择？"

跳过审查步骤的话，任务质量一定会在3-5次任务内下滑，无一例外。

→ 搭建Agent通信渠道时，请阅读 references/communication.md → 查看经过验证的多步骤工作流，请阅读 references/patterns.md

Reference Files

参考文件

File	Read when...
team-setup.md	Defining agents, roles, models, workspaces
task-lifecycle.md	Designing task states, transitions, comments
communication.md	Setting up async/sync communication, artifact paths
patterns.md	Implementing specific workflows (spec→build→test, parallel research, escalation)

文件	适用场景
team-setup.md	定义Agent、角色、模型、工作区
task-lifecycle.md	设计任务状态、流转规则、备注规范
communication.md	搭建同步/异步通信机制、工件路径规范
patterns.md	实现特定工作流（需求→构建→测试、并行调研、问题升级）

Common Pitfalls

常见陷阱

Spawning without clear artifact output paths

下发任务时没有明确的工件输出路径

Agent produces great work, but you can't find it. Always specify the exact output path in the spawn prompt. Use a shared artifacts directory with predictable structure.

Agent产出了符合要求的工作成果，但你找不到。一定要在下发任务的提示词中指定准确的输出路径，使用结构可预测的共享工件目录。

No review step = quality drift

没有审查步骤导致质量下滑

"It's a small change, skip review." Do this three times and you have compounding errors. Every artifact gets at least one set of eyes that didn't produce it.

"只是个小改动，跳过审查吧。" 这么做三次之后你就会遇到叠加的错误。每份工件都至少要经过一名非产出者的检查。

Agents not commenting on task progress

Agent没有备注任务进度

Silent agents create coordination blind spots. Require comments at: start, blocker, handoff, completion. If an agent goes silent, assume it's stuck.

沉默的Agent会造成协作盲区。要求Agent在以下节点备注：任务开始、遇到阻塞、移交工作、任务完成。如果Agent长时间没有反馈，默认它已经卡住。

Not verifying agent capabilities before assigning

分配任务前没有验证Agent能力

Assigning browser-based testing to an agent without browser access. Assigning image work to a text-only model. Check capabilities before routing.

给没有浏览器访问权限的Agent分配浏览器测试任务，给仅支持文本的模型分配图像处理任务。在路由任务前一定要先检查能力匹配度。

Orchestrator doing execution work

编排者亲自执行工作

The orchestrator routes and tracks — it doesn't build. The moment you start "just quickly doing this one thing," you've lost oversight of the rest of the team.

编排者的职责是路由和跟踪任务，而不是亲自构建。一旦你开始想着「就快速搞定这一件小事」，你就会失去对团队其余工作的监管。

When NOT to Use This Skill

不适用该技能的场景

Single-agent setups — Just follow standard AGENTS.md conventions. Team orchestration adds overhead that solo agents don't need.
One-off task delegation — Use
```
sessions_spawn
```
directly. This skill is for sustained workflows with multiple handoffs.
Simple question routing — If you're just forwarding a question to a specialist, that's a message, not a workflow.

This skill is for sustained team workflows — recurring collaboration patterns where agents depend on each other's output over multiple tasks.

单Agent场景 —— 直接遵循标准AGENTS.md规范即可。团队编排会带来单Agent不需要的额外开销。
一次性任务委托 —— 直接使用
```
sessions_spawn
```
即可。该技能适用于存在多次移交的持续工作流。
简单问题路由 —— 如果你只是把问题转发给专家，那只是发消息，不是工作流。

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