agents24 agent-teams 插件：多智能体团队协作的任务协调策略——任务分解、依赖图设计与负载均衡实战

本篇基于 agents24/agents 仓库中 agent-teams 插件的 task-coordination-strategies 技能文档，系统讲解如何将复杂任务分解为可并行的工作单元、如何设计基于 blockedBy/blocks 的任务依赖图、如何编写包含验收标准与文件所有权边界的任务描述，以及如何监控并再平衡团队成员间的工作负载。读完后，你能够掌握一套完整的多智能体（agent team）任务拆解—派发—监控—收敛的协调方法论，并知道如何借助插件提供的 /team-feature、/team-delegate、/team-status 等命令将其落地到 Claude Code 的 Agent Teams 工作流中。

技能定位与适用场景

task-coordination-strategies 是 agent-teams 插件六项技能之一，其定位是：为智能体团队分解可并行化单元、设计依赖图、撰写有效的任务描述并跨团队监控工作负载。README 将其概括为"Task Coordination — Dependency-aware task management with workload balancing"，即依赖感知的任务管理与负载平衡。

技能原文档列出的适用场景包括：

• 将复杂任务拆解为可并行执行的单元
• 设计任务依赖关系（blockedBy/blocks）
• 撰写带清晰验收标准的任务描述
• 监控团队负载并再平衡
• 在多任务工作流中识别关键路径（critical path）

这套技能服务于插件中的 team-lead 角色——它是团队编排器，负责把复杂工程任务分解为带文件所有权边界的并行工作流。从 team-lead.md 的 "Dependency Management" 能力定义可以看到，技能中的策略正是该 Agent 的内置行为：构建 blockedBy/blocks 依赖图、最小化依赖链深度、识别并消除循环依赖、沿关键路径排序任务。

运行前提：该插件依赖 Claude Code 的实验性 Agent Teams 功能，需要先启用环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，并在 ~/.claude/settings.json 中配置显示模式（tmux、iterm2 或默认的 in-process）。安装方式为添加市场后执行 /plugin install agent-teams@claude-code-workflows（详见 插件 README）。

任务分解策略：四种切分维度

技能文档给出四种把复杂工作拆分为并行单元的策略，各自对应不同的适用架构形态：

按架构层切分（By Layer）

按架构层级拆分工作：前端组件、后端 API 端点、数据库迁移/模型、测试套件。最适合：全栈功能、垂直切片场景。

按功能组件切分（By Component）

按功能模块拆分：认证模块、用户资料模块、通知模块。最适合：微服务、模块化架构。

按横切关注点切分（By Concern）

按横切关注点拆分：安全审查、性能审查、架构审查。最适合：代码评审、安全审计类任务。

按文件所有权切分（By File Ownership）

按文件/目录边界拆分，例如：

src/components/ — Implementer 1
src/api/        — Implementer 2
src/utils/      — Implementer 3

最适合：并行实现、避免合并冲突。这是插件中并行功能开发的核心手段，/team-feature 命令的分解阶段就要求"每个 stream 拥有独占的文件所有权（无重叠文件）"。

两个完整分解示例

技能的 references/task-decomposition.md 给出了两个可直接套用的完整示例，展示了"垂直切片"与"水平分层"两种切法如何落到具体文件上：

示例 1：用户认证功能（垂直切片）

添加邮箱/密码认证，含登录、注册与个人资料页。拆分为三条流：

流	负责	拥有文件	依赖
Stream 1：登录流	implementer-1	src/pages/login.tsx、src/api/login.ts、tests/login.test.ts	依赖共享类型
Stream 2：注册流	implementer-2	src/pages/register.tsx、src/api/register.ts、tests/register.test.ts	依赖共享类型
Stream 3：共享基础设施	implementer-3	src/types/auth.ts、src/middleware/auth.ts、src/utils/jwt.ts	无（其他流依赖它）

依赖图为：Stream 3 (types/middleware) → Stream 1 (login) 且 → Stream 2 (registration)。两个业务流都从共享基础设施导入 AuthResponse 类型，但都不修改它——这正是"接口契约先行"的典型形态。

示例 2：Projects 资源的 REST CRUD API（按层切分）

流	负责	拥有文件	依赖
Stream 1：数据层	implementer-1	src/models/project.ts、src/migrations/add-projects.ts、src/repositories/project-repo.ts	无
Stream 2：业务逻辑	implementer-2	src/services/project-service.ts、src/validators/project-validator.ts	被 Stream 1 阻塞（需要 model/repository）
Stream 3：API 层	implementer-3	src/routes/projects.ts、src/controllers/project-controller.ts	被 Stream 2 阻塞（需要 service 层）

注意该示例中依赖链较深（1 → 2 → 3），这正引出了下一节的依赖图设计原则：层级切分天然产生串行链，应评估是否可以通过接口契约（先定义类型与服务接口）将部分依赖"前置化解"，让上层与下层并行开工。

依赖图设计：原则、模式与 blockedBy/blocks

四条设计原则

技能文档给出的依赖图设计原则：

1. 最小化链深度——优先选择宽而浅的图，而非深链；
2. 识别关键路径——最长链决定最短完成时间；
3. 节制使用 blockedBy——只添加真正必需的依赖；
4. 避免循环依赖——A 阻塞 B、B 阻塞 A 就是死锁。

基本图模式

技能文档定义了三种基本模式：

独立型（并行度最高）：

Task A ─┐
Task B ─┼─→ Integration
Task C ─┘

顺序型（必要依赖）：

Task A → Task B → Task C

钻石型（混合）：

        ┌→ Task B ─┐
Task A ─┤          ├→ Task D
        └→ Task C ─┘

references/dependency-graphs.md 在此基础上补充了每种模式的权衡与两个进阶模式，并给出对应的 TaskCreate 依赖设置方式：

模式	并行度	风险	适用场景	依赖设置
完全独立	最大——所有任务同时运行	集成阶段才暴露不兼容	任务操作完全不相交的文件/模块	各任务无 blockedBy；集成任务被所有任务阻塞
顺序链	无	每步都是瓶颈，一处延迟级联放大	每个任务依赖前一个任务的产出（应尽量避免）	每个任务 blockedBy 前一个任务
钻石（共享基础）	B、C 在 A 完成后并行	A 是瓶颈；D 需等 B、C 全部完成	B、C 都需要 A 的产出（如共享类型）	B、C blockedBy A；D blockedBy B 和 C
Fork-Join（分阶段并行）	阶段内并行	阶段边界带来同步延迟	有天然阶段依赖的流程（构建→测试→部署）	阶段 2 的任务 blockedBy 阶段 1 的全部任务
流水线（双链流式）	两条并行链	两条链的实现路径可能分叉	从共同起点出发的两个独立特性分支	B、D blockedBy A；C blockedBy B；E blockedBy D

反模式与修复

同一参考文档还列出了三种必须规避的反模式：

• 循环依赖（死锁）：A → B → C → A ✗。修复：把共享依赖抽取为一个独立任务，让三者都依赖它；
• 无谓依赖：A → B → C 中 B 其实并不需要 A 的产出。修复：删除该 blockedBy 关系，让 B 独立运行；
• 星型瓶颈：A 分叉出 B、C、D、E 再汇入 F。若 A 很慢，全部下游都被拖累。修复：把 A 的工作并行化。

用 TaskCreate/TaskUpdate 表达依赖

技能文档给出了依赖关系的工具调用示例（对应 Claude Code Agent Teams 的任务工具）：

TaskCreate: { subject: "Build API endpoints" }         → Task #1
TaskCreate: { subject: "Build frontend components" }    → Task #2
TaskCreate: { subject: "Integration testing" }          → Task #3
TaskUpdate: { taskId: "3", addBlockedBy: ["1", "2"] }  → #3 waits for #1 and #2

这与 team-feature.md 命令中 Phase 4（Task Creation）的编排流程一一对应：先用 TaskCreate 为每个 work stream 建任务（subject 为流名，description 包含拥有文件、需求、接口契约、验收标准），再用 TaskUpdate 设置依赖流的 blockedBy 关系，最后用 TaskUpdate 将任务指派给 implementer（设置 owner）。也就是说，技能文档中的策略在执行层就是这条 TaskCreate → TaskUpdate(blockedBy) → TaskUpdate(owner) 的调用链。

任务描述最佳实践：六要素模板

技能文档要求每个任务描述都包含六个要素：

1. Objective（目标）——需要完成什么（1-2 句）；
2. Owned Files（拥有文件）——该队友可以修改的文件/目录的显式列表；
3. Requirements（需求）——期望的具体交付物或行为；
4. Interface Contracts（接口契约）——本工作如何与其他队友的工作衔接；
5. Acceptance Criteria（验收标准）——如何验证任务被正确完成；
6. Scope Boundaries（范围边界）——明确不在范围内的工作。

文档给出的完整模板以"构建用户认证 API 端点"为例：

## Objective
Build the user authentication API endpoints.

## Owned Files
- src/api/auth.ts
- src/api/middleware/auth-middleware.ts
- src/types/auth.ts (shared — read only, do not modify)

## Requirements
- POST /api/login — accepts email/password, returns JWT
- POST /api/register — creates new user, returns JWT
- GET /api/me — returns current user profile (requires auth)

## Interface Contract
- Import User type from src/types/auth.ts (owned by implementer-1)
- Export AuthResponse type for frontend consumption

## Acceptance Criteria
- All endpoints return proper HTTP status codes
- JWT tokens expire after 24 hours
- Passwords are hashed with bcrypt

## Out of Scope
- OAuth/social login
- Password reset flow
- Rate limiting

references/task-decomposition.md 还提供了一个更通用的参数化任务模板（## Task: {Stream Name} 下含 Objective / Owned Files / Requirements / Interface Contract / Acceptance Criteria / Out of Scope 六个小节，其中 Owned Files 采用"{file} — {purpose}"格式、验收标准使用 - [ ] 可勾选清单）。

为什么 Owned Files 与 Interface Contracts 如此重要？ 因为这直接对应插件执行层的两条硬性规则：

• team-lead.md 的 "File Ownership Rules"：一个文件只能有一个 owner；每个任务描述中显式列出拥有文件；共享边界处先定义契约（类型、API）再开工；若文件必须被多人触碰，则由 lead 持有并按顺序应用变更。
• team-implementer.md 的 "File Ownership Protocol"：只修改分配给自己的文件；绝不触碰共享文件（需要改就发消息给 team lead）；只在自己边界内新建文件；接口契约不可变（未经 lead 批准不得修改）；存疑时先问。

从源码结构看，任务描述中的"Owned Files"清单就是这些 Agent 行为约束的唯一输入来源——/team-feature 命令在 Phase 3 派生 implementer 时，正是把"owned files、interface contracts、implementation requirements"写进 spawn prompt（见 team-feature.md）。因此，任务描述写得不完整，等价于让实现 Agent 在模糊边界上自由发挥，冲突风险随之而来。

工作负载监控与再平衡

失衡信号识别

技能文档给出了一张失衡信号识别表：

信号	含义	应对动作
某队友空闲，其他人在忙	分配不均	重新分配待办任务
某队友卡在一个任务上	可能存在阻塞	主动询问、提供帮助
所有任务都被阻塞	依赖问题	优先解决关键路径
某队友任务量是其他人的 3 倍	过载	拆分任务或重新指派

再平衡五步

1. 调用 TaskList 评估当前状态；
2. 识别空闲或过载的队友；
3. 使用 TaskUpdate 重新分配任务；
4. 使用 SendMessage 通知受影响的队友；
5. 持续监控吞吐量是否改善。

工具层支撑：/team-status 与 /team-delegate

技能中的监控流程在插件的命令层有完整落地：

• /team-status：读取 ~/.claude/teams/{team-name}/config.json 并调用 TaskList，输出成员表（姓名、角色、状态）、任务表（ID、状态、负责人、主题）与总体进度百分比（如 Progress: 40% (2/5 completed)），支持 --tasks、--members、--json 过滤；
• /team-delegate：提供委派仪表盘与再平衡能力。其默认仪表盘列出未分配任务、各成员任务量（in_progress + pending 分列）、被阻塞任务（含阻塞源与 owner）以及自动生成的建议（如 "Assign #5 to implementer-3 (idle)"）。执行 --rebalance 时，命令会按明确阈值分析负载——0 个任务判定为 idle，3 个及以上判定为 overloaded——生成"Workload Analysis + Suggestions"报告，经用户确认后通过 TaskUpdate + SendMessage 执行迁移（见 team-delegate.md）。
• 指派与通信：--assign task-id=member-name 用 TaskUpdate 设置 owner 并用 SendMessage（type: "message"）通知成员；--message 用于向指定成员发送消息。

从 README 的最佳实践看，官方建议是"用 /team-status 定期巡检，负载不均时用 /team-delegate --rebalance"，与技能文档的再平衡五步构成"技能层方法论 + 命令层工具"的完整闭环。

端到端实战流程小结

将技能文档的策略串联起来，一次完整的团队协调流程如下：

1. 分析：理解特性范围，探索代码库找出需修改的文件、既有模式与集成点（team-feature.md Phase 1）；
2. 分解：选择上述四种切分维度之一（或混合），为每个 stream 确定独占文件所有权、定义接口契约、识别 blockedBy 依赖、平衡负载；可用 --plan-first 让用户在派生前审批分解方案；
3. 建图：用 TaskCreate 建任务，TaskUpdate 设置 blockedBy 与 owner；
4. 监控：周期性 TaskList / /team-status，对照失衡信号表识别问题；
5. 再平衡：/team-delegate --rebalance 生成建议并执行迁移，SendMessage 同步受影响成员；
6. 收敛：所有任务完成后执行构建与测试验证集成，创建修复任务分配给相应 implementer，最终向用户汇报并走 /team-shutdown 优雅关闭。

相关资源

• 技能主文档：SKILL.md
• 依赖图模式参考：dependency-graphs.md
• 任务分解示例参考：task-decomposition.md
• 配套技能：parallel-feature-development（文件所有权策略与冲突规避）、team-composition-patterns（团队规模与 Agent 类型选择）、team-communication-protocols（消息类型选择与计划审批流程）
• 角色定义：team-lead、team-implementer
• 命令：team-feature、team-delegate、team-status
• 插件总览与安装：plugins/agent-teams/README.md

适用前提：以上内容基于仓库中 agent-teams 插件 v1.0.2 版本的技能文档，依赖 Claude Code 实验性 Agent Teams 功能（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）及其 TaskCreate/TaskList/TaskGet/TaskUpdate/SendMessage/TeamCreate/TeamDelete/Agent 等工具，实际可用性以 Claude Code 当前版本对实验特性的支持为准。