1、Agent Teams：技术架构解析

1.1、 什么是Agent Teams

Agent Teams是Claude Code的一个实验性功能（Research Preview），允许多个Claude Code实例在同一项目中并行工作，通过共享任务列表和消息系统实现协调。

1.1.1、核心组件

1.1.2、核心能力

1）并行工作能力

多个 Claude 实例同时处理不同任务
每个成员拥有独立的上下文窗口
适合需要并行探索的复杂任务
团队协作机制

2）团队领导（Lead）负责协调工作
团队成员（Teammates）独立执行任务
成员之间可以直接通信和讨论
共享任务列表进行协调
3）自主任务管理

领导分配任务或成员自主认领
支持任务依赖关系
自动同步任务状态

1.1.3、Subagents vs Agent Teams

这是很多人容易混淆的两个概念：

选择原则

1）使用 Subagents：当您需要快速、专注且能及时汇报工作的员工时，适合场景：

A、顺序任务

任务之间有严格的先后依赖关系
后续任务需要前一个任务的结果
例如：必须先设计数据库模式，再实现 API，最后写测试

B、同一文件的编辑

多个成员修改同一个文件会导致冲突
合并变更需要额外的协调成本
例如：修改同一个配置文件、更新同一个函数

C、涉及多个依赖项的工作

工作之间紧密耦合，难以独立进行
需要频繁的信息同步
例如：重构核心模块，影响整个代码库

D、简单直接的任务

任务范围小，单个 Agent 就能快速完成
创建团队的开销大于收益
例如：修改一个 bug、添加一个简单功能

2）使用 Agent Teams：当团队成员需要分享发现、互相挑战并自主协作时。当团队成员能够独立操作时，Agent Teams 的效果最佳。如果发现成员之间需要频繁沟通协调，或者工作内容高度重叠，那么单个会话可能更合适。

1.2、上下文继承关系

1.2.1、Agent Teams模式

在项目根目录创建CLAUDE.md，这是所有Teammates共享的上下文（每个Teammate启动时会自动读取这个文件，但不会继承Lead的对话历史）如果你在和Lead聊天时提到了"用@MainActor"，Teammates不知道。但CLAUDE.md里写了，它们就知道了。

1.2.2、Subagents模式

会读取目根目录创建CLAUDE.md，同时Subagents也会继承主会话得上下文

1.3、配置Agent Teams

settings.json：

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

settings.json的位置：

• 项目级：项目根目录/.claude/settings.json
• 用户级：~/.claude/settings.json

1.4、Agent Teams显示模式

1）In-Process模式（默认）：所有Teammates在主终端内运行

• Shift+Up/Down：切换Teammate
• Ctrl+T：查看任务列表
• 无需额外配置，任何终端都能用

2）Split-Pane模式（需要tmux或iTerm2）：每个Teammate独立窗格

配置方式有两种：

1）配置settings.json：

{

"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },

"teammateMode": "tmux"

}

2）命令启动

claude --teammate-mode in-process
claude --teammate-mode auto
claude --teammate-mode tmux

1.5、触发方式

claude启动后，直接用自然语言告诉Claude创建团队：

创建一个 agent team 来开发这个项目。生成3个teammates： 

一个负责后端API实现 

一个负责前端UI组件 

一个负责测试用例编写

确保每个teammate在实施前需要计划批准。

在开发过程中，需要遵循 计划(plan)、测试驱动开发(tdd)、  评审(review)、测试(test )、验证(verify)、 沉淀(Learn)等开发流程

Leader只负责任务分解、协调、统筹工作

开启Delegate Mode

当团队成员完成计划后，会向项目负责人发送计划审批请求。项目负责人审核计划后，会批准或拒绝并提供反馈意见。

如果计划被拒绝，团队成员会继续留在plan模式，根据反馈意见进行修改，然后重新提交。一旦计划获得批准，团队成员就会退出plan模式并开始实施。

项目负责人自主做出审批决定。为了影响项目负责人的判断，请在提示中给出一些标准，例如“只批准包含测试覆盖率的计划”或“拒绝修改数据库架构的计划”。

可以理解为：所有的成员在正在开始任务之前都需要把方案给到团队老板，获得老板批准才能执行

Claude会自动：

1. 创建团队目录和配置
2. 为每个角色生成Teammate
3. 建立共享任务列表
4. 协调工作分配
5. 综合最终结果

1.6、控制团队的关键操作

# 指定模型（节省成本，使用自然语言直接说）
每个 Teammate 使用 Sonnet 模型。

# 委托模式（Lead只协调不动手）
按 Shift+Tab 进入 Delegate 模式

# 查看Teammate状态
按 Shift+Up/Down 在Teammates之间切换

# 直接与某个Teammate对话
选中Teammate后直接输入消息

# 等待所有Teammate完成
等待你的Teammates完成他们的任务后再继续

# 关闭某个Teammate
请研究员Teammate关闭

# 清理整个团队
清理团队
 

1.7、系统内置任务依赖系统

Agent Teams内置了任务依赖管理，自动管理

2、实战

2.1、用Agent Teams并行开发我的macOS项目

2.1.1、项目背景

我有一个macOS菜单栏管理工具Tuck的详细开发规划（shimmying-sparking-wilkinson.md），包含：

10个开发Phase
30+个Swift文件
从私有API桥接到浮动条、搜索面板、Profile系统的完整功能
原来的问题是：这份1500行的规划文档只能喂给单一的Claude Code窗口串行执行。每个Phase完成后才能开始下一个，即使有些Phase的工作是完全独立的。

2.1.2、先澄清一个关键问题：Agent Teams到底怎么触发？

很多人（包括我最初）都会有这个疑问：是不是只需要在prompt里说"创建agent team"就行了？

答案是：是的，就是这么简单。 但有前提条件：

第一步：启用实验性功能（一次性配置）

Agent Teams默认关闭。你必须先开启它，有两种方式：

# 方式1：环境变量（临时，仅当前会话）
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

# 方式2：写入配置文件（永久，推荐）
# 编辑 ~/.claude/settings.json 或 项目/.claude/settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

第二步：用自然语言告诉Claude你要创建团队

启用后，终端界面没有任何视觉变化——没有新按钮、没有新菜单。你只需要在正常的Claude Code对话中，用自然语言描述你想要的团队。Claude会自动识别意图并调用底层的TeammateTool API。

触发关键词不是固定的，以下说法都能触发：

# 这些都能触发Agent Teams：
"创建一个agent team..."
"Create an agent team..."
"Spawn 3 teammates to..."
"我需要多个agent并行处理..."
"帮我组建一个团队来..."
 

第三步：Claude在后台自动完成的事

当你说出类似的话后，Claude（作为Lead）会自动依次执行：

1. TeammateTool({ operation: "spawnTeam", team_name: "tuck-phase1" })
   → 创建 ~/.claude/teams/tuck-phase1/config.json
   → 创建 ~/.claude/tasks/tuck-phase1/ 目录

2. TaskCreate({ subject: "实现Bridging层", description: "..." })
   → 创建任务 #1

3. TaskCreate({ subject: "实现MenuBarEngine", description: "..." })
   → 创建任务 #2（可选依赖 #1）

4. Task({ name: "bridging-dev", prompt: "...", run_in_background: true })
   → 生成第一个Teammate（独立的Claude Code进程）

5. Task({ name: "engine-dev", prompt: "...", run_in_background: true })
   → 生成第二个Teammate
 

你不需要手动调用这些API——Claude自动处理。你看到的只是Claude的文本回复：“好的，我已经创建了团队并生成了3个Teammates，他们正在开始工作…”

2.1.3、团队创建后，终端变成什么样？

这取决于你的显示模式设置。

1）In-Process模式（默认，无需额外配置）

外观上几乎看不出变化——还是那个Claude Code终端。但现在：

┌─────────────────────────────────────────────────┐
│  Claude Code (Team Lead)                        │
│                                                 │
│  > 团队 "tuck-phase1" 已创建                     │
│  > Teammate "bridging-dev" 已启动 (后台)          │
│  > Teammate "engine-dev" 已启动 (后台)            │
│  > Teammate "utility-dev" 已启动 (后台)           │
│                                                 │
│  💡 Shift+Up/Down 切换Teammate                   │
│  💡 Ctrl+T 查看任务列表                           │
│  💡 Escape 中断当前Teammate                       │
│                                                 │
│  You: _                                          │
└─────────────────────────────────────────────────┘
 

Teammates在后台运行，你看不到它们的实时输出。需要主动操作：

2）Split-Pane模式（需要tmux，推荐）

如果你配置了tmux，效果完全不同——每个Teammate有自己的终端窗格：

┌──────────────────────────┬──────────────────────────┐
│                          │  [bridging-dev]           │
│  [Team Lead]             │  正在创建                  │
│                          │  PrivateAPIs.swift...     │
│  团队已就绪，            ├──────────────────────────┤
│  3个Teammates正在工作    │  [engine-dev]              │
│                          │  正在创建                  │
│  You: _                  │  MenuBarItem.swift...     │
│                          ├──────────────────────────┤
│                          │  [utility-dev]             │
│                          │  正在创建                  │
│                          │  NSScreen+Extensions...   │
└──────────────────────────┴──────────────────────────┘
 

• 实时看到所有Teammate的工作进度
• 直接点击窗格就能和对应Teammate对话
• 不需要记忆Shift+Up/Down

2.1.4、Shift+Tab Delegate模式：防止Lead"抢活"

这是Agent Teams的一个重要机制。默认情况下，Lead既可以协调团队，也可以自己写代码。实际使用中会出现一个常见问题：Lead等不及Teammates完成，自己动手开始写代码了。

按Shift+Tab可以循环切换Lead的权限模式：

Normal Mode → Auto-accept Mode → Plan Mode → Delegate Mode → Normal Mode
                                                    ↑
                                              你需要的是这个
 

Delegate Mode下Lead只能做这些事：

• 生成新的Teammate
• 给Teammate发消息/广播
• 关闭Teammate
• 管理任务列表

Delegate Mode下Lead不能做这些事：

• 使用Edit/Write工具修改文件
• 使用Bash执行命令
• 任何直接"动手"的操作

2.1.5 并行化分析

回顾规划文档，我标注了每个Phase的并行可能性：

关键原则：每个Agent拥有不同的文件集，避免冲突。

2.2、完整实操流程

2.2.1、前置准备：CLAUDE.md

在项目根目录创建CLAUDE.md，这是所有Teammates共享的上下文（每个Teammate启动时会自动读取这个文件，但不会继承Lead的对话历史）：

# Tuck - macOS Menu Bar Manager

## 技术栈
- Swift + SwiftUI(70%) + AppKit(30%)
- macOS 14 Sonoma+
- 不使用沙箱（需要Accessibility权限）

## 项目结构
详见 shimmying-sparking-wilkinson.md（包含每个Phase的详细代码规格）

## 编码规范
- 使用 @MainActor @Observable 代替 ObservableObject
- 错误处理使用 os.Logger
- 所有私有API封装在 Bridging/ 目录
- SwiftUI和AppKit的桥接统一在各自的Panel/View中处理

## Agent协作规则
- 每个Agent只修改自己负责的文件，绝对不碰其他Agent的文件
- 公共接口变更必须在任务描述中明确说明
- 完成后在任务中标注新增的public API供其他Agent参考

## 工作流程

- 确保每个teammate在实施前需要计划批准。

- 在开发过程中，需要遵循 计划(plan)、测试驱动开发(tdd)、  评审(review)、测试(test )、验证(verify)、 沉淀(Learn)等开发流程

- Leader只负责任务分解、协调、统筹工作

-开启Delegate Mode

为什么CLAUDE.md如此重要？因为Teammates不继承Lead的对话历史。如果你在和Lead聊天时提到了"用@MainActor"，Teammates不知道。但CLAUDE.md里写了，它们就知道了。

该文档可以手动编辑，也可以/init命令，进行初始化，然后把在手动便补充规范

2.2.2、启动Claude Code + 创建团队

# 编辑 ~/.claude/settings.json 或 项目/.claude/settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

claude --teammate-mode in-process

然后输入以下prompt（这就是"触发"Agent Teams的全部操作）：

读取 shimmying-sparking-wilkinson.md 中的 Phase 1 部分。

现在创建一个 agent team 来并行开发 Phase 1: 核心引擎。

生成3个teammates，每个负责完全独立的文件集：

1. teammate "bridging-dev"，prompt如下：
   "你负责实现 Bridging/ 目录下的4个文件：
   PrivateAPIs.swift（@_silgen_name声明）、
   BridgingHelpers.swift（CGS安全封装）、
   WindowInfo.swift（窗口信息结构体）、
   ScreenCapture.swift（截图封装）。
   严格按照 shimmying-sparking-wilkinson.md 中 Phase 1 Agent 1 的描述实现。
   只创建和修改 Bridging/ 目录下的文件，不要碰其他目录。"

2. teammate "engine-dev"，prompt如下：
   "你负责实现 MenuBarEngine/ 目录下的6个文件：
   MenuBarItem.swift、MenuBarItemInfo.swift、
   MenuBarItemDetector.swift、ControlItemManager.swift、
   MenuBarSection.swift、MenuBarManager.swift。
   严格按照 shimmying-sparking-wilkinson.md 中 Phase 1 Agent 2 的描述实现。
   只创建和修改 MenuBarEngine/ 目录下的文件。
   Bridging层的接口假设已存在，直接import调用即可。"

3. teammate "utility-dev"，prompt如下：
   "你负责实现3个文件：
   MenuBarEngine/MenuBarItemImageCache.swift、
   Utilities/Extensions/NSScreen+Extensions.swift、
   Utilities/Extensions/CGRect+Extensions.swift。
   严格按照 shimmying-sparking-wilkinson.md 中 Phase 1 Agent 3 的描述实现。"

每个teammate使用Sonnet模型以节省成本。
实施前需要计划批准。

在开发过程中，需要遵循 计划(plan)、测试驱动开发(tdd)、  评审(review)、测试(test )、验证(verify)、 沉淀(Learn)等开发流程

- Leader只负责任务分解、协调、统筹工作

-开启Delegate Mode

2.2.3、Claude自动执行的过程

发送上述prompt后，你会看到Claude（Lead）开始工作：

Lead: 好的，我来创建团队。

[Team "tuck-phase1" created]
[Task #1: 实现Bridging层 - pending]
[Task #2: 实现MenuBarEngine核心 - pending]
[Task #3: 实现截图缓存和Extensions - pending]

[Spawning teammate "bridging-dev"...]  ← 独立进程启动
[Spawning teammate "engine-dev"...]    ← 独立进程启动
[Spawning teammate "utility-dev"...]   ← 独立进程启动

3个teammates已启动，正在认领各自的任务。
 

如果你用了tmux split-pane模式，此时屏幕会自动分成4个窗格。

2.2.4 进入Delegate模式

立即按Shift+Tab多次，直到状态栏显示Delegate Mode。

为什么要立即做？因为Lead非常"积极"——如果你不限制它，它会在等Teammates的同时自己也开始写代码，导致文件冲突。

2.2.5 监控Teammates

In-process模式下：

# 按 Shift+Down 选择 bridging-dev
# 按 Enter 查看它的工作状态
# 看到类似输出：
bridging-dev: 正在读取 shimmying-sparking-wilkinson.md...
bridging-dev: 我的计划是创建以下4个文件：
  1. Bridging/PrivateAPIs.swift - CGS函数声明
  2. Bridging/BridgingHelpers.swift - 安全封装
  ...
bridging-dev: [等待计划批准]

# 你可以直接输入："approved, proceed" 批准它的计划
# 按 Escape 返回Lead视角
# 按 Shift+Down 切换到 engine-dev 查看它的状态
 

Split-pane模式下：
直接看右侧窗格，点击对应窗格输入消息。

2.2.6 完成和集成

当所有Teammates完成后，Lead会收到idle通知。此时：

你（对Lead说）：
所有teammates已完成。现在请检查所有创建的文件，
将它们集成到AppState.swift和AppDelegate.swift中。
具体来说：
1. 在AppDelegate.applicationDidFinishLaunching中调用MenuBarManager.setup()
2. 连通Tuck图标点击事件到MenuBarManager.toggleHidden()
3. 确保编译通过
 

2.2.7 清理并进入下一个Phase

清理团队。  ← 这会删除团队配置和Teammate进程

现在开始Phase 3: 浮动条。
创建agent team，2个teammates：
1. "panel-dev"：负责 FloatingBar/FloatingBarPanel.swift（AppKit NSPanel子类）
2. "ui-dev"：负责 FloatingBar/FloatingBarContentView.swift 和 FloatingBarItemView.swift
 

注意：每个Lead会话只能管理一个团队，所以必须先清理再创建新团队

3、十条最佳实践

1）从只读任务开始：代码审查、Bug调查，熟悉后再尝试并行开发
2）写好CLAUDE.md：这是所有Teammates的共享上下文，项目规范、编码标准、接口约定都放这里
3）文件所有权分离：每个Teammate负责不同的文件集，绝不让两个Teammate编辑同一文件
4）每Teammate 5-6个任务：太少不值得并行，太多容易偏离方向
5）用Delegate模式：按Shift+Tab，防止Lead自己动手而不是等Teammates
6）定期检查进度：不要长时间放任不管，避免浪费Token
7）要求计划批准：让Teammates先说做什么，你审批后再实施
8）选对模型：非关键任务用Sonnet节省成本，架构决策用Opus
9）Git Worktree隔离：大项目建议每个Agent一个worktree

4、总结

Claude Code Agent Teams代表了AI辅助编程的一个重要方向——从单Agent到多Agent协作。

对我们开发者来说，现在最值得做的事情是：

1）学会写好规划文档——这将成为驱动AI团队的"需求规格书"
2）练习模块化架构设计——可并行的架构才能充分发挥Agent Teams的价值
3）从小项目开始尝试——代码审查、Bug调查这类低风险任务先上手

Agent Teams目前仍需谨慎使用（成本高、有限制），但方向已经很清晰了。当这项技术成熟后，"一个人管理一支AI团队完成一个大型项目"将从科幻变为日常。