古法编程

要启用 Claude Code Agent Teams，需要在启动时设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。这是一个实验性功能，它允许你同时启动多个独立的 Claude Code 会话（每个会话拥有完整的上下文和工具），并通过一个共享的任务列表进行协调，从而并行完成复杂的工作流构建任务，其效率远高于单会话内的子代理（Subagents）模式。

Claude Code Agent Teams 实战：多智能体协作构建完整工作流

在复杂的软件工程任务中，单个 Claude Code 会话可能面临上下文窗口和专注度的限制。Agent Teams 是 Claude Code 提供的一项实验性功能，它将一个大型任务拆解，分配给多个并行工作的“团队成员”，每个成员都是一个独立的 Claude Code 实例，拥有完整的工具链和记忆系统。本文将带你从零开始，实战构建一个由 Agent Teams 协作完成的“迪拜时间可视化”工作流。

核心概念：Agent Teams 与 Subagents 的区别

在深入实践前，需要厘清两个概念：

  • Subagents（子代理）：在单个 Claude Code 会话内部派生出的专用代理，共享主会话的上下文窗口，适合处理需要特定工具或指令的子任务。
  • Agent Teams（代理团队）：同时启动多个完整的 Claude Code 会话，每个会话（称为一个 teammate）都独立加载自己的 CLAUDE.md、MCP 服务器和技能。它们通过一个“共享任务列表”进行协调，各自负责工作流中不同的、可能并行的部分。

这种团队模式尤其适合构建涉及多个独立组件（如命令、代理、技能）的编排工作流。

实战准备：环境与工具链

我们将使用 tmux 作为终端复用器，在 iTerm2 中实现分屏，以便同时观察多个智能体的工作状态。

步骤 1：安装必要工具 

brew install --cask iterm2
brew install tmux

步骤 2：启动团队协作环境

  1. 创建并进入一个新的 tmux 会话：
    tmux new -s dev
  2. 关键一步：使用实验性环境变量启动 Claude Code：
    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
    启动后，Claude 会识别该环境变量，并准备接受用于引导团队的指令。

任务定义：构建“时间编排”工作流

我们的目标是让 Agent Teams 协作构建一个 time-orchestrator 工作流。该工作流最终能通过 /time-orchestrator 命令，获取迪拜的当前时间，并生成一个视觉化的 SVG 时间卡片。

步骤 3：向 Lead（你）发出团队组建指令

在启动的 Claude Code 会话中，粘贴并发送以下提示词（其核心来自项目的 agent-teams-prompt.md）：

Create an agent team to build a time orchestration workflow...

这个提示词定义了最终产物（time-orchestrator 命令）和三个并行的团队角色：

三个核心团队角色及其并行协调流程

Agent Teams 的精髓在于角色分工与并行执行。收到指令后，Lead（即你的主 Claude 会话）会并行派出三个“团队成员”：

  1. Command Architect（命令架构师）：负责设计主命令 time-orchestrator.md 的流程。它需要定义如何使用 Agent 工具调用 time-agent，再使用 Skill 工具调用 time-svg-creator。
  2. Agent Engineer（代理工程师）：负责实现 time-agent.md 子代理，以及为其预加载的 time-fetcher 技能。该代理专门用于通过 Bash 获取迪拜的实时时间。
  3. Skill Designer（技能设计师）：负责实现 time-svg-creator 技能，包括定义其指令、SVG 模板参考和输出示例，确保它能将接收到的时间数据渲染成漂亮的 SVG 卡片。

关键协调机制：这三个角色虽然并行工作，但并非毫无关联。他们通过一个共享任务列表来同步关键的数据契约。例如，他们需要共同约定 time-agent 应返回哪些字段（time, timezone, formatted），time-orchestrator 命令又如何将这些字段传递给 time-svg-creator 技能。一旦契约达成，各自的实现便可独立进行。

工作流实现解析：从提示到产出文件

让我们快速浏览这三个角色是如何将指令转化为具体文件的：

  • Command Architect 生成了 agent-teams/.claude/commands/time-orchestrator.md。该文件定义了清晰的步骤：先调用 Agent 获取数据，再调用 Skill 生成 SVG。
  • Agent Engineer 生成了 agent-teams/.claude/agents/time-agent.md 及其预加载的技能 agent-teams/.claude/skills/time-fetcher/SKILL.md。time-agent 的指令明确：运行特定的 date 命令并返回三个约定字段。
  • Skill Designer 生成了 agent-teams/.claude/skills/time-svg-creator/SKILL.md 以及相关的模板和示例文件。该技能严格遵守“只使用传入数据，绝不重新获取”的规则。

运行完成的工作流

当三个团队成员完成工作后，你会在项目目录下看到完整的 agent-teams/.claude/ 结构。此时，你可以亲自运行这个由团队构建的工作流：

cd agent-teams
claude
/time-orchestrator

命令执行后，你会看到一个清晰的流程：Claude 首先调用 time-agent 获取迪拜时间，然后调用 time-svg-creator 技能，最终在 agent-teams/output/dubai-time.svg 生成可视化的时间卡片，并在 agent-teams/output/output.md 写入一份摘要报告。

总结

通过这个实战，我们体验了 Claude Code Agent Teams 如何将一项复杂的工程任务分解、并行化。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 环境变量是打开这扇大门的钥匙，而 tmux 分屏则为我们提供了绝佳的可视化监控视角。理解 Command、Agent、Skill 三种角色的职责划分，以及他们通过共享任务列表协调数据契约的方式，是掌握这种高效多智能体协作模式的关键。

FAQ

Q: Agent Teams 功能是稳定版吗？ A: 不是。从环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 的命名可以看出，这仍是一项实验性功能。在生产环境中使用前，请充分测试。

Q: 如果没有 tmux 或 iTerm2，还能使用 Agent Teams 吗？ A: 可以。tmux/iTerm2 主要用于分屏观察多个智能体的实时输出，便于调试和监控。即使不分屏，你也可以通过一个主 Claude 会话来引导团队，只是无法直观看到其他“队友”的实时工作过程。核心功能（并行派发和协调）不依赖特定的终端工具。

Q: 共享任务列表是如何工作的？我能直接看到它吗？ A: 共享任务列表是 Claude Code 内部的一种协调机制。你无法像查看文件一样直接看到它，但在 Lead（主会话）输出的团队协调流程图中，它会以列表形式呈现，用于展示团队成员间协商达成的共识。它是实现“契约驱动”并行工作的逻辑纽带。