1. Agent Teams技术架构解析
1.1 什么是Agent Teams
Agent Teams是Claude Code的一个实验性功能(Research Preview),允许多个Claude Code实例在同一项目中并行工作。这个功能通过共享任务列表和消息系统实现协调,本质上是一个多智能体协作框架。
在实际开发中,我们经常会遇到需要同时处理多个模块的情况。传统方式是串行处理,效率低下。而Agent Teams允许我们像管理真实开发团队一样,将不同任务分配给不同的AI实例,实现真正的并行开发。
1.1.1 核心组件
Agent Teams由以下几个核心组件构成:
- Team Lead(团队领导):负责协调整个团队的工作,分配任务,监控进度
- Teammates(团队成员):独立的Claude Code实例,每个负责特定任务
- 共享任务列表:所有团队成员可见的任务队列
- 消息系统:团队成员间的通信机制
这些组件共同构成了一个完整的协作系统,使得多个AI实例能够像人类团队一样协同工作。
1.1.2 核心能力
1)并行工作能力
多个Claude实例可以同时处理不同任务,每个成员拥有独立的上下文窗口。这种能力特别适合需要并行探索的复杂任务,比如:
- 同时开发前后端模块
- 并行编写测试用例和实现代码
- 多模块重构工作
2)团队协作机制
团队领导(Lead)负责协调工作,团队成员(Teammates)独立执行任务。成员之间可以直接通信和讨论,通过共享任务列表进行协调。这种机制模拟了真实开发团队的协作方式:
- 任务分配和认领
- 进度同步
- 问题讨论
3)自主任务管理
系统支持任务依赖关系的自动管理,包括:
- 领导分配任务或成员自主认领
- 任务状态自动同步
- 依赖关系自动解析
1.1.3 Subagents vs Agent Teams
这是两个容易混淆的概念,但它们有本质区别:
Subagents(子代理):
- 在主会话中创建的子任务处理器
- 共享主会话的上下文
- 适合顺序执行的任务
- 执行结果直接返回给主会话
Agent Teams(代理团队):
- 完全独立的Claude Code实例
- 拥有独立的上下文窗口
- 适合并行执行的任务
- 通过消息系统与Lead通信
选择原则
1)使用Subagents的场景:
- 任务之间有严格的先后依赖关系
- 多个成员需要修改同一个文件
- 工作内容高度耦合,需要频繁同步
- 简单直接的小任务
2)使用Agent Teams的场景:
- 任务可以独立并行执行
- 每个成员负责不同的文件集
- 需要团队成员分享发现、互相挑战
- 复杂的大型项目开发
1.2 上下文继承关系
1.2.1 Agent Teams模式
在项目根目录创建CLAUDE.md文件,这是所有Teammates共享的上下文。每个Teammate启动时会自动读取这个文件,但不会继承Lead的对话历史。
这意味着:
- 在Lead会话中讨论的内容,Teammates不会知道
- 所有需要共享的信息必须写在CLAUDE.md中
- 适合定义项目规范、接口约定等静态信息
1.2.2 Subagents模式
Subagents会读取项目根目录的CLAUDE.md文件,同时也会继承主会话的上下文。这种模式适合:
- 需要了解主会话讨论内容的任务
- 基于前序任务结果继续工作的场景
- 需要频繁引用主会话信息的场景
1.3 配置Agent Teams
要启用Agent Teams功能,需要在settings.json中进行配置:
json复制{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
配置文件可以放在两个位置:
- 项目级:
项目根目录/.claude/settings.json - 用户级:
~/.claude/settings.json
项目级配置会覆盖用户级配置,这允许我们为不同项目设置不同的行为。
1.4 Agent Teams显示模式
Agent Teams支持两种显示模式:
1)In-Process模式(默认)
- 所有Teammates在主终端内运行
- 快捷键操作:
Shift+Up/Down:切换TeammateCtrl+T:查看任务列表
- 优点:无需额外配置,任何终端都能用
2)Split-Pane模式(需要tmux或iTerm2)
- 每个Teammate有独立窗格
- 配置方式:
- 通过settings.json:
json复制{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "teammateMode": "tmux" } - 或通过命令行参数:
bash复制
claude --teammate-mode tmux
- 通过settings.json:
- 优点:可以实时查看所有Teammate的工作状态
1.5 触发方式
启动claude后,直接用自然语言告诉Claude创建团队。例如:
code复制创建一个agent team来开发这个项目。生成3个teammates:
一个负责后端API实现
一个负责前端UI组件
一个负责测试用例编写
确保每个teammate在实施前需要计划批准。
在开发过程中,需要遵循计划(plan)、测试驱动开发(tdd)、评审(review)、测试(test)、验证(verify)、沉淀(Learn)等开发流程
Leader只负责任务分解、协调、统筹工作
开启Delegate Mode
Claude会自动完成以下工作:
- 创建团队目录和配置
- 为每个角色生成Teammate
- 建立共享任务列表
- 协调工作分配
- 综合最终结果
1.6 控制团队的关键操作
以下是一些常用的团队控制命令:
code复制# 指定模型(节省成本)
每个Teammate使用Sonnet模型。
# 进入委托模式
按Shift+Tab进入Delegate模式
# 查看Teammate状态
按Shift+Up/Down在Teammates之间切换
# 直接与某个Teammate对话
选中Teammate后直接输入消息
# 等待所有Teammate完成
等待你的Teammates完成他们的任务后再继续
# 关闭某个Teammate
请研究员Teammate关闭
# 清理整个团队
清理团队
1.7 系统内置任务依赖系统
Agent Teams内置了任务依赖管理系统,可以自动处理任务间的依赖关系。例如:
- 任务B依赖于任务A的完成
- 只有当任务A完成后,任务B才会开始
- 系统会自动管理这些依赖关系,无需人工干预
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 实战应用
2.1 使用Agent Teams并行开发macOS项目
2.1.1 项目背景
假设我们有一个macOS菜单栏管理工具Tuck的开发项目,包含:
- 10个开发阶段
- 30+个Swift文件
- 从私有API桥接到浮动条、搜索面板、Profile系统的完整功能
传统方式下,我们只能串行执行每个阶段,即使有些阶段的工作是完全独立的。使用Agent Teams可以实现真正的并行开发。
2.1.2 触发Agent Teams的关键步骤
很多人会有疑问:如何触发Agent Teams功能?其实很简单:
第一步:启用实验性功能
Agent Teams默认是关闭的,需要先启用它。有两种方式:
-
临时启用(仅当前会话):
bash复制
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude -
永久启用(推荐):
编辑配置文件:bash复制# 编辑 ~/.claude/settings.json 或 项目/.claude/settings.json { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
第二步:用自然语言创建团队
启用功能后,只需在正常的Claude Code对话中,用自然语言描述你想要的团队。以下说法都能触发:
code复制"创建一个agent team..."
"Create an agent team..."
"Spawn 3 teammates to..."
"我需要多个agent并行处理..."
"帮我组建一个团队来..."
第三步:Claude自动完成的工作
当发出创建团队的指令后,Claude(作为Lead)会自动执行以下操作:
- 创建团队配置目录和文件
- 创建共享任务目录
- 生成任务列表
- 启动独立的Claude Code进程作为Teammates
- 协调团队成员的工作
2.1.3 团队创建后的界面
根据显示模式的不同,界面会有不同表现:
In-Process模式(默认)
外观上看不出明显变化,还是原来的Claude Code终端。但可以通过快捷键操作:
Shift+Up/Down:切换TeammateCtrl+T:查看任务列表Escape:中断当前Teammate
Split-Pane模式(需要tmux)
每个Teammate有自己的终端窗格,可以:
- 实时查看所有Teammate的工作进度
- 直接点击窗格与对应Teammate对话
- 无需记忆快捷键
2.1.4 Delegate模式的重要性
Delegate模式是一个重要机制。默认情况下,Lead既可以协调团队,也可以自己写代码。这会导致一个问题:Lead可能等不及Teammates完成,自己就开始写代码了。
按Shift+Tab可以进入Delegate模式,此时Lead只能:
- 生成新的Teammate
- 给Teammate发消息/广播
- 关闭Teammate
- 管理任务列表
而不能:
- 直接修改文件
- 执行命令
- 进行任何"动手"的操作
2.1.5 并行化策略
要实现有效的并行开发,需要遵循以下原则:
- 每个Agent负责不同的文件集
- 明确划分责任边界
- 避免多个Agent修改同一文件
- 公共接口变更必须明确说明
2.2 完整实操流程
2.2.1 准备工作:CLAUDE.md
在项目根目录创建CLAUDE.md文件,包含以下内容:
- 项目概述和技术栈
- 项目结构说明
- 编码规范
- Agent协作规则
- 工作流程
这个文件是所有Teammates的共享上下文,非常重要。
2.2.2 启动Claude并创建团队
配置好settings.json后,启动Claude:
bash复制claude --teammate-mode in-process
然后输入创建团队的prompt:
code复制读取项目规划文档中的Phase 1部分。
现在创建一个agent team来并行开发Phase 1:核心引擎。
生成3个teammates,每个负责完全独立的文件集:
1. teammate "bridging-dev",负责Bridging/目录下的4个文件
2. teammate "engine-dev",负责MenuBarEngine/目录下的6个文件
3. teammate "utility-dev",负责3个工具类文件
每个teammate使用Sonnet模型以节省成本。
实施前需要计划批准。
在开发过程中,需要遵循计划、测试驱动开发、评审、测试、验证、沉淀等开发流程
Leader只负责任务分解、协调、统筹工作
开启Delegate Mode
2.2.3 监控和管理团队
团队创建后,需要:
- 立即进入Delegate模式(按Shift+Tab)
- 定期检查各Teammate的进度
- 审批Teammate提交的计划
- 解决可能出现的问题
2.2.4 完成和集成
当所有Teammates完成任务后:
- Lead会收到通知
- 检查所有创建的文件
- 进行必要的集成工作
- 确保编译通过
2.2.5 清理并进入下一阶段
完成当前阶段后:
code复制清理团队
然后可以开始下一阶段的开发。
3. 最佳实践
根据实际使用经验,总结出以下十条最佳实践:
-
从只读任务开始:先尝试代码审查、Bug调查等低风险任务,熟悉后再进行并行开发。
-
完善CLAUDE.md:这是所有Teammates的共享上下文,应该包含:
- 项目规范
- 编码标准
- 接口约定
- 协作规则
-
明确文件所有权:每个Teammate负责不同的文件集,避免冲突。
-
合理分配任务量:每个Teammate分配5-6个任务为宜,太少不值得并行,太多容易偏离方向。
-
使用Delegate模式:防止Lead自己动手而不是等待Teammates完成。
-
定期检查进度:避免长时间放任不管,造成资源浪费。
-
要求计划批准:让Teammates先提交计划,审批后再实施。
-
合理选择模型:非关键任务用Sonnet节省成本,架构决策用Opus。
-
使用Git Worktree隔离:大型项目建议每个Agent使用独立的worktree。
-
从小项目开始:先在小项目上积累经验,再应用到大型项目。
4. 经验总结
在实际使用Agent Teams进行开发时,有几个关键点需要特别注意:
-
规划文档的重要性:清晰、详细的规划文档是成功使用Agent Teams的基础。文档应该:
- 明确定义每个模块的功能
- 描述模块间的接口
- 说明预期的行为
-
模块化设计:项目架构应该尽可能模块化,这样才能充分发挥并行开发的优势。
-
沟通机制:虽然Teammates可以自主工作,但必要的沟通机制仍然重要:
- 定期状态报告
- 问题反馈渠道
- 变更通知
-
质量控制:并行开发更需要严格的质量控制:
- 代码审查
- 自动化测试
- 持续集成
-
成本控制:多个Agent同时运行会增加成本,需要:
- 合理分配资源
- 监控使用情况
- 优化工作流程
通过遵循这些原则和实践,可以有效地利用Agent Teams提高开发效率,实现"一个人管理一支AI团队完成大型项目"的目标。
