本节目标

  1. 理解 Sub-agent 与 Agent Team 的本质区别（星型拓扑 vs 网状拓扑）

  2. 掌握 Agent Team 三大通信原语：TaskCreate、TaskUpdate、SendMessage

  3. 能设计 Lead Agent 角色并配置并发锁机制

  4. 能搭建 4 Agent 开发团队（Planner -> Coder -> Reviewer -> Debugger）并防止无限循环

核心知识点

1. Sub-agent vs Agent Team：不只是名字不同

很多开发者把 Sub-agent 和 Agent Team 混为一谈，但两者的架构差异决定了完全不同的能力上限：

维度 Sub-agent（子代理） Agent Team（代理团队）
拓扑结构 星型拓扑：主 Agent 一控多 网状拓扑：Agent 之间对等通信
通信方向 单向：主 Agent 下发任务，Sub-agent 返回结果 双向：任意 Agent 之间可直接通信
状态共享 仅返回最终结果给主 Agent 通过共享上下文和消息传递实时同步
适用场景 并行独立任务（如同时审查 3 个文件） 有依赖关系的协作任务（如开发流水线）
典型工具 Task 工具（单次调用） TaskCreate + SendMessage + TaskUpdate

一句话总结：Sub-agent 是"外包"，Agent Team 是"组队"。外包适合独立工作，组队适合协作攻坚。

2. Agent Team 的通信机制

Claude Code v2.1.x 提供了三件套通信原语，构成 Agent Team 的神经系统：

// 通信三原语
interface AgentTeamCommunication {
  // 1. 创建新 Agent 实例并指定其角色和能力
  TaskCreate: {
    agentId: string;        // 唯一标识符
    role: string;           // 角色定义（如 "Planner", "Coder"）
    systemPrompt: string;   // 专属系统提示词
    tools: string[];        // 可用工具集
    model?: string;         // 可选：指定模型（默认继承）
  };
​
  // 2. 更新 Agent 状态或任务进度
  TaskUpdate: {
    agentId: string;
    status: "running" | "blocked" | "completed" | "failed";
    progress?: string;      // 进度描述
    result?: any;           // 阶段性产出
  };
​
  // 3. Agent 间直接消息传递
  SendMessage: {
    fromAgentId: string;
    toAgentId: string;      // 目标 Agent（支持 broadcast）
    messageType: "request" | "response" | "notification";
    payload: string;        // 消息内容
  };
}

3. Lead Agent 设计模式

Lead Agent 是 Agent Team 的"项目经理"，不亲自写代码，但负责：

  • 任务拆解：将用户需求分解为子任务并分配给合适的 Agent

  • 进度追踪：通过 TaskUpdate 监控各 Agent 状态

  • 冲突仲裁：当两个 Agent 产出冲突时做出决策

  • 质量把关：最终检查所有产出是否满足用户需求

# Lead Agent 角色定义示例
name: lead-dev-manager
role: "Tech Lead / Project Manager"
system_prompt: |
  你是开发团队的 Tech Lead。你的职责是：
  1. 接收用户需求，拆解为可并行/串行的子任务
  2. 为每个子任务选择最合适的 Agent（Planner/Coder/Reviewer/Debugger）
  3. 监控进度，当 Agent 阻塞时主动协调
  4. 最终验证所有产出并汇总给用户
  
  重要规则：
  - 不要亲自写代码，你的价值在于协调
  - 当 Reviewer 发现问题时，自动创建 Debugger Agent
  - 任何 Agent 连续失败 3 次，切换策略而非重试

4. 并发锁机制

多 Agent 同时操作同一文件是灾难的根源。Claude Code 提供了两种并发控制策略：

// 策略 1：文件级锁（File-level Lock）
// 某 Agent 编辑 fileA.ts 期间，其他 Agent 对该文件的写操作排队等待
const lockConfig = {
  type: "file-level",
  timeout: 30000,          // 锁超时 30 秒自动释放
  retryStrategy: "queue"   // 排队等待而非报错
};
​
// 策略 2：区域级锁（Section-level Lock）
// 更细粒度：仅锁定文件中被修改的函数/类区域
const lockConfig = {
  type: "section-level",
  conflictDetection: "semantic",  // 语义级冲突检测
  mergeStrategy: "rebase"        // 自动 rebase 非冲突修改
};

实战建议：小团队（2-3 Agent）用文件级锁足够；大团队（4+ Agent）建议区域级锁以避免瓶颈。

5. 无限循环防护

Agent Team 最常见的故障模式是"无限循环"——Reviewer 发现问题 -> Debugger 修复 -> Reviewer 又发现新问题 -> Debugger 再修复 -> 永无止境。

# 防护配置
loop_prevention:
  max_cycles: 5                    # 同一任务链最多 5 轮
  escalation_policy: "human"       # 超限后升级给人类
  cycle_detection:
    method: "hash_state"           # 对状态做哈希，检测重复
    similarity_threshold: 0.95     # 95% 相似视为循环
  backoff:
    initial_delay: 0               # 首次重试无延迟
    max_delay: 60                  # 最大延迟 60 秒
    multiplier: 2                  # 指数退避

实操步骤

步骤 1：定义 4 Agent 团队的完整配置

创建 D:/18-document/claude-02/agent-team/dev-team.yml：

team:
  name: "fullstack-dev-team"
  lead: "lead-dev-manager"
  loop_prevention:
    max_cycles: 5
    escalation: "human"
​
agents:
  - id: "planner"
    role: "Planner"
    model: "sonnet"
    system_prompt: |
      你是技术规划专家。接收需求后产出：
      1. 技术方案（架构图 + 技术选型）
      2. 任务分解（按优先级排序的子任务列表）
      3. 风险识别（至少 3 个潜在风险 + 应对方案）
      输出格式：结构化 Markdown，每个任务带预估工时。
    tools: ["Read", "Glob", "Grep", "WebSearch"]
    max_turns: 15
​
  - id: "coder"
    role: "Coder"
    model: "sonnet"
    system_prompt: |
      你是资深全栈工程师。严格遵循 Planner 的技术方案编码。
      规则：
      - 每个函数不超过 50 行
      - 必须包含错误处理
      - 写完代码后自测核心路径
      - 不确定的技术决策标记 TODO 并说明原因
    tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
    max_turns: 30
    dependencies: ["planner"]
​
  - id: "reviewer"
    role: "Reviewer"
    model: "haiku"  # 审查用轻量模型即可
    system_prompt: |
      你是代码审查专家。对 Coder 产出进行三级审查：
      1. 安全审查：无硬编码密钥、无注入风险、无路径遍历
      2. 质量审查：命名规范、函数长度、错误处理、测试覆盖
      3. 架构审查：是否符合 Planner 方案，是否有过度设计
      输出标准：Critical/High/Medium/Low 四级问题清单。
    tools: ["Read", "Glob", "Grep", "Bash"]
    max_turns: 10
    dependencies: ["coder"]
​
  - id: "debugger"
    role: "Debugger"
    model: "sonnet"
    system_prompt: |
      你是调试专家。仅处理 Reviewer 标记的 Critical 和 High 问题。
      修复流程：
      1. 复现问题（运行代码确认）
      2. 定位根因（不修表面症状）
      3. 实施修复（最小改动原则）
      4. 验证修复（运行相同测试确认通过）
      规则：绝不引入新功能，只修 Bug。
    tools: ["Read", "Edit", "Bash", "Grep"]
    max_turns: 15
    dependencies: ["reviewer"]
​
communication_rules:
  - "Planner 完成后自动触发 Coder"
  - "Coder 完成后自动触发 Reviewer"
  - "Reviewer 发现 Critical/High 问题时自动触发 Debugger"
  - "Debugger 修复后回链 Reviewer 进行 re-review"
  - "任何 Agent 连续失败 3 次，Lead Agent 介入决策"

步骤 2：启动 Agent Team

在 Claude Code 会话中：

# 使用 ag 命令加载团队配置
/ag team start --config dev-team.yml --task "实现用户认证模块：支持 JWT + OAuth2.0，包含登录、注册、Token 刷新"
​
# 监控团队状态
/ag team status
​
# 查看 Agent 间对话日志
/ag team logs --filter "planner->coder"
​
# 人工介入（当循环防护触发时）
/ag team intervene --agent debugger --message "改用 bcrypt 替代 argon2，兼容性优先"

步骤 3：实战观察——一次完整的开发流水线

[10:00:01] Lead Agent: 收到任务"用户认证模块"
[10:00:05] Lead Agent → TaskCreate(Planner)
[10:00:45] Planner → TaskUpdate: completed
          产出：技术方案（JWT + OAuth2.0）+ 6 个子任务
[10:00:46] Lead Agent → TaskCreate(Coder)
[10:02:30] Coder → TaskUpdate: completed
          产出：auth.service.ts, jwt.strategy.ts, oauth.controller.ts
[10:02:31] Lead Agent → TaskCreate(Reviewer)
[10:03:10] Reviewer → TaskUpdate: completed
          发现：2 Critical（密钥硬编码、缺少 CSRF），3 High，5 Medium
[10:03:11] Lead Agent → TaskCreate(Debugger)
[10:04:20] Debugger → TaskUpdate: completed
          修复：密钥迁入环境变量、添加 CSRF 中间件、优化错误处理
[10:04:21] Lead Agent → Reviewer(re-review)
[10:04:50] Reviewer → TaskUpdate: completed
          结果：0 Critical，0 High，2 Medium（可接受）
[10:04:51] Lead Agent → 汇总所有产出，呈现给用户

避坑指南

坑 1：把 Lead Agent 当成"超级程序员"

错误做法：Lead Agent 自己写代码，Agent Team 沦为摆设。 正确做法：Lead Agent 只做协调，所有执行工作委托给专业 Agent。如果 Lead Agent 开始写代码，说明你的任务拆解不够细。

坑 2：过度依赖自动流转

问题：配置了 coder 完成后自动触发 reviewer，但 Coder 产出的是半成品，Reviewer 审查了无效代码。 解决：在每个 Agent 的 system_prompt 中加入"完成标准"检查清单。Coder 必须在自测通过后才标记 completed。

坑 3：忽略模型成本

Haiku 审查代码的能力接近 Sonnet 的 90%，但成本仅为其 1/3。对于 Reviewer 这种"只读不写"的角色，用 Haiku 足够。不要所有 Agent 都上 Sonnet。

坑 4：无限循环的真正原因

大多数"无限循环"不是因为代码有 Bug，而是因为：

  • Planner 的方案本身不可行，Coder 被迫偏离方案

  • Reviewer 的审查标准和 Planner 的方案冲突

  • Debugger 修复一个问题引入了另一个

解决思路：当循环超过 2 轮时，让 Lead Agent 重新评估"是不是方案本身有问题"，而不是继续修修补补。

课后作业

  1. 基础练习：将你最近完成的一个开发任务（至少涉及 3 个文件的修改）用 Agent Team 重新执行一遍。配置 Planner -> Coder -> Reviewer 三 Agent 链，记录各 Agent 耗时和产出质量。

  2. 进阶练习：设计一个 5 Agent 团队来处理"代码库迁移"任务：

    • Analyzer：分析旧代码库结构和依赖

    • Planner：制定迁移方案

    • Migrator：执行代码迁移

    • Tester：编写和运行测试

    • Reviewer：审查迁移后的代码 写出完整的 migration-team.yml 配置文件。

  3. 思考题：在什么场景下 Agent Team 反而不如单 Agent？给出至少 3 种情况并说明原因。

总结

Agent Team 的核心价值不在"多"，而在"对"。4 个角色明确、通信高效的 Agent，远比 10 个职责模糊的 Agent 有价值。记住三个关键原则：

  1. 角色单一职责：每个 Agent 只做一件事，做到极致

  2. 通信最小化：Agent 之间只传递必要信息，避免上下文污染

  3. 失败快速升级：不要在同一层重试太多次，超过阈值就升级给 Lead Agent 或人类

掌握了 Agent Team，你就从"使用 AI 的人"变成了"指挥 AI 团队的人"——这是 Claude Code 高阶用户的核心竞争力。

# 编辑器
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

Windows部署OpenClaw：PowerShell安装、自定义模型与远程访问实测

avatar AI Agent技术社区
cover

深入理解 AI Agent · MEMORY #02：记忆的工程机制

avatar AI Agent技术社区
cover

DeepSeek V4 Pro正式版上线：AI Agent能力跃升背后的行业趋势

avatar AI Agent技术社区