Claude Code实战：从零配置Agent Teams代码审查团队的详细指南

在上一篇 Claude Code 并行开发完全指南：Subagents + Agent Teams + Git Worktree + 工作流编排实战 中，我们把 Subagents、Agent Teams、Git Worktree、工作流编排这四条技术路线都梳理了一遍。

有读者看完后提问：听起来最复杂的 Agent Teams，是不是也最难上手？

说实话，Agent Teams 本身的配置并不复杂。真正的门槛在于：找到值得用它并行的场景。工具就摆在那里，但什么时候该启动 Agent Teams，什么时候用 Subagent 就够，这才是大多数人感到困惑的地方。

本文就围绕一个真实的代码审查场景，带你完整走一遍 Agent Teams 的配置、启动、协作与结果整合流程，顺便把“什么时候用”和“什么时候不用”讲清楚。

一、场景：为什么需要多代理并行？

假设你正在重构一个典型的三层架构项目：前端用 React，后端是 Node.js，还有一堆数据库迁移脚本。代码量不小，而且改动分散在三个不同的目录。

如果只开一个 Claude 实例，你可能会陷入这样的困境：一边要跟“架构师”讨论整体方案，另一边还得协调前端改完的接口后端能不能用。体验往往很糟糕：

• 跟“架构师”聊了20分钟，切到“前端开发”窗口时发现，刚才讨论的上下文全丢了。
• 不得不重新解释一遍项目背景，再花15分钟等它重新读完代码。
• 等你切回“架构师”窗口，之前的讨论结论已经变得模糊不清。

这不是 Claude Code 的问题，而是单实例工具设计上就不支持“多个工作流同时进行”。而 Agent Teams 要解决的，正是这个问题。

二、启用 Agent Teams

2.1 前置条件

• Claude Code v2.1+
• macOS 或 Linux（Windows 用户可使用 WSL）
• tmux 已安装

如果你的系统还没安装 tmux，可以通过以下命令安装：

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

2.2 开启实验性功能

编辑（或创建）配置文件 ~/.claude/settings.json：

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

如果还没有这个配置文件，先创建目录和文件：

mkdir -p ~/.claude
touch ~/.claude/settings.json

2.3 启动你的第一个团队会话

配置完成后，启动方式非常直观——直接用自然语言描述你的团队：

# 直接用自然语言启动团队
claude "创建一个代码审查团队"

启动后，你将直接与 Team Lead（团队领导） 对话。它的职责是理解你的需求，并将任务合理分配给其他队友（Agent）。

三、创建并运作你的审查团队

3.1 定义团队成员

你不需要提前编写复杂的配置文件。直接向 Team Lead 描述你需要的队友角色即可，它会自动创建对应的 Agent。

例如，启动一个专为后端 API 和安全审计设计的团队：

claude "创建一个代码审查团队：一个负责后端API审查，一个负责安全审计"

Team Lead 上线后，你可以继续用自然语言分配具体任务：

审查 src/api 目录的代码，重点看权限校验和数据查询的安全性。

Team Lead 会自动将任务分解，并分派给对应的“后端专家”和“安全审计师”。两者开始并行工作，各自完成审查后，将结果汇总给 Team Lead，最后由 Team Lead 向你进行统一汇报。

3.2 团队运作的几种典型模式

Agent Teams 的核心价值在于灵活的协作模式。下图清晰地展示了三种主要的协作范式：

模式一：分工审查

• 适用场景：同一套代码需要从多个不同维度（如功能、安全、性能）同时审查。
• 运作方式：Team Lead 将代码库同时分发给 backend-dev（审查业务逻辑）和 security-auditor（审查安全漏洞）。两者并行工作，视角独立，最后将各自发现的问题汇总。

模式二：主从协作

• 适用场景：任务步骤之间存在强依赖关系，必须按顺序进行。
• 运作方式：例如重构认证模块。architect 先分析现有体系并提供设计方案；backend-dev 基于前者的方案进行具体实现；security-auditor 最后对实现代码进行安全性审查。Team Lead 会协调依赖，确保上游任务完成后再启动下游。

模式三：并行探索

• 适用场景：需要对比多种技术方案，快速决策。
• 运作方式：比如评估“用 Redis 缓存还是本地内存缓存”。Team Lead 可让 architect（看架构影响）、backend-dev（看实现成本）、security-auditor（看潜在风险）同时进行分析。Team Lead 综合三方意见，给出最终建议。

四、核心操作：在多个队友间切换与整合结果

4.1 切换队友窗口

启动 Agent Teams 后，你默认看到的是 Team Lead 的窗口（在 tmux 中是一个独立的 pane）。查看或干预其他队友的工作进度，需要手动切换。

操作	按键
切换到下一个队友窗口	Shift+↑
切换回上一个队友窗口	Shift+↓

切换过去后，你就可以直接与那个队友对话，询问进展、纠正方向或补充上下文。

给 macOS + iTerm2 用户的建议：使用 tmux 控制模式，可以获得更佳的多窗口体验：

tmux -CC

iTerm2 会将每个队友的会话渲染成独立的窗格（split pane），让你能同时看到所有 Agent 的输出，无需来回切换。

4.2 整合团队输出

重要提示：任务并行执行完成后，Team Lead 不会自动生成一份格式优美的汇总报告。你需要明确指示它如何整合信息。

你可以这样告诉 Team Lead：

帮我把 backend-dev 和 security-auditor 的审查结果合并成一份报告，请按以下结构组织：
1. 高优先级问题（必须修复才能合并代码）
2. 中优先级问题（建议在本迭代修复）
3. 低优先级问题（优化项，可后续处理）

Team Lead 会根据你的要求，提取和重组各个队友的输出，形成一份结构化的最终报告。这种在 后端与架构 设计中常见的分层归纳思想，同样适用于指导 AI 团队的工作汇报。

五、实战中容易踩的“坑”

坑一：任务描述过于模糊

Team Lead 的调度能力很大程度上取决于你输入的指令质量。“帮我看看代码”是一个糟糕的任务描述。“审查 src/api/auth.py 文件，重点检查 JWT Token 的校验逻辑是否存在越权漏洞，并列出所有发现。”——这才是一个清晰的指令。任务越具体，分解越准确，队友的工作质量越高。

坑二：启动后不监控进度

Agent Teams 默认只在 Team Lead 的窗口显示最终汇总。如果你一直不看其他队友的窗口，他们中途理解错了需求、跑偏了方向，你都无法及时纠正。建议每隔几分钟就用 Shift+↑ 浏览一下各个队友的进展。

坑三：上下文窗口限制

每个队友有独立的上下文，但 Team Lead 自身仍受 Claude 上下文窗口大小的限制。如果任务涉及的文件量巨大，在分配任务时就可能把 Team Lead 的上下文撑满。解决方案是：让 Team Lead 只做高级别的任务分解和调度，具体的代码阅读和分析工作交由各队友独立完成，无需将所有文件内容都经过 Team Lead。

坑四：队友间缺乏通信

默认情况下，各队友是独立工作的，不会主动同步信息。如果 backend-dev 发现了一个会严重影响 security-auditor 判断的底层问题，它不会主动告知对方。你需要在任务描述中明确加入通信规则，例如：“如果发现可能影响其他队友结论的共性问题，请立即报告给 Team Lead。”

六、什么时候用？什么时候不用？

Agent Teams 有启动和协调的开销，并非万能。

值得使用的场景：

• 多模块并行审查：例如，需要同时审查前端界面、后端 API 和数据库脚本。
• 多方案对比决策：需要从架构、实现、风险等多个视角快速评估不同技术选项。
• 复杂任务流水线：典型的“架构师出方案 -> 开发实现 -> 安全审计”这类有严格阶段划分的任务。

不值得使用的场景：

• 单个文件的简单修改：直接开一个 Claude 实例更快捷。
• 编写单元测试或注释：单一、明确的任务，一个 Agent 足矣。
• 解释代码或查询文档：这属于信息检索或学习场景，无需并行。

简单说，Agent Teams 的核心是“多 Agent 同时工作”。如果你的问题一个 Agent 就能轻松搞定，那就不要用它，避免把简单问题复杂化。

七、团队配置持久化

每次开始新项目都重新用自然语言描述一遍团队结构，显然很麻烦。你可以将常用的团队配置写入项目根目录的 CLAUDE.md 文件中：

# 本项目 Agent Teams 配置

## 默认团队
本项目使用以下团队配置：
- architect：负责架构分析和方案评审
- backend-dev：负责后端代码审查与实现
- security-auditor：负责安全漏洞审查

## 启动命令
`claude "创建一个代码审查团队：architect 评审方案，backend-dev 和 security-auditor 并行审查代码"`

## 典型工作流
1.  首先由 architect 评审技术方案可行性。
2.  方案通过后，由 backend-dev 和 security-auditor 并行审查相关代码。
3.  最后由 Team Lead 汇总两者的结果，生成合并报告。

这样，下次在这个项目目录下启动 Claude Code 时，只需要复制粘贴启动命令即可，团队结构会自动复用。

八、总结

Agent Teams 是 Claude Code 中用于解决“多个工作流需要真正并行”的高阶功能。它的核心价值在于模拟了一个由智能体（Agent） 组成的协作团队，这也是当前 人工智能 应用走向复杂任务处理的一个重要方向。

核心操作流程回顾：

1. 启用：在 ~/.claude/settings.json 中开启实验性功能。
2. 启动：使用 claude “创建一个团队...” 自然语言命令。
3. 切换：使用 Shift+↑/↓ 在队友窗口间切换，监控进度。
4. 整合：明确指示 Team Lead 以特定格式汇总结果。

关键注意事项：

• 指令要具体：模糊的指令导致低效的并行。
• 过程要监控：主动切换窗口，防止方向跑偏。
• 通信需明确：默认情况下，队友之间不会自动交换信息。

用对了，它能成为你代码审查和复杂问题拆解的“超级外脑”；用错了，就只是几个 AI 在同时漫无目的地运行。希望这篇在云栈社区分享的实战指南，能帮助你真正驾驭这个强大的工具。