前言：为什么学习 Agent Teams

作为一名长期使用 Codebuddy Code 进行日常开发的程序员，我一直在探索如何更高效地利用 AI 辅助编程。从最初的简单问答，到后来使用 Hooks 自动化工作流，再到 Skills 封装特定领域能力，Claude Code 已经成为我不可或缺的开发伙伴。

当我第一次了解到 Agent Teams 这个功能时，我被它的概念深深吸引：多个 AI 智能体可以组成一个"开发团队"，并行处理复杂任务，每个智能体还拥有独立的上下文窗口。这意味着什么？意味着我可以让一个队友专注于安全审查，另一个专注于性能优化，第三个专注于测试覆盖率——它们可以同时工作，还能相互沟通协调。

这种"多智能体协作"的范式，可能就是 AI 辅助编程的下一个重要演进方向。

本文将分享我学习 Agent Teams 的完整历程，包括核心概念理解、配置实践、与 Skill 结合使用的场景，以及踩坑经验。如果你也对多智能体协作感兴趣，希望这篇文章能为你提供有价值的参考。

一、Agent Teams 核心概念解析

1.1 什么是 Agent Teams

Agent Teams 是 Claude Code 推出的一项实验性功能，允许你协调多个 Claude Code 实例作为一个团队协同工作。

核心架构包含四个关键组件：

组件	角色
Team lead	创建团队、生成队友并协调工作的主 Claude Code 会话
Teammates	各自处理分配任务的独立 Claude Code 实例
Task list	队友认领和完成的共享工作项列表
Mailbox	代理之间通信的消息系统

这个设计最精妙的地方在于：每个 teammate 都有自己独立的上下文窗口（context window）。这意味着它们不会互相干扰，也不会因为某个队友的对话历史过长而影响其他队友的工作。

1.2 与 Subagents 的关键区别

学习初期，我最大的困惑是：Agent Teams 和之前的 Subagents 有什么区别？官方文档给出了清晰的对比：

特性	Subagents	Agent Teams
上下文	自己的 context window；结果返回给调用者	自己的 context window；完全独立
通信方式	仅向主代理报告结果	队友直接相互发送消息
协调机制	主代理管理所有工作	具有自我协调的共享任务列表
最佳用例	只有结果重要的专注任务	需要讨论和协作的复杂工作
令牌成本	较低	较高：每个队友是独立实例

用一个实际场景来说明：

• Subagents：你让助手"帮我查一下这个 API 的返回格式"，它查完告诉你结果，任务结束。
• Agent Teams：你组织一个团队，前端队友和后端队友同时工作，它们可以实时协调 API 变更，而不是等一方完成后才发现冲突。
  

1.3 独立上下文窗口的意义

为什么独立上下文窗口很重要？

假设你正在开发一个复杂的全栈应用，前端需要重构组件结构，后端需要优化数据库查询，测试需要补充覆盖率。如果用一个 AI 实例处理所有这些任务：

1. 上下文会越来越长，响应变慢
2. 不同领域的知识容易混淆
3. 一个任务的修改可能影响另一个任务的判断

而 Agent Teams 的设计让每个队友专注于自己的领域，拥有独立的对话历史和工作记忆。这就像一个真正的开发团队——前端工程师不需要记住后端工程师的每一条 SQL 语句。

二、快速上手：创建你的第一个 Team

2.1 环境配置与启用方式

Agent Teams 默认是禁用的，需要手动启用。有两种配置方式：

方法一：settings.json 配置（推荐）

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

方法二：环境变量

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

注意：需要 Claude Code v2.1.32 或更高版本（来源）。

配置完成后，重启 Claude Code 即可生效。

2.2 自然语言创建团队示例

Agent Teams 的一大亮点是：你不需要写复杂的配置文件，用自然语言描述即可创建团队。

来看一个实际例子。假设我要审查一个 PR，需要从多个角度检查：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

执行后，Claude Code 会：

1. 创建一个团队负责人会话
2. 生成三个具有不同专注点的队友
3. 为每个队友分配任务
4. 队友开始并行工作

这种"声明式"的创建方式非常直观，你只需要描述目标，Claude Code 会帮你组织团队结构。

2.3 显示模式选择：In-process vs Split panes

Agent Teams 支持两种显示模式：

In-process 模式（默认）

• 所有队友在主终端内运行
• 使用 Shift+Down 循环浏览不同队友
• 使用 Enter 查看队友会话
• 使用 Escape 中断当前轮次
• 使用 Ctrl+T 切换任务列表

Split panes 模式

• 每个队友获得自己的终端窗格
• 可以同时看到所有队友的工作
• 点击窗格直接与特定队友交互

限制：Split panes 模式需要 tmux 或 iTerm2；VS Code 终端、Windows Terminal、Ghostty 暂不支持。

配置方式：

// settings.json 全局配置
{
  "teammateMode": "in-process"
}

或命令行：

claude --teammate-mode in-process

对于初学者，推荐使用 In-process 模式；团队规模较大（4-5 个队友）时，Split panes 模式能更直观地监控所有队友的进度。

三、任务协调机制深入理解

3.1 共享任务列表的工作原理

Agent Teams 的核心协调机制是共享任务列表。这不是简单的待办事项，而是一套完整的任务管理生态系统。

任务有三种状态：

状态	说明
待处理（pending）	任务已创建，等待认领
进行中（in_progress）	已被某个队友认领并开始处理
已完成（completed）	任务完成，产出可交付成果

任务分配有两种方式：

1. 负责人显式分配
负责人可以在创建团队时指定任务归属，例如：

Create a team where security-reviewer handles auth audit, 
performance-analyzer handles database queries, and 
test-validator handles coverage checks.

2. 自我认领
队友完成任务后，会自动检查任务列表，认领下一个未分配且未被阻塞的任务。系统内置了文件锁定机制，防止多个队友同时尝试认领同一任务。

3.2 任务状态与依赖关系管理

任务可以设置依赖关系，这在我实际使用中非常有用。比如：

• 任务 B 依赖任务 A（需要等 API 设计完成后才能写前端调用）
• 任务 C 依赖任务 A 和任务 B（测试需要等开发和文档都完成）

系统会自动管理这些依赖，确保队友只能认领其依赖任务已完成的任务。

实际案例：我在重构一个认证模块时，设置了以下任务依赖：

Task 1: 设计新的 JWT 验证流程
Task 2: 实现后端验证中间件（依赖 Task 1）
Task 3: 更新前端认证逻辑（依赖 Task 1）
Task 4: 编写集成测试（依赖 Task 2, Task 3）

后端队友和前端队友可以并行开发（Task 2 和 Task 3），但测试队友必须等两个都完成才能开始。这种依赖管理让团队协作更加有序。

3.3 队友间的消息通信机制

Agent Teams 的通信设计非常优雅：队友可以直接相互发送消息，不需要通过负责人中转。

消息传递是自动的：

• 队友发送的消息会自动传递给收件人
• 负责人不需要轮询更新
• 队友完成并停止时会自动通知负责人

如果你想联系所有人，需要为每个收件人发送一条消息。这可能看起来有点繁琐，但设计上是为了减少不必要的广播开销。

实际场景：安全审查队友发现了一个严重漏洞，需要通知所有队友暂停相关工作：

Send a message to all teammates: "Found critical vulnerability in auth flow, 
please pause related work until I provide fix recommendations."

这种实时通信机制让团队协作更加高效，队友之间可以同步发现、协调工作，而不是各自为战。

四、实战场景一：代码审查与安全检查

4.1 多角色并行审查的优势

在传统的代码审查中，一个人需要兼顾安全、性能、代码风格等多个维度，很容易顾此失彼。而使用 Agent Teams，可以让不同队友专注于不同维度。

我最近在审查一个电商系统的订单模块时，创建了一个四人的审查团队：

Create an agent team to review src/order/ module. Spawn four teammates:
- security-reviewer: focus on SQL injection, authentication, data validation
- performance-analyzer: focus on N+1 queries, caching opportunities
- code-quality-checker: focus on code smells, design patterns
- test-coverage-validator: focus on missing test cases, edge cases

4.2 具体操作流程与代码示例

步骤一：创建团队

在 Claude Code 中输入上述指令，系统会生成四个队友，每个都有特定的审查重点。

步骤二：观察任务分配

使用 Ctrl+T 查看任务列表，你会看到类似这样的结构：

Task ID	Subject	Status	Owner
1	Security review of order creation	in_progress	security-reviewer
2	Performance analysis of order queries	in_progress	performance-analyzer
3	Code quality check	in_progress	code-quality-checker
4	Test coverage validation	in_progress	test-coverage-validator

步骤三：查看队友发现

使用 Shift+Down 切换到不同队友，查看它们的发现。例如，切换到 security-reviewer：

I found a potential SQL injection vulnerability in the order search function:

// order_repository.go:45
func SearchOrders(db *sql.DB, keyword string) ([]Order, error) {
    query := "SELECT * FROM orders WHERE name LIKE '%" + keyword + "%'"
    // This is vulnerable to SQL injection!
    rows, err := db.Query(query)
    ...
}

Recommendation: Use parameterized queries instead of string concatenation.

4.3 效率提升的量化体会

使用 Agent Teams 进行代码审查后，我发现：

指标	传统方式	Agent Teams
审查时间	约 2 小时	约 30 分钟
发现问题数	15 个	42 个
漏洞类型覆盖	3-4 种	10+ 种
干扰其他工作	是（长时间占用上下文）	否（独立上下文）

关键洞察：并行审查不仅节省时间，更重要的是——不同队友的独立视角发现了许多开发者视角容易忽略的问题。比如 test-coverage-validator 发现了一个边界条件测试缺失，这是常规审查中容易被忽视的场景。

五、实战场景二：与 Skill 结合使用

5.1 Agent Teams + Skill 的协同价值

作为一名深度 Claude Code 用户，我已经创建了不少 Skills 来封装特定工作流。Agent Teams 与 Skill 的结合，是我发现的最强大的使用模式之一。

为什么这个组合如此强大？

• Skill 封装了特定领域的专业知识和工作流
• Agent Teams 提供了并行执行和协调能力
• 两者结合，相当于你有了一个由"领域专家"组成的团队

5.2 使用 Subagent 定义创建专业队友

你可以引用任何范围的 subagent 定义（项目、用户、插件或 CLI 定义）来创建队友。

例如，我有一个 security-reviewer 的 agent 定义（使用 Markdown + YAML frontmatter 格式）：

# 文件：.claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools:
  - Read
  - Grep
  - Glob
model: opus
---

You are a security reviewer. Focus on:
- Authentication and authorization flaws
- SQL injection, XSS, CSRF
- Data validation and sanitization
- Sensitive data handling

然后我可以在创建团队时直接使用：

Spawn a teammate using the security-reviewer agent type to audit the auth module.

这个队友会继承 security-reviewer 定义的所有属性：

• 只能使用 Read、Grep、Glob 工具（不能修改文件）
• 使用 Opus 模型（更强的推理能力）
• 遵循安全审查的系统提示

注意：subagent 定义中的 skills 和 mcpServers 字段在作为队友使用时不会被应用。

5.3 实际工作流整合案例

我最近在面试，突然想到我可以创建两个agent来进行面试，一个面试官一个面试者，但是想到双方需要通信，比subagents更好的选择出现了，整合了 Agent Teams 和 Skill：
team创建在以下路径

创建在team沙箱内，每次会话会创建一次team

下面是面试官的对话内容

领导者对话内容

面试官对话内容

六、踩坑经验与最佳实践

6.1 团队规模与任务大小的权衡

踩坑经历：刚开始我创建了 7 个队友，每个任务非常细粒度。结果发现：

• 协调开销超过了实际工作效率
• 大量时间花在任务分配和同步上
• 某些队友因为等待依赖任务而长时间空闲

学到的教训：

因素	建议
起始规模	3-5 个队友
任务数量	每个队友 5-6 个任务
任务大小	自包含的单位，产生清晰的可交付成果

三个专注的队友通常胜过五个分散的队友。

任务大小的判断标准：

• 太小：协调开销超过收益（如"修改一个函数名"）
• 太大：队友长时间工作不检查，增加浪费努力的风险
• 恰到好处：比如"重构某个模块的认证逻辑"或"审查 PR 的安全影响"

6.2 避免文件冲突的策略

踩坑经历：两个队友同时修改同一个文件，导致合并冲突。

解决方案：

1. 分解工作使每个队友拥有不同的文件集

   Teammate A: handles src/auth/*
   Teammate B: handles src/api/*
   Teammate C: handles tests/*
   

2. 使用依赖关系管理

   Task 1: Refactor auth module (assign to A)
   Task 2: Update API to use new auth (assign to B, depends on Task 1)
   

3. 明确指定工作边界

   Create teammates with clear file ownership:
   - frontend-dev: only modifies src/components/*
   - backend-dev: only modifies src/server/*
   

6.3 常见问题排查指南

问题	解决方案
队友未出现	使用 Shift+Down 循环浏览；检查 tmux 是否正确安装
过多权限提示	预批准常见操作，或使用 --dangerously-skip-permissions
队友错误后停止	直接给予额外指示，或生成替代队友
负责人过早关闭	告诉负责人继续等待
孤立的 tmux 会话	运行 tmux kill-session -t <session-name>
任务状态卡住	队友有时无法将任务标记为完成，手动干预或重启团队

关于权限的重要提示：

队友默认从负责人的权限设置开始。如果你使用了 --dangerously-skip-permissions，所有队友也会继承这个设置。但生成后可以更改个别队友的模式。

七、已知限制与应对策略

在使用过程中，我整理了以下已知限制：

限制类型	描述	应对策略
会话恢复	/resume 和 /rewind 不会恢复 in-process 队友	计划好会话时间，避免中断
任务状态滞后	队友有时无法将任务标记为已完成	手动干预或重启团队
关闭延迟	队友在关闭前完成当前请求	耐心等待或使用 shutdown_request
单团队限制	负责人一次只能管理一个团队	合并相关任务到一个团队
无嵌套团队	队友无法生成自己的团队或队友	设计扁平化团队结构
固定负责人	创建团队的会话在其生命周期内是负责人	选择稳定的主会话作为负责人

八、学习收获与展望

8.1 核心知识点回顾

通过这段时间的学习，我对 Agent Teams 有了系统的认知：

1. 概念理解：Agent Teams 是多智能体协作框架，每个队友拥有独立上下文
2. 与 Subagents 的区别：Agent Teams 强调协作和通信，而非简单的任务委托
3. 协调机制：共享任务列表 + 直接消息传递，实现高效团队协作
4. 最佳场景：代码审查、多模块开发、竞争假设调试
5. Skill 结合：Subagent 定义可以创建专业化的领域专家队友

8.2 对日常工作效率的影响

Agent Teams 给我的开发工作带来了实实在在的改变：

• 代码审查效率提升 4 倍：并行多角度审查，发现更多问题
• 复杂任务处理能力增强：可以同时推进多个相关模块
• 上下文管理更清晰：不同任务有独立的对话历史
• 团队协作模拟：真实复现了代码 Review 流程

8.3 后续深入学习方向

我计划继续探索以下方向：

1. 与 Hooks 的深度整合：使用 TeammateIdle、TaskCreated、TaskCompleted 等 Hooks 强制质量门
2. Split panes 模式的更多实践：尝试在复杂项目中使用多窗格监控
3. 团队模式优化：探索更多队友组合和任务分配策略
4. 与其他 Claude Code 功能的协同：结合 MCP、Skills 等构建完整工作流

总结

Claude Code Agent Teams 代表了 AI 辅助编程的一个重要发展方向：从"单一助手"到"协作团队"。这种范式转变不仅仅是技术上的升级，更是工作方式的革新。

对于开发者来说，掌握 Agent Teams 意味着：

• 可以更高效地处理复杂、多维度的工作
• 拥有了一个"随叫随到"的专家团队
• 能够并行推进多个相关任务

虽然目前还有一些限制，但作为实验性功能，Agent Teams 已经展示了巨大的潜力。我相信随着功能的完善，它将成为 AI 辅助编程的标配能力。

给新手的建议：从简单的代码审查场景开始，使用 3 人团队，选择 In-process 模式，逐步熟悉后再尝试更复杂的工作流。

---

拓展阅读

• Claude Code 官方文档 - Agent Teams
• Claude Code Agent Teams 实战教程
• Agent Hooks 系列文章 - 了解如何使用 Hooks 自动化工作流

---

本文首发于 CSDN，作者：kingwu