用 Claude Code 构建 AI 团队：多 Agent 协作完全指南

如何让多个 AI Agent 像真正的团队一样协作？本文介绍全新的 Team Skill，一个统一入口搞定团队全生命周期管理。

为什么需要 Team Skill？

复杂任务需要多种角色配合：设计师出方案、开发者写代码、测试员验证。如果让单个 AI 承担所有角色，容易顾此失彼。

Team Skill 的核心价值：

🤖 多角色协作 - 每个 Agent 专注一个角色
🎯 显式任务分配 - Agent 等待指令后才工作，禁止自动执行
🔄 任务依赖管理 - 自动处理执行顺序
📊 实时状态监控 - 一目了然看进度
🛠️ 动态任务调整 - 运行中增删改任务
✅ 配置自动验证 - 防止循环依赖等问题

快速开始

安装

将 team/ 目录复制到 ~/.claude/skills/ 即可：

mkdir -p ~/.claude/skills
cp -r team ~/.claude/skills/

创建团队（需要明确目标）

关键原则：AI 必须先询问目标，不能假设任务内容！

用户：创建一个团队，角色是 architect developer tester

❌ 错误做法（AI 直接创建任务）：
   AI：自动创建"架构设计"、"代码开发"、"测试"任务
   → AI 不知道要开发什么，任务可能是错的！

✅ 正确做法（先询问目标）：
   AI："请描述你们要开发什么？具体需求是什么？"

用户："一个电商订单管理系统，需要设计架构、开发后端API、测试功能"

AI："明白了，我设计以下任务：
      - task-1: 设计电商订单管理系统架构 → architect
      - task-2: 开发后端订单API → developer（依赖task-1）
      - task-3: 测试系统功能 → tester（依赖task-2）
      确认吗？"

用户："确认"

AI：
  ✅ TeamCreate: "ecommerce-order-system"
  ✅ TaskCreate: 设计电商订单管理系统架构 → architect
  ✅ TaskCreate: 开发后端订单API → developer
  ✅ TaskCreate: 测试系统功能 → tester
  ✅ Spawn: architect, developer, tester

  📨 发送给 architect: "请开始执行任务 task-1"
  📨 发送给 developer: "请等待，task-2 依赖 task-1"
  📨 发送给 tester: "请等待，task-3 依赖 task-2"

重要：

AI 必须先询问目标 - 不能基于角色名称假设任务
任务设计必须基于用户明确的需求 - 用户确认后才创建
Agent 不会自动工作 - 启动后进入空闲等待状态，必须收到明确指令后才工作

常用命令

你说	Claude 做
"创建团队，角色是 frontend backend tester"	初始化全栈团队
"开始任务 task-1" 或 "designer 开始工作"	显式分配任务（关键！）
"团队状态"	查看进度报告
"添加任务 '性能优化' 分配给 developer"	动态添加任务
"验证团队配置"	检查循环依赖等问题
"关闭团队"	优雅结束协作

核心功能详解

一、INIT - 团队初始化

触发方式： 说"创建团队"、"init team"、"新建团队"

关键原则：必须先明确目标，再创建任务！

❌ 错误做法：AI 假设任务内容

用户："创建团队，角色是 architect developer"
AI：自动创建"架构设计"、"代码开发"任务
→ AI 不知道要开发什么，任务可能是错误的！

✅ 正确做法：AI 询问具体目标

用户："创建团队，角色是 architect developer"
AI："请描述你们要开发什么？具体需求是什么？"
用户："一个电商订单管理系统，需要..."
AI：基于描述设计具体任务，用户确认后创建

1. 角色自定义（空格分隔）

用户：创建一个数据分析团队，角色是 data-engineer ml-engineer data-scientist

Claude：
  角色解析：["data-engineer", "ml-engineer", "data-scientist"]

  "请描述你们要开发什么？例如：
   - 要处理什么数据？
   - 目标是什么？
   - 有什么特殊要求？"

用户："我们需要处理用户行为日志，分析产品转化漏斗，要求实时报表"

Claude：
  基于描述设计任务：
  - task-1: 设计数据采集和清洗流程 → data-engineer
  - task-2: 构建转化漏斗分析模型 → ml-engineer
  - task-3: 验证分析结果并生成报表 → data-scientist

  "请确认任务设计：...
   确认吗？"

用户："确认"

Claude：创建团队并设置依赖

支持任意角色名称，不再局限于预设选项：

designer developer tester - 标准团队
frontend backend tester - 全栈团队
ios android flutter qa - 移动端团队
pm ui dev devops - 产品运维团队
architect backend tester - 后端系统开发团队

2. 智能流水线生成

角色组合	自动生成的依赖关系
`designer developer tester`	设计 → 开发 → 测试
`frontend backend tester`	前端 ∥ 后端 → 测试（并行）
`architect developer`	架构 → 开发
`developer reviewer`	开发 → 审查
未匹配的组合	按顺序串行执行

并行任务示例：

frontend ──┐
           ├──→ tester
backend ───┘

二、ASSIGN - 显式任务分配（关键！）

触发方式： Agent 签到后，或用户说"开始工作"、"分配任务"

为什么必须显式分配？

❌ 错误做法：
   Agent 启动后自动读取任务、自动开始写代码
   → Agent 可能误解任务
   → Agent 可能在不该工作时工作
   → 无法协调多个 Agent

✅ 正确做法：
   Agent 启动后等待指令
   Team Lead 明确说："designer 开始执行任务 task-1"
   → Agent 确认收到指令
   → Agent 检查依赖后才开始工作
   → 完全可控的协作流程

分配流程：

Step 1: Agent 签到
  designer: "我已上线，等待任务分配"

Step 2: Team Lead 检查依赖
  TaskList → TaskGet
  确认 task-1 无依赖，可以开始

Step 3: Team Lead 显式分配
  SendMessage → designer: "请开始执行任务 task-1: 设计方案"

Step 4: Agent 确认并开始
  designer: "收到，开始执行 task-1"
  TaskUpdate(task-1, in_progress)
  开始设计工作

等待状态的 Agent：

Team Lead 发送给 developer: "请等待，task-2 依赖 task-1"
developer 回复: "收到，等待 task-1 完成"
→ developer 保持空闲，不主动工作

三、STATUS - 状态报告

触发方式： 说"团队状态"、"进度报告"

输出示例：

==================================================
团队 "user-auth" 状态报告
==================================================

整体进度: [████████░░] 80% (4/5 完成)

进行中:
  🔄 task-4: 代码审查 → @reviewer

待处理:
  ⏳ task-5: 部署上线 → @devops (blocked by task-4)

已完成:
  ✅ task-1: 设计方案 → @designer
  ✅ task-2: 实现功能 → @developer
  ✅ task-3: 编写测试 → @tester

Agent 状态:
  @designer   : 空闲
  @developer  : 空闲
  @tester     : 空闲
  @reviewer   : 工作中
  @devops     : 等待中
==================================================

自动检测：

✅ 任务完成统计
⏳ 阻塞任务识别
🔄 Agent 工作状态
📊 可视化进度条

四、TASK-MANAGE - 动态任务管理

运行中可以灵活调整任务，无需重启团队。

添加任务

用户：给 user-auth 团队添加一个 "性能优化" 任务，分配给 developer，依赖 task-2

Claude：
  ✅ 已添加 task-6: 性能优化
  负责人: @developer
  依赖: task-2
  当前状态: 等待依赖完成

自动分配任务 ID： 查找现有最大编号 + 1

删除任务

用户：删除任务 task-5

Claude：
  ⚠️ 检查依赖...
  ✅ 没有其他任务依赖 task-5
  ✅ 已删除 task-5

安全检查： 如果被其他任务依赖，会阻止删除并提示。

修改任务

用户：将 task-3 的负责人改为 senior-tester，状态设为 completed

Claude：
  ✅ 已更新 task-3
  新负责人: @senior-tester
  新状态: completed
  🔔 通知下游 agent: task-4 的依赖已满足

重新分配

用户：把 task-2 转交给 reviewer

Claude：
  ✅ task-2 已重新分配给 @reviewer
  📨 已通知 reviewer 有新任务

列出所有任务

用户：列出所有任务

Claude：
  🔄 task-4: 代码审查 → @reviewer
  ⏳ task-5: 部署上线 → @devops (等待: task-4)
  ✅ task-1: 设计方案 → @designer
  ✅ task-2: 实现功能 → @developer
  ✅ task-3: 编写测试 → @tester

五、VALIDATE - 配置验证

触发方式： 说"验证团队"、"检查配置"

自动检查项：

✅ 任务 ID 唯一性 - 检测重复 ID
✅ 依赖存在性 - 检查 blocker 是否存在
✅ 循环依赖检测 - DFS 算法检测死锁
⚠️ Owner 有效性 - 检查负责人是否在团队中
⚠️ 孤立任务检测 - 找出无依赖也无被依赖的任务

循环依赖检测示例：

❌ 检测到循环依赖:
  task-1 → task-2 → task-3 → task-1

💡 解决方案:
  1. 打破 task-3 → task-1 的依赖
  2. 或重新设计任务结构

六、SHUTDOWN - 优雅关闭

触发方式： 说"关闭团队"、"结束团队"

关闭流程：

Step 1: 检查未完成任务
  → 发现 2 个未完成任务
  → 询问：强制关闭 / 取消

Step 2: 通知所有 Agent
  → 发送 shutdown_request
  → 等待确认（超时 2 分钟）

Step 3: 清理资源
  → TeamDelete

Step 4: 输出总结
  ✅ 已完成: 5
  ⏳ 未完成: 2
  👥 团队成员: 4

核心协作协议

Team Lead（AI）行为准则

作为 Team Lead，AI 必须先明确目标再创建任务：

步骤	必做动作
📝 创建团队前	询问具体目标 - 用户必须描述要做什么
🔍 设计任务时	基于目标设计 - 每个任务必须结合具体需求
✅ 创建任务前	用户确认 - 展示任务设计，用户确认后才创建
📋 分配任务时	明确指令 - 告诉 Agent 具体执行哪个任务

Agent 行为准则

每个被 spawn 的 Agent 必须遵守：

时机	必做动作
🚀 启动时	TaskList → SendMessage 签到 → 等待明确指令
📋 收到指令后	确认任务分配 → TaskGet 检查依赖 → 开始工作
📝 工作中	每 5-10 分钟汇报进度，遇阻立即请求协助
✅ 完成后	TaskUpdate(completed) → 通知 lead → 通知下游

关键规则

-1. 必须先明确目标（MOST CRITICAL）

❌ 严重错误：AI 基于角色名称假设任务内容
   用户："创建团队，角色是 architect developer"
   AI：自动创建"架构设计"、"代码开发"任务
   → AI 不知道要开发什么系统！

✅ 正确做法：AI 先询问目标
   用户："创建团队，角色是 architect developer"
   AI："请描述你们要开发什么？具体需求是什么？"
   用户："一个电商订单管理系统..."
   AI：基于描述设计具体任务，用户确认后创建

关键区别：
   - 任务必须基于用户明确的需求
   - 禁止基于角色名称假设任务（如"架构设计"、"编写代码"）
   - 用户确认任务设计后，才执行创建

0. 绝对禁止自动工作（CRITICAL）

❌ 严重错误：Agent 启动后自动读取任务、自动写代码
   designer 启动后："我看到 task-1 分配给我，开始设计..."

✅ 正确做法：等待 Team Lead 明确指令
   designer 启动后："我已上线，等待任务分配"
   Team Lead: "designer 请开始执行 task-1"
   designer: "收到，开始执行 task-1"

关键区别：
   - Agent 绝不主动假设知道该做什么
   - 必须收到 "开始任务 X" 明确指令后才工作
   - 未收到指令时保持空闲状态

1. 绝对禁止抢跑

❌ 错误：依赖未完成就开始工作
✅ 正确：检查所有 blocker 为 completed 后才开工

2. 完成后必须通知

✅ TaskUpdate 状态改为 completed
✅ SendMessage 通知 team lead
✅ SendMessage 通知所有下游 agent

3. 阻塞时主动汇报

⏳ 发现依赖未完成时：
   → 通知 team lead 被阻塞
   → 通知 blocker 的 owner
   → 等待（不做任何工作）

完整工作流示例

场景：开发用户认证系统

[T=0] 创建团队
─────────────────────────────
用户：创建团队 "auth-service"，角色是 designer developer tester

Claude：
  ✅ TeamCreate: auth-service
  ✅ TaskCreate: 设计方案 (designer)
  ✅ TaskCreate: 实现功能 (developer) ← 依赖设计方案
  ✅ TaskCreate: 编写测试 (tester) ← 依赖实现功能
  ✅ Spawn: designer, developer, tester

[T=1] Agent 上线（等待状态）
─────────────────────────────
designer:   "我已上线，等待任务分配"
developer:  "我已上线，等待任务分配"
tester:     "我已上线，等待任务分配"

⚠️ 注意：Agent 不会自动开始工作！

[T=2] 显式分配任务（关键步骤！）
─────────────────────────────
用户：designer 开始工作

Claude（Team Lead）：
  📨 发送给 designer: "请开始执行任务 task-1: 设计方案"
  📨 发送给 developer: "请等待，task-2 依赖 task-1"
  📨 发送给 tester:    "请等待，task-3 依赖 task-2"

designer: "收到，开始执行 task-1"
          TaskUpdate(task-1, in_progress)

developer: "收到，等待 task-1 完成"
           （保持空闲，不主动工作）

tester: "收到，等待 task-2 完成"
        （保持空闲，不主动工作）

[T=12] 设计完成
─────────────────────────────
designer: "✅ task-1 完成，产出：UI设计稿"
         └─► 通知 Team Lead

用户：developer 开始工作

Claude（Team Lead）：
  📨 发送给 developer: "task-1 已完成，请开始执行 task-2"

developer: "收到，依赖已满足，开始开发"
          TaskUpdate(task-2, in_progress)

[T=25] 开发完成
─────────────────────────────
developer: "✅ task-2 完成，产出：认证API"
         └─► 通知 Team Lead

用户：tester 开始工作

Claude（Team Lead）：
  📨 发送给 tester: "task-2 已完成，请开始执行 task-3"

tester: "收到，依赖已满足，开始测试"
       TaskUpdate(task-3, in_progress)

[T=32] 测试完成
─────────────────────────────
tester: "✅ task-3 完成，所有测试通过"
       └─► 通知 Team Lead

[T=33] 关闭团队
─────────────────────────────
用户：关闭团队

Claude：
  ✅ 所有任务已完成
  ✅ 通知所有 Agent
  ✅ TeamDelete
  📊 总结：3个任务，3个Agent，耗时33分钟

关键对比：

❌ 旧版（自动工作）
  Agent 启动 → 自动找任务 → 自动开始
  → 可能误解任务
  → 无法协调多个 Agent

✅ 新版（显式分配）
  Agent 启动 → 等待指令 → 收到明确指令后工作
  → 完全可控
  → 精确协调执行顺序

技术实现

Team Skill 完全基于 Claude Code 原生工具，无需任何外部依赖：

工具	用途
`TeamCreate`	创建团队实例
`TaskCreate`	创建任务
`TaskUpdate`	更新状态、设置依赖、分配 owner
`TaskList` / `TaskGet`	查询任务状态
`SendMessage`	Agent 间通信
`AskUserQuestion`	交互式收集信息

所有逻辑嵌入 SKILL.md，包括：

角色解析算法（空格分割）
任务 ID 生成规则
流水线生成决策表
循环依赖检测 DFS 算法
进度条计算公式

最佳实践

1. 角色命名建议

使用有意义的角色名：

✅ 好：frontend, backend, api-gateway, data-processor
❌ 差：a, b, c, agent1, agent2

2. 任务粒度控制

太粗：developer 负责 "实现整个系统"（无法并行）
太细：100个 1分钟任务（协调开销大）
✅ 正好：5-10个 10-30分钟任务

3. 依赖设计原则

✅ 推荐：线性或树形结构
  A → B → C
      ↘ D

❌ 避免：复杂网状依赖
  A ↔ B ↔ C ↔ A（循环）

4. 定期状态检查

Team Lead 每 5-10 分钟：
  → "团队状态"
  → 关注被阻塞的任务
  → 及时协调资源

对比：旧版 vs 新版

特性	旧版（3个独立skill）	新版（统一team skill）
入口	team-init / team-protocol / team-checkin	一个 `team` 搞定所有
任务分配	Agent 自动开始（易误解任务）	✅ 显式分配（完全可控）
角色定义	预设选项，不够灵活	空格分隔，任意角色
动态任务	❌ 不支持	✅ 增删改查全支持
状态监控	❌ 无	✅ 可视化进度报告
配置验证	❌ 手动检查	✅ 自动验证，含循环检测
外部依赖	可选 Python 脚本	✅ 零依赖，纯提示词实现
使用难度	需要了解3个skill的区别	✅ 自然语言即可

结语

Team Skill 将 Claude Code 的多 Agent 协作能力提升到了新水平：

🎯 统一入口 - 一个 skill 管所有
🎯 显式控制 - Agent 等待指令后才工作，完全可控
🎨 灵活定义 - 任意角色，任意流水线
🔄 动态管理 - 运行中调整任务
🛡️ 可靠验证 - 自动预防配置错误
🚀 零依赖 - 开箱即用

最重要的改进：Agent 不再自动工作！

之前：Agent 启动 → 自动找任务 → 自动写代码
       → 可能做错误的事情

现在：Agent 启动 → 等待明确指令 → 确认后工作
       → 完全可控，精确执行

现在，你可以像管理真实团队一样管理 AI Agent 了！

📁 Skill 位置：~/.claude/skills/team/

📖 完整文档：team/SKILL.md

💡 示例参考：team/references/examples.md

目录CONTENT

用 Claude Code 构建 AI 团队：多 Agent 协作完全指南

用 Claude Code 构建 AI 团队：多 Agent 协作完全指南

为什么需要 Team Skill？

快速开始

安装

创建团队（需要明确目标）

常用命令

核心功能详解

一、INIT - 团队初始化

关键原则：必须先明确目标，再创建任务！

1. 角色自定义（空格分隔）

2. 智能流水线生成

二、ASSIGN - 显式任务分配（关键！）

三、STATUS - 状态报告

四、TASK-MANAGE - 动态任务管理

添加任务

删除任务

修改任务

重新分配

列出所有任务

五、VALIDATE - 配置验证

六、SHUTDOWN - 优雅关闭

核心协作协议

Team Lead（AI）行为准则

Agent 行为准则

关键规则

完整工作流示例

场景：开发用户认证系统

技术实现

最佳实践

1. 角色命名建议

2. 任务粒度控制

3. 依赖设计原则

4. 定期状态检查

对比：旧版 vs 新版

结语

评论区