11.2 Agent Teams 的架构与配置

面向经管学生、研究者与从业者的 AI 智能体设计教材

11.2 配图

一个 Agent Team 由四个部分组成：

组件	说明
Lead（团队领导）	创建团队、生成队友、协调工作的主 Claude Code 会话
Teammates（队友）	独立的 Claude Code 实例，各自处理分配的任务
Shared task list（共享任务列表）	所有队友都能看到和更新的工作条目列表
Messaging system（消息系统）	智能体之间的通信通道

Lead 是团队的创建者和协调者，负责生成队友、创建初始任务列表、监控进度并综合结果。团队创建后，Lead 角色在整个生命周期内不会转让。队友是独立运行的 Claude Code 实例，拥有自己的上下文窗口、工具权限和工作空间，可以自主认领任务、与其他队友通信、完成后标记任务状态。

启用方法

Agent Teams 默认禁用。启用方法是设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

可以将这行命令添加到 Shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中，每次启动终端时自动生效。也可以在 ~/.claude.json 中配置：

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

显示模式

队友的显示方式有两种，通过 teammateMode 设置控制：

设置值	行为	优点	缺点
in-process	所有队友在主终端窗口内运行，用 Shift+Down 切换	设置简单，无需额外工具	同时只能看一个队友
tmux（split-pane）	每个队友有独立终端面板	同时监控所有队友	需要 tmux 或 iTerm2
auto（默认）	检测到 tmux 则用 split-pane，否则用 in-process	自动适配环境	—

在 ~/.claude.json 中配置显示模式：

{
  "teammateMode": "in-process"
}

也可以通过命令行参数临时指定：claude --teammate-mode in-process。初次使用时，建议先用 in-process 模式。

创建团队与角色配置

在对话中明确要求创建团队，并描述需要什么角色：

▶ Claude Code

我正在设计一个金融数据分析 CLI 工具。
请创建一个 Agent Team 从不同角度探索这个项目：
一个队友负责用户体验设计，
一个负责技术架构，
一个扮演批评者角色，挑战前两者的方案。

如果 Claude Code 判断当前任务适合并行协作，它也可能主动建议创建团队，用户确认后才实际创建。

队友数量推荐 3-5 个。每个队友可以使用不同的模型：分析任务用 sonnet，深度推理用 opus，简单数据收集用 haiku。Lead 通常使用最强的模型，因为它承担协调和决策的核心工作。

如果已经在 .claude/agents/ 中定义了子代理（如 security-reviewer.md），可以在创建队友时直接引用作为角色模板。队友会继承该定义的系统提示词作为补充指令，但 model 和 tools 字段在作为队友运行时不会生效——队友的模型由创建时指定，工具权限继承自 Lead。

快速上手

第一次尝试 Agent Teams 时，可以先设 2 个队友。先给出明确分工，用一个小任务验证流程，再逐步扩展团队规模。