Agent Teams 团队协作

Agent Teams: Multi-Instance Collaboration

Agent Teams 是 Claude Code 的实验性功能，允许多个独立的 Claude 实例在同一个项目上协同工作。与 SubAgent 不同，Teams 中的每个 Agent 是独立的进程，拥有完全独立的会话和上下文。

核心概念

Core Concepts

Agent Teams 将"团队协作"的理念引入 AI 辅助开发。每个 Agent 就像团队中的一名开发者，独立工作但朝着共同目标推进。

架构概览

Architecture Overview

┌─────────────────────────────────────────────────┐
│                 协调层 (Coordinator)               │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ Agent 实例│  │ Agent 实例│  │ Agent 实例│     │
│  │    #1    │  │    #2    │  │    #3    │     │
│  │ (独立进程)│  │ (独立进程)│  │ (独立进程)│     │
│  │          │  │          │  │          │     │
│  │ 前端重构  │  │ API 开发  │  │ 测试编写  │     │
│  └──────────┘  └──────────┘  └──────────┘     │
│       │              │              │           │
│       └──────────────┼──────────────┘           │
│                      │                          │
│              共享项目文件系统                      │
└─────────────────────────────────────────────────┘

关键特性

Key Features

特性	说明
独立进程	每个 Agent 运行在独立的进程中
独立会话	每个 Agent 有完整的对话上下文
共享文件系统	所有 Agent 访问同一个项目目录
并行执行	多个 Agent 可同时工作
松耦合	Agent 之间通过文件系统和消息松散协调

实验性功能启用

Enabling the Experimental Feature

Agent Teams 目前处于实验阶段，需要通过环境变量显式启用。

启用方法

How to Enable

在终端中设置环境变量：

bash

# Linux / macOS
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Windows (PowerShell)
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"

# Windows (CMD)
set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

也可以在项目的 .env 文件中添加：

env

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

验证启用状态

Verifying the Feature Is Active

启用后，在 Claude Code 中可以通过以下方式确认功能已激活：

> /config

当前配置：
  ...
  experimental.agent_teams: enabled ✓
  ...

实验性功能注意事项

Experimental Feature Caveats

警告：实验性功能可能在未来版本中发生变化或被移除。在生产环境中使用时请格外注意。

API 和行为可能在版本间变化
某些边界情况可能未充分处理
建议在独立分支上使用，避免对主分支造成影响
遇到问题时可通过 GitHub Issues 反馈

与 SubAgent 的区别

Differences from SubAgent

理解 Agent Teams 与 SubAgent 的区别是正确选择工具的关键。

对比表

Comparison Table

维度	SubAgent	Agent Teams
进程模型	同一进程内的子任务	独立进程
会话关系	从属于主 Agent 会话	完全独立的会话
生命周期	随主 Agent 结束而终止	可独立存活
上下文共享	通过返回值传递摘要	通过文件系统和消息
启动方式	Agent 工具调用	配置文件或命令行
适用规模	单一任务分解	大型项目多模块协作
用户交互	不能直接与用户对话	每个 Agent 可独立交互
状态管理	由主 Agent 管理	各自独立管理

类比理解

Analogy

SubAgent ≈ 函数调用
  主 Agent 调用一个"函数"来完成子任务，
  函数返回结果后主 Agent 继续。

Agent Teams ≈ 微服务
  每个 Agent 是独立的"服务"，
  它们通过约定的协议交换信息，
  各自独立运行和扩展。

选择指南

When to Choose What

需要快速完成子任务？           → SubAgent
需要长时间独立工作？           → Agent Teams
任务之间有强依赖？             → SubAgent（更易协调）
任务之间较独立？               → Agent Teams
需要不同的系统提示词？         → Agent Teams
在同一个会话上下文中工作？     → SubAgent

Teams 工作模式

Team Working Patterns

Agent Teams 支持多种协作模式，适应不同的项目需求。

分工模式

Division of Labor Pattern

每个 Agent 负责项目的不同模块或层次，类似于团队中的角色分工。

项目结构：
├── frontend/      ← Agent #1 (前端专家)
│   ├── components/
│   ├── pages/
│   └── styles/
├── backend/       ← Agent #2 (后端专家)
│   ├── routes/
│   ├── services/
│   └── middleware/
├── database/      ← Agent #3 (数据库专家)
│   ├── migrations/
│   ├── models/
│   └── seeds/
└── tests/         ← Agent #4 (测试专家)
    ├── unit/
    ├── integration/
    └── e2e/

分工模式配置示例：

json

{
  "team": {
    "agents": [
      {
        "name": "frontend-agent",
        "role": "前端开发",
        "scope": ["frontend/"],
        "system_prompt": "你是前端开发专家，负责 React 组件和页面开发。"
      },
      {
        "name": "backend-agent",
        "role": "后端开发",
        "scope": ["backend/"],
        "system_prompt": "你是后端开发专家，负责 API 路由和业务逻辑。"
      },
      {
        "name": "db-agent",
        "role": "数据库",
        "scope": ["database/"],
        "system_prompt": "你是数据库专家，负责数据模型和迁移脚本。"
      }
    ]
  }
}

分工模式的优势：

优势	说明
专注度高	每个 Agent 只关注自己的领域
冲突少	不同模块间文件修改不重叠
并行度高	所有 Agent 可以同时工作
专业化	可为每个 Agent 定制最适合的提示词

流水线模式

Pipeline Pattern

Agent 之间形成串行的处理链，每个 Agent 的输出是下一个 Agent 的输入。

Agent #1          Agent #2          Agent #3
(需求分析)   →    (代码实现)   →    (测试验证)
                                        │
                                        ↓
                                   Agent #4
                                   (代码审查)

流水线模式执行流程：

阶段 1: 需求分析 Agent
  输入: 用户需求描述
  输出: 技术规格文档 (spec.md)

阶段 2: 代码实现 Agent
  输入: spec.md
  输出: 实现代码 + 实现说明

阶段 3: 测试验证 Agent
  输入: 实现代码
  输出: 测试用例 + 测试报告

阶段 4: 代码审查 Agent
  输入: 实现代码 + 测试报告
  输出: 审查意见 + 改进建议

混合模式

Hybrid Pattern

实际项目中，往往需要结合分工模式和流水线模式。

                ┌→ Agent A (前端) ─┐
用户需求 → 规划 Agent ─┤                  ├→ 集成 Agent → 发布
                └→ Agent B (后端) ─┘

配置方法

Configuration

项目级配置

Project-Level Configuration

在项目根目录创建 .claude/teams.json 配置文件：

json

{
  "version": "1",
  "team_name": "my-project-team",
  "agents": [
    {
      "id": "architect",
      "name": "架构师",
      "description": "负责系统架构设计和技术决策",
      "system_prompt_file": ".claude/prompts/architect.md",
      "tools": ["Read", "Grep", "Glob"],
      "auto_start": false
    },
    {
      "id": "implementer",
      "name": "实现者",
      "description": "负责具体的代码实现",
      "system_prompt_file": ".claude/prompts/implementer.md",
      "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
      "auto_start": false
    },
    {
      "id": "reviewer",
      "name": "审查者",
      "description": "负责代码审查和质量保证",
      "system_prompt_file": ".claude/prompts/reviewer.md",
      "tools": ["Read", "Grep", "Glob", "Bash"],
      "auto_start": false
    }
  ],
  "coordination": {
    "mode": "manual",
    "shared_artifacts_dir": ".claude/artifacts"
  }
}

配置参数说明

Configuration Parameters

参数	类型	说明
`version`	string	配置文件版本
`team_name`	string	团队名称标识
`agents[].id`	string	Agent 唯一标识符
`agents[].name`	string	Agent 显示名称
`agents[].description`	string	Agent 职责描述
`agents[].system_prompt_file`	string	系统提示词文件路径
`agents[].tools`	string[]	允许使用的工具列表
`agents[].auto_start`	boolean	是否自动启动
`coordination.mode`	string	协调模式 (`manual` / `auto`)
`coordination.shared_artifacts_dir`	string	共享产物目录

通信机制

Communication Mechanisms

Agent Teams 中的通信是异步且松耦合的，主要通过以下方式实现。

文件系统通信

File System Communication

最基本的通信方式——通过共享文件交换信息。

.claude/artifacts/
├── architect-output.md      ← 架构师产出
├── implementation-plan.json ← 实现计划
├── review-notes.md          ← 审查意见
└── status.json              ← 整体状态追踪

状态文件示例：

json

{
  "tasks": [
    {
      "id": "task-001",
      "assigned_to": "implementer",
      "status": "in_progress",
      "description": "实现用户认证模块",
      "dependencies": [],
      "output_file": "architect-output.md"
    },
    {
      "id": "task-002",
      "assigned_to": "reviewer",
      "status": "pending",
      "description": "审查用户认证模块",
      "dependencies": ["task-001"],
      "output_file": null
    }
  ],
  "last_updated": "2025-01-15T10:30:00Z"
}

消息队列通信

Message Queue Communication

通过内置的消息机制，Agent 之间可以发送结构化消息。

Agent A → 消息队列 → Agent B

消息格式：
{
  "from": "architect",
  "to": "implementer",
  "type": "task_assignment",
  "payload": {
    "task": "实现 /api/users 端点",
    "priority": "high",
    "reference": "architect-output.md#user-api"
  }
}

通信模式对比

Communication Pattern Comparison

通信方式	延迟	可靠性	适用场景
文件系统	低	高	产物共享、状态追踪
消息队列	中	中	任务分配、事件通知
共享状态	低	中	进度同步、锁协调

适用场景

Use Cases

大型项目开发

Large-Scale Project Development

场景：电商平台全栈开发

Agent 团队配置：
├── 前端 Agent：React + TypeScript UI 开发
├── API Agent：RESTful API 设计与实现
├── 数据库 Agent：Schema 设计、迁移、索引优化
├── 认证 Agent：OAuth2、JWT、权限系统
└── 测试 Agent：E2E 测试、性能测试

协作流程：
1. 所有 Agent 阅读需求文档
2. 各自在负责的模块中工作
3. 通过共享的接口契约文件协调
4. 测试 Agent 对所有模块进行集成验证

多模块并行开发

Parallel Multi-Module Development

场景：微服务架构的同时开发

Service A Agent ──→ user-service/
Service B Agent ──→ order-service/
Service C Agent ──→ payment-service/
Gateway Agent   ──→ api-gateway/

每个 Agent 独立开发自己的服务，
通过 Proto/OpenAPI 定义交互契约。

代码迁移项目

Code Migration Projects

场景：从 JavaScript 迁移到 TypeScript

分析 Agent：识别需要迁移的文件，评估复杂度
迁移 Agent x3：同时迁移不同目录的文件
类型定义 Agent：创建和维护共享类型定义
验证 Agent：运行类型检查和测试确保无回归

当前限制和注意事项

Current Limitations and Considerations

已知限制

Known Limitations

限制	说明	缓解措施
文件冲突	多个 Agent 修改同一文件时可能冲突	通过 scope 约束各 Agent 的工作范围
资源消耗	每个 Agent 实例消耗独立的资源	控制同时运行的 Agent 数量
协调复杂度	Agent 之间的协调需要额外开销	使用明确的通信协议和状态追踪
上下文不共享	Agent 之间无法直接共享对话上下文	通过文件产物传递关键信息
实验性质	API 可能变化	关注版本更新日志

安全注意事项

Security Considerations

权限控制：确保每个 Agent 只能访问其职责范围内的文件
敏感信息：避免在共享产物中包含密钥或凭据
操作审计：定期检查各 Agent 的操作日志

性能建议

Performance Recommendations

推荐做法：
├── 限制同时运行的 Agent 数量（建议 ≤ 5）
├── 为只读任务使用轻量级 Agent 配置
├── 合理设置 scope 避免不必要的文件扫描
└── 定期清理共享产物目录

不推荐做法：
├── 启动过多 Agent 导致资源耗尽
├── 让所有 Agent 拥有完整的写入权限
├── 缺少明确的任务分配导致重复工作
└── 忽略文件冲突的可能性

调试技巧

Debugging Tips

当 Agent Teams 出现问题时，可以：

检查各 Agent 的日志输出
查看共享产物目录中的状态文件
验证环境变量是否正确设置
单独运行出问题的 Agent 进行隔离排查
使用 /agents 命令查看各 Agent 的运行状态

总结

Summary

Agent Teams 将 Claude Code 从单一 Agent 的工作模式扩展为多 Agent 协作模式，适合大型、复杂的项目开发场景。虽然目前仍处于实验阶段，但其潜力巨大。核心要点：

通过环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用
每个 Agent 是独立进程，拥有独立会话
支持分工模式、流水线模式和混合模式
通过文件系统和消息队列实现松耦合通信
注意文件冲突、资源消耗等限制
适合大型项目的多模块并行开发

Agent Teams 团队协作 ​

核心概念 ​

架构概览 ​

关键特性 ​

实验性功能启用 ​

启用方法 ​

验证启用状态 ​

实验性功能注意事项 ​

与 SubAgent 的区别 ​

对比表 ​

类比理解 ​

选择指南 ​

Teams 工作模式 ​

分工模式 ​

流水线模式 ​

混合模式 ​

配置方法 ​

项目级配置 ​

配置参数说明 ​

通信机制 ​

文件系统通信 ​

消息队列通信 ​

通信模式对比 ​

适用场景 ​

大型项目开发 ​

多模块并行开发 ​

代码迁移项目 ​

当前限制和注意事项 ​

已知限制 ​

安全注意事项 ​

性能建议 ​

调试技巧 ​

总结 ​

Agent Teams 团队协作

核心概念

架构概览

关键特性

实验性功能启用

启用方法

验证启用状态

实验性功能注意事项

与 SubAgent 的区别

对比表

类比理解

选择指南

Teams 工作模式

分工模式

流水线模式

混合模式

配置方法

项目级配置

配置参数说明

通信机制

文件系统通信

消息队列通信

通信模式对比

适用场景

大型项目开发

多模块并行开发

代码迁移项目

当前限制和注意事项

已知限制

安全注意事项

性能建议

调试技巧

总结