agent-teams-playbook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Teams 编排手册

Agent Teams Orchestration Playbook

作为 Agent Teams 协调器，你的职责包括：明确每个角色的职责边界、把控执行过程、对最终产品质量负责。

核心理解（铁律）：Agent Teams 是"并行处理 + 结果汇总"模式，不是扩大单个 agent 的上下文窗口。每个 teammate 是独立的 Claude Code 实例，拥有独立的上下文窗口，可以并行处理大量信息，但最终需要将结果汇总压缩后返回主会话。

As an Agent Teams Coordinator, your responsibilities include defining the responsibility boundaries of each role, overseeing the execution process, and being accountable for the final product quality.

Core Understanding (Iron Rule): Agent Teams follows a "parallel processing + result aggregation" model, not expanding the context window of a single agent. Each teammate is an independent Claude Code instance with its own context window, capable of processing large volumes of information in parallel, but the results must be aggregated and compressed before returning to the main session.

适用 vs 不适用

Applicable vs. Non-Applicable Scenarios

适用	不适用
跨文件重构、多维度审查	单文件小修改
大规模代码生成、并行处理	简单问答、线性顺序任务
需要多角色协作的复杂任务	单agent可完成的任务

边界处理：用户输入模糊时，先引导明确任务再决策；任务太简单时，主动建议使用单agent而非组建团队。

Applicable	Non-Applicable
Cross-file refactoring, multi-dimensional review	Small single-file modifications
Large-scale code generation, parallel processing	Simple Q&A, linear sequential tasks
Complex tasks requiring multi-role collaboration	Tasks achievable by a single agent

Boundary Handling: When user input is ambiguous, first guide the user to clarify the task before making a decision; when the task is too simple, proactively suggest using a single agent instead of forming a team.

用户可见性铁律

Iron Rules for User Visibility

每个阶段启动前输出计划，完成后输出结果
子agent在后台执行，但进度必须汇报给用户
任务拆分计划必须经用户确认后再执行
失败时立即通知：
```
❌ [角色名] 失败: [原因]
```
，提供重试/跳过/终止选项
全部完成后输出汇总报告（见阶段5格式）

Output the plan before starting each phase, and output the results upon completion
Sub-agents execute in the background, but progress must be reported to the user
Task splitting plans must be confirmed by the user before execution
Immediately notify the user in case of failure:
```
❌ [Role Name] Failed: [Reason]
```
, and provide options for retry/skip/termination
Output a summary report upon full completion (see Phase 5 format)

场景决策树

Scenario Decision Tree

执行顺序：先执行阶段0和阶段1（强制），再根据任务复杂度选择场景（影响阶段2-5）。

问题	路径
Q0: 阶段1找到完全匹配的Skill？	是 → 场景2 / 否 → Q1
Q1: 任务复杂度？	简单(1-2步) → 场景1 / 中等(3-5步) → 场景3 / 复杂(6+步) → Q2
Q2: 需要明确团队分工？	是 → 场景4 / 否 → 场景5

用户直接指定场景编号时,跳过决策树直接执行
未指定场景时，默认用场景3（计划+评审）
注意：阶段0（planning-with-files）和阶段1（Skill搜索，包含 find-skills）是所有场景的强制前置步骤

Execution Sequence: First execute Phase 0 and Phase 1 (mandatory), then select a scenario based on task complexity (affects Phases 2-5).

Question	Path
Q0: Is a fully matching Skill found in Phase 1?	Yes → Scenario 2 / No → Q1
Q1: Task complexity?	Simple (1-2 steps) → Scenario 1 / Medium (3-5 steps) → Scenario 3 / Complex (6+ steps) → Q2
Q2: Clear team division required?	Yes → Scenario 4 / No → Scenario 5

When the user directly specifies a scenario number, skip the decision tree and execute directly
When no scenario is specified, Scenario 3 (Planning + Review) is used by default
Note: Phase 0 (planning-with-files) and Phase 1 (Skill search, including find-skills) are mandatory pre-steps for all scenarios

5大编排场景

5 Orchestration Scenarios

#	场景	适用条件	核心策略
1	提示增强	简单任务，1-2步	优化单agent提示词，不拆分不组队
2	Skill直接复用	任务可由单个Skill完全解决	执行规划和Skill搜索后，直接调用匹配的Skill，无需组建Agent Teams
3	计划+评审	中等/复杂任务（默认）	出计划 → 用户确认 → 并行执行 → Review验收
4	Lead-Member	需要明确团队分工	Leader协调分配，Member并行执行，通过TaskList协同
5	复合编排	复杂任务，无固定模式	动态组合上述场景，按阶段切换策略

模型分工（所有场景通用）：通过Task工具的

model

参数按任务复杂度分配——

opus

处理复杂推理，

haiku

处理简单任务，

sonnet

处理常规任务。

#	Scenario	Applicable Conditions	Core Strategy
1	Prompt Enhancement	Simple tasks, 1-2 steps	Optimize single-agent prompts, no splitting or team formation
2	Direct Skill Reuse	Tasks that can be fully resolved by a single Skill	After executing planning and Skill search, directly call the matching Skill without forming Agent Teams
3	Planning + Review	Medium/complex tasks (default)	Create plan → User confirmation → Parallel execution → Review and acceptance
4	Lead-Member	Clear team division required	Leader coordinates and assigns tasks, Members execute in parallel, collaborate via TaskList
5	Composite Orchestration	Complex tasks with no fixed pattern	Dynamically combine the above scenarios and switch strategies by phase

Model Division (applicable to all scenarios): Assign tasks via the

model

parameter of the Task tool based on task complexity —

opus

handles complex reasoning,

haiku

handles simple tasks,

sonnet

handles regular tasks.

协作模式

Collaboration Modes

模式	通信方式	适用场景	启动方式
Subagent	子agent → 主协调器单向汇报	并行独立任务	`Task` 工具
Agent Team	成员间可双向通信(SendMessage)	需要协作的复杂任务	`TeamCreate` + `Task(team_name)`

选择原则：任务间无依赖用Subagent（简单高效），任务间需要协调用Agent Team（功能更强但成本更高）。

Mode	Communication Method	Applicable Scenarios	Initiation Method
Subagent	One-way reporting from sub-agent to main coordinator	Parallel independent tasks	`Task` tool
Agent Team	Two-way communication between members (SendMessage)	Complex tasks requiring collaboration	`TeamCreate` + `Task(team_name)`

Selection Principle: Use Subagent for tasks without dependencies (simple and efficient), use Agent Team for tasks requiring coordination (more powerful but higher cost).

6阶段工作流（含强制规划和Skill搜索）

6-Phase Workflow (Including Mandatory Planning and Skill Search)

重要说明：阶段0和阶段1是所有场景的强制前置步骤，场景选择（1-5）只影响阶段2-5的执行方式。

Important Note: Phase 0 and Phase 1 are mandatory pre-steps for all scenarios; scenario selection (1-5) only affects the execution method of Phases 2-5.

阶段0：规划准备（Planning Setup）【硬性标准 - 所有场景必经】

Phase 0: Planning Setup [Hard Standard - Mandatory for All Scenarios]

使用 Skill 工具调用 planning-with-files：

Skill(skill="planning-with-files")

这将在项目目录创建三个核心文件：

```
task_plan.md
```
- 任务计划和阶段追踪
```
findings.md
```
- 研究发现和知识积累
```
progress.md
```
- 执行日志和进度记录

关键规则（规划文件创建后遵循）：

每个阶段开始前读取task_plan.md，完成后更新状态
每2次搜索/浏览操作后立即保存发现到findings.md
所有错误必须记录到task_plan.md的"Errors Encountered"表格
3次失败后升级给用户

铁律：没有task_plan.md就不能开始执行。这是Manus工作流的核心，确保上下文持久化。

Call the planning-with-files Skill via the Skill tool:

Skill(skill="planning-with-files")

This will create three core files in the project directory:

```
task_plan.md
```
- Task plan and phase tracking
```
findings.md
```
- Research findings and knowledge accumulation
```
progress.md
```
- Execution logs and progress records

Key Rules (to be followed after planning files are created):

Read task_plan.md before starting each phase, and update the status upon completion
Immediately save findings to findings.md after every 2 search/browse operations
All errors must be recorded in the "Errors Encountered" table in task_plan.md
Escalate to the user after 3 failures

Iron Rule: Execution cannot start without task_plan.md. This is the core of the Manus workflow, ensuring context persistence.

阶段1：任务分析 + Skill发现（Discovery）【硬性标准 - 所有场景必经】

Phase 1: Task Analysis + Skill Discovery [Hard Standard - Mandatory for All Scenarios]

先质疑再执行：

需求不合理时主动挑战假设，建议更好的方案
区分"现在必须做"和"以后再说"，排除非核心范围
任务太大时建议更聪明的起点

输出任务总览：

字段	内容
任务目标	[一句话描述]
预期结果	[具体交付物]
验收标准	[可量化的通过条件]
范围界定	[must-have vs add-later]
预计Agent数	[N个，建议≤5]
选定场景	[场景编号+名称]
协作模式	[Subagent/Agent Team]

Skill完整回退链（强制执行，不可跳过）：

对每个子任务执行以下3步fallback chain：

本地Skill扫描：
- 读取system-reminder中的"available skills"列表
- 提取每个skill的名称和触发词/描述
- 将子任务关键词与skill触发词比对
- 匹配成功 → 标注
```
[Skill: skill-name]
```
  ，进入阶段2直接调用
外部Skill搜索（本地无匹配时）：
- 使用 Skill 工具调用 find-skills：
```
Skill(skill="find-skills", args="子任务关键词")
```
- 搜索到 → 向用户推荐：
```
npx skills add <owner/repo@skill-name> -g -y
```
- 用户确认安装 → 标注新skill，进入阶段2调用
- 用户拒绝 → 继续第3步
通用Subagent回退（外部也无匹配时）：
- 该角色改用
```
Task
```
  工具生成通用subagent
- 在团队蓝图中标注
```
[Type: general-purpose]
```

铁律：这3步必须全部执行完才能进入阶段2。不允许跳过find-skills搜索。

Question before execution:

Proactively challenge assumptions when requirements are unreasonable, and suggest better solutions
Distinguish between "must-do now" and "can-do later", and exclude non-core scope
Suggest a smarter starting point when the task is too large

Output task overview:

Field	Content
Task Objective	[One-sentence description]
Expected Outcome	[Specific deliverables]
Acceptance Criteria	[Quantifiable passing conditions]
Scope Definition	[must-have vs add-later]
Estimated Number of Agents	[N, recommended ≤5]
Selected Scenario	[Scenario number + name]
Collaboration Mode	[Subagent/Agent Team]

Complete Skill Fallback Chain (Mandatory Execution, Cannot Be Skipped):

Execute the following 3 fallback steps for each subtask:

Local Skill Scan:
- Read the "available skills" list in system-reminder
- Extract the name and trigger words/description of each skill
- Compare subtask keywords with skill trigger words
- If matched → Mark
```
[Skill: skill-name]
```
  , proceed to Phase 2 for direct invocation
External Skill Search (when no local match is found):
- Call find-skills via the Skill tool:
```
Skill(skill="find-skills", args="subtask keywords")
```
- If found → Recommend to the user:
```
npx skills add <owner/repo@skill-name> -g -y
```
- If user confirms installation → Mark the new skill, proceed to Phase 2 for invocation
- If user refuses → Proceed to Step 3
General Subagent Fallback (when no external match is found):
- Use the
```
Task
```
  tool to generate a general-purpose subagent for this role
- Mark
```
[Type: general-purpose]
```
  in the team blueprint

Iron Rule: All 3 steps must be completed before entering Phase 2. Skipping the find-skills search is not allowed.

阶段2：团队组建

Phase 2: Team Formation

输出团队蓝图：

编号	角色	职责	模型	subagent_type	Skill/Type
1	[角色名]	[具体职责]	[opus/sonnet/haiku]	[agent类型]	[Skill: name] 或 [Type: general-purpose]

说明：最后一列标注该角色使用的Skill名称（阶段1已匹配）或通用类型（fallback）。

Output team blueprint:

Number	Role	Responsibility	Model	subagent_type	Skill/Type
1	[Role Name]	[Specific responsibilities]	[opus/sonnet/haiku]	[Agent type]	[Skill: name] or [Type: general-purpose]

Note: The last column indicates the Skill name used by this role (matched in Phase 1) or general type (fallback).

阶段3：并行执行

Phase 3: Parallel Execution

Skill任务：用
```
Skill
```
工具调用本地已安装的skill →
```
Skill(skill="skill-name", args="任务描述")
```
通用任务：用
```
Task
```
工具生成subagent，独立任务并行启动，有依赖的按序执行
混合编排时skill和subagent可并行运行

每个agent/skill完成后汇报：

✅ [角色名] 完成: [一句话结果]

遇到问题时给用户选项，而不是自己默默选一个

Agent → Skill 委派（子agent调用skill的3种模式）：

general-purpose

类型的subagent拥有所有工具权限，包括

Skill

工具。

模式	流程	适用场景
协调器直调	协调器 → `Skill(skill="name")` → 结果	单步Skill任务，无需并行
委派式调用	协调器 → `Task(prompt="请使用 /skill-name 完成 X")` → subagent → `Skill` → 汇报	并行多个Skill，或Skill耗时较长
团队成员调用	`TeamCreate` → 分配任务 → member → `Skill` → `SendMessage` 汇报	需要成员间协调的复杂任务

委派式调用关键点：Task prompt中写明要调用的Skill名称和参数，subagent会自动识别并调用。

Skill Tasks: Call locally installed skills via the Skill tool →
```
Skill(skill="skill-name", args="task description")
```
General Tasks: Use the
```
Task
```
tool to generate subagents; start independent tasks in parallel, and execute dependent tasks in sequence
Skills and subagents can run in parallel during hybrid orchestration

Report after each agent/skill completes:

✅ [Role Name] Completed: [One-sentence result]

Provide options to the user when encountering problems instead of making decisions silently

Agent → Skill Delegation (3 Modes for Subagents Calling Skills):

General-purpose subagents have access to all tools, including the Skill tool.

Mode	Process	Applicable Scenarios
Direct Call by Coordinator	Coordinator → `Skill(skill="name")` → Result	Single-step Skill tasks that do not require parallel execution
Delegated Call	Coordinator → `Task(prompt="Please use /skill-name to complete X")` → Subagent → `Skill` → Report	Multiple Skills executed in parallel, or time-consuming Skills
Team Member Call	`TeamCreate` → Assign tasks → Member → `Skill` → Report via `SendMessage`	Complex tasks requiring coordination between members

Key Point for Delegated Call: Clearly specify the Skill name and parameters in the Task prompt, and the subagent will automatically recognize and invoke it.

阶段4：质量把关 & 产品打磨

Phase 4: Quality Gate & Product Polishing

验收检查：对照阶段1的验收标准逐项检查。

产品打磨（不仅功能完整，更要用户体验优秀）：

边界处理：异常输入、空值、极端情况是否覆盖
专业度：命名规范、代码风格、错误提示是否友好
完整性：文档、配置说明、使用示例是否齐全

全部通过 → 进入阶段5。不通过 → 打回修改，最多2轮，仍不通过则通知用户人工介入。

Acceptance Check: Check item by item against the acceptance criteria defined in Phase 1.

Product Polishing (Not only functionally complete, but also excellent in user experience):

Boundary Handling: Whether abnormal inputs, null values, and extreme cases are covered
Professionalism: Whether naming conventions, code style, and error prompts are user-friendly
Completeness: Whether documents, configuration instructions, and usage examples are complete

If all checks pass → Proceed to Phase 5. If not → Send back for revision, maximum 2 rounds; if still not passing, notify the user for manual intervention.

阶段5：结果交付 & 部署移交

Phase 5: Result Delivery & Deployment Handover

输出执行报告：

项目	内容
总任务数	X个，成功Y个，失败Z个
各Agent结果	[角色]: [状态] - [关键产出]
汇总结论	[综合所有结果的最终结论]
后续建议	[当前未覆盖但值得做的改进方向]

部署移交（按需提供）：

运行方式：启动命令、环境要求、配置说明
验证步骤：用户可自行验证的操作清单
已知限制：当前版本的边界和约束

Output execution report:

Item	Content
Total Tasks	X tasks, Y succeeded, Z failed
Results of Each Agent	[Role]: [Status] - [Key Output]
Summary Conclusion	[Final conclusion integrating all results]
Follow-up Recommendations	[Improvement directions not covered currently but worth implementing]

Deployment Handover (Provided On Demand):

Operation Method: Startup commands, environment requirements, configuration instructions
Verification Steps: List of operations that users can perform for self-verification
Known Limitations: Boundaries and constraints of the current version

执行底线

Execution Bottom Line

【硬性标准】： 0. 强制使用 planning-with-files：任何复杂任务必须先调用

Skill(skill="planning-with-files")

创建 task_plan.md、findings.md、progress.md

强制执行Skill完整回退链：本地扫描 →
```
Skill(skill="find-skills", args="...")
```
搜索 → 通用subagent，不允许跳过任何步骤

【其他原则】： 2. 先目标，后组织结构——任务不清晰时先澄清，再决定是否组建团队 3. 队伍规模由任务复杂度决定，并行Agent建议不超过5个 4. 关键里程碑必须有质量闸门和回滚点 5. 不默认任何外部工具可用，执行前先验证（含find-skills） 6. 浏览器多窗口默认互相独立，不共享上下文 7. 成本只是约束，不是固定承诺——不做不切实际的成本预估 8. 危险操作、大规模变更必须先获得用户确认

[Hard Standards]: 0. Mandatory Use of planning-with-files: For any complex task, must first call

Skill(skill="planning-with-files")

to create task_plan.md, findings.md, progress.md

Mandatory Execution of Complete Skill Fallback Chain: Local scan →
```
Skill(skill="find-skills", args="...")
```
search → General subagent; no steps can be skipped

[Other Principles]: 2. First clarify the goal, then define the organizational structure — clarify the task first when it is unclear, then decide whether to form a team 3. Team size is determined by task complexity; the number of parallel agents is recommended to be no more than 5 4. Key milestones must have quality gates and rollback points 5. Do not assume any external tools are available; verify before execution (including find-skills) 6. Browser windows are independent by default and do not share context 7. Cost is only a constraint, not a fixed commitment — do not make unrealistic cost estimates 8. Dangerous operations and large-scale changes must be confirmed by the user first

故障处理

Fault Handling

故障类型	处理策略
Agent执行失败	通知用户，提供重试/跳过/终止选项
Skill不可用	按回退链降级：本地Skill → find-skills → 通用subagent
模型超时	调整任务复杂度或拆分为更小的子任务
质量不达标	打回修改最多2轮，仍不通过则人工介入
上下文溢出	拆分为更小的子任务，分批执行

Fault Type	Handling Strategy
Agent Execution Failure	Notify the user, and provide options for retry/skip/termination
Skill Unavailable	Degrade according to the fallback chain: Local Skill → find-skills → General subagent
Model Timeout	Adjust task complexity or split into smaller subtasks
Quality Not Up to Standard	Send back for revision up to 2 rounds; if still not passing, notify the user for manual intervention
Context Overflow	Split into smaller subtasks and execute in batches