Claude Code Team Agents

如何使用Claude Code搭建自己的Agent Team

本文主要是介绍Claude Code入门之后，如何使用Claude Code新开发的Team功能，搭建自己的Agent团队
Note

一个人就是一个团队：协调多个Claude Code实例作为一个团队一起工作，共享任务，代理间消息传递和集中管理。

1. 开启Agent Teams

在Claude Code中，Agent teams能够让你协同多个Claude Code工作吗。一个作为团队的大脑主控，分配工作，协调任务和汇总结果。队友独立工作，每个都在自己的上下文窗口中，并直接相互通信。

不同于subagent，不同的agent也可以直接与队友互动，而不需要经过领导

subagent它们在单个会话中运行，并且只能向主agent报告

Important

Agent teams功能需要Claude Code版本大于2.1.32，如果你想使用teams agent，你必须要检查claude的版本 claude --version

本篇主要介绍下面几项内容

  • 什么时候使用agent teams
  • 怎么创建一个team
  • 如何控制team agent之间的沟通协作
  • 平行任务 之间多练习

2. 什么时候使用Agent Teams

智能体团队（Agent Teams）在处理那些‘并行探索’能带来实质性价值的任务时，效果最为显著。

  • Agent teams (智能体团队)： 指由多个AI智能体（Agents）组成的协作系统。这些智能体可以扮演不同的角色（如研究员、程序员、审查员），或者拥有相同的技能但独立工作，共同解决一个复杂问题

  • Parallel exploration (并行探索)： 指多个智能体同时尝试不同的路径、方法、假设或解决方案，而不是按顺序一个接一个地试

  1. 研究和审查：多个团队成员可以同时调查问题的不同方面，然后分享和挑战彼此的发现
  2. 新的模块或功能：队友可以各自拥有一个单独的部件，而不会踩到对方
  3. 用相互竞争的假设进行调试：团队成员并行测试不同的理论，从而更快地得到答案
  4. 跨层协调：跨越前端、后端和测试的更改，每个更改由不同的团队拥有
  5. 科学发现或药物研发。让10个智能体同时模拟10种不同的分子结构组合，比让1个智能体依次模拟10次要快得多，且更容易尽早发现有效方案

代理团队增加了协调开销，并且比单个会话使用更多的token。当团队成员能够独立工作时，他们的工作效果最好。对于顺序任务、相同文件编辑或使用许多依赖项的工作，单个会话或子代理更有效。

如果你只需要从网页上抓取一个明确的数字，派10个智能体去抢着做这件事不仅没必要，还会导致资源冲突和结果混乱

2.1 Subagents和Agents Team区别

深入理解subagent和agens team区别，才能学会什么时候用不同的方式，更加有效的解决自己的任务

subagents

claude code 官网中介绍了两者的不同

特性 Subagents (子代理) Agent teams (智能体团队)
Context (上下文) 拥有独立的上下文窗口；结果返回给调用者（主代理）。 拥有独立的上下文窗口；成员之间完全独立。
Communication (通信) 仅向主代理 (Main Agent) 汇报结果。 团队成员之间直接互相发消息。
Coordination (协调) 由主代理管理所有工作流程和分配。 共享任务列表，进行自我协调 (Self-coordination)。
Best for (最佳场景) 专注型任务，只关心最终结果，不需要中间讨论。 复杂工作，需要成员间进行讨论、辩论和深度协作。
Token cost (令牌成本) 较低：结果被总结后返回到主上下文中，无需保留所有中间对话。 较高：每个队友都是一个独立的 Claude 实例，消耗多份上下文令牌。

核心区别总结：

  • 架构模式

    • Subagents 是 “主从模式” (Hub-and-Spoke)。主代理是大脑，子代理是手脚或专用工具。适合“拆解 - 执行 - 汇总”的线性工作流。
    • Agent teams 是 “网状模式” (Mesh)。没有绝对的单一控制者，成员像人类团队一样互动。适合需要头脑风暴、多角度验证或动态调整策略的复杂问题。

2.2 如何启用agent teams

Claude Code启用Team Agent是非常简单的，默认是禁用。可以在.claude目录中找到settings.json文件，然后修改CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS为1，即可开启

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

找到文件中的env，然后复制即可，不要忘记了前一个参数要加,

3. 开启你的第一个agent team

在启用agent team之后，告诉Claude创建一个代理团队，并用自然语言描述您想要的任务和团队结构。claude创建团队，生成队友，并根据您的提示协调工作。

下面这个例子效果很好，因为这三个角色是独立的，可以在不等待对方的情况下探索问题

I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

把提示词输入到claude命令行中

agent teams

开始之后，Claude 创造了一个team用一个分享任务列表，为每个视角生成队友，让他们探索问题，综合发现，并在完成任务后尝试清理团队

  ┌─────────────┬────────────────────────────────────────────────┬──────────────────────────┐
  │  Teammate   │                     Focus                      │       Output File        │
  ├─────────────┼────────────────────────────────────────────────┼──────────────────────────┤
  │ ux-designer │ User experience, command design, workflows     │ todo-cli-ux-analysis.md  │
  ├─────────────┼────────────────────────────────────────────────┼──────────────────────────┤
  │ architect   │ Technical decisions, performance, integrations │ todo-cli-architecture.md │
  ├─────────────┼────────────────────────────────────────────────┼──────────────────────────┤
  │ skeptic     │ Critical challenges, edge cases, alternatives  │ todo-cli-critique.md     │
  └─────────────┴────────────────────────────────────────────────┴──────────────────────────┘

3.1 控制agent team

使用自然语言去领导你想要的，它可以根据您的指示处理团队协调、任务分配和委派。

  1. 选择一个展示模型

Agent teams支持两种展示模型：

  • In-process: 所有agent都在主终端内运行。使用shift+Down来切换队友并直接发送消息，这个模式可以在任意终端运作，不需要额外的设置

  • Split panes：每一个agent都有自己的终端您可以同时查看所有人的输出，并点击窗格直接进行交互。需要 tmux 或 iTerm2

Tip

官方提醒：tmux在一些操作系统上有局限性，最好的操作还是在macOS哈桑，可以在iTerm2中使用tmux，具体的tmux使用请查看tmux文章,在终端的使用中，Ghostty也是相当优秀的存在，内存占有小，并且GPU加速，请看Ghostty设置

默认值为“自动”，如果您已经在 tmux 会话中运行，则使用分屏显示；否则，使用进程内显示。“tmux”设置启用分屏模式，并根据您的终端自动检测是使用tmux还是iTerm2。在settings.json中可以设置，加在最外层，和env是平级

"teammateMode": "in-process"

也可以强制使用某一种模式在启动的时候,这个是命令行的形式，请查看claude code

claude --teammate-mode in-process

agent teams

你也可以指定Claude Code生成多少个agent，对于复杂或高风险的任务，您可以要求团队成员在实施前进行计划。在负责人批准其方案之前，团队成员以只读模式编写计划

指派一名架构师队友重构身份验证模块。 在进行任何更改之前，必须获得方案批准。

团队成员完成计划后，会向项目负责人发送计划审批请求。项目负责人审核计划后，会批准或拒绝并提供反馈意见。如果计划被拒绝，团队成员会继续留在计划模式，根据反馈意见进行修改，然后重新提交。一旦计划获得批准，团队成员就会退出计划模式并开始实施。

3.2 与agent直接对话

每个队友都是一个完整的、独立的 Claude Code 会话。您可以直接向任何队友发送消息，提供补充说明、提出后续问题或调整他们的编程方法。

  • In-process 模式：使用shift+Down切换到队友，然后输入消息发送消息。按 Enter 键查看队友的会话，然后按 Esc 键中断其当前回合。按 Ctrl+T 键切换任务列表。

  • Split-pane mode: 点击进入队友的面板即可直接与其会话进行交互。每位队友都能完整查看自己的终端。

agent teams change

组件 角色
shared task list 🧠 全局状态（所有 agent 共享）
lead agent 🎯 任务规划者（写入 task list）
worker agents 🛠 执行者（读取 task list）

任务有三种状态：待处理、进行中和已完成

任务认领机制使用文件锁定来防止多个队友同时认领同一任务时出现竞态条件。任务也可以依赖于其他任务：具有未解决依赖关系的待处理任务，只有在这些依赖关系完成后才能被认领。

3.3 关闭和清空合作

在终端可以使用自然语言来关闭agent team

Ask the researcher teammate to shut down

负责人发送关机请求。团队成员可以批准并正常退出，也可以拒绝并给出解释

当关闭之后，可以要求清楚team。将移除共享的团队资源。当主管运行清理程序时，它会检查是否有活跃的团队成员正在运行，如果有，则会运行失败，因此需要先关闭这些成员。

Caution

始终由负责人进行清理工作。团队成员不应执行清理操作，因为他们的团队上下文可能无法正确解析，从而可能导致资源处于不一致的状态。

使用Hooks强制执行质量把控

  • TeammateIdle:当某个 agent（队友）准备“停下来/结束工作”时触发的拦截点 > 相当于一个AI监工，一直让干

  • TaskCompleted: 当任务被标记为完成时运行。以代码 2 退出以阻止任务完成并发送反馈。

4. Agent teams是如何工作的？

本节介绍Agent Team背后的架构和机制

4.1 Claude Agent Teams架构

首先要开启一个agent teams

  • 给Claude布置一项适合并行处理的任务，并明确要求他组建一个代理团队，Claude会根据你的指示创建一个代理团队。
  • Claude 建议组建团队：如果 Claude 认为您的任务适合并行处理，它可能会建议组建团队。您需要在流程开始前确认

架构

组件 作用说明
Team lead 主 Claude Code 会话，负责创建团队、生成子代理（teammates）并协调整体工作
Teammates 独立运行的 Claude Code 实例，各自负责执行分配到的任务
Task list 共享任务列表，所有代理可以领取并完成其中的任务
Mailbox 代理之间通信的消息系统，用于发送与接收信息

系统会自动管理任务依赖关系。当团队成员完成其他任务所依赖的任务后，被阻塞的任务会自动解除阻塞，无需人工干预

Teams和Tasks存储的位置

  • Team config: ~/.claude/teams/{team-name}/config.json
  • Task list: ~/.claude/tasks/{team-name}/

4.2 文本和交流

每个agent都有自己的上下文窗口。agent生成时，会加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。它还会接收来自主线角色head的生成提示。主线角色的对话记录不会保留。

  • 自动消息发送：团队成员发送消息时，消息会自动发送给收件人。负责人无需轮询更新
  • 空闲通知：当队友完成任务并停止时，会自动通知Head
  • 共享任务列表：所有代理都可以查看任务状态并认领可用工作
Note

多个agent，用的多个上下文窗口，意味着Token爆炸，对于研究、审查和新功能开发，额外的令牌通常是值得的。对于日常任务，单个会话更具成本效益。有关使用指南，请参阅代理团队令牌成本。

5. Agent Team 案例

官网提供了一些简单的案例加深对于Agent Team的理解

5.1 并行运行代码审查

单个审稿人往往一次只会关注一种类型的问题。将审查标准拆分为独立的领域意味着安全性、性能和测试覆盖率都能同时得到彻底的关注。提示信息会为每位Agent分配一个不同的镜头，以避免镜头重叠：

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.

Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish.

5.2 运用相互竞争的假设进行调查

当根本原因不明时，单个agent往往会找到一个看似合理的解释，然后停止。他通过让队友之间形成明确的对抗关系来对抗这种现象：每个人的工作不仅是研究自己的理论，还要挑战其他人的理论。

Users report the app exits after one message instead of staying connected. Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each other's theories, like a scientific debate. Update the findings doc with whatever consensus emerges.

辩论结构是关键机制。循序渐进的调查研究容易受到锚定效应的影响：一旦某个理论被探讨过，后续的调查研究就会倾向于该理论。由于多位独立Agent人员都在积极尝试推翻对方的说法，最终被采纳的理论更有可能是真正的根本原因。

5.3 注意细节

  1. 团队成员会自动加载项目上下文，包括 CLAUDE.md、MCP 服务器和技能，但他们不会继承领导的对话历史记录。

  2. Agent人数没有硬性限制，但实际操作中会受到一些限制：

  • Toekn 成本呈线性增长：每个队友都有自己的上下文窗口并独立消耗代币
  • 协调成本增加：团队成员越多，意味着需要沟通更多、任务协调更多，冲突的可能性也更大。
  • 边际效益递减：超过一定限度后，增加Agent并不会成比例地加快工作速度。

大多数工作流程建议从 3-5 名团队成员开始。这样既能保证并行工作，又能便于协调。本指南中的示例均采用 3-5 名团队成员，因为这个人数范围适用于不同类型的任务。

每个团队成员负责 5-6 个任务，可以保证所有人的效率，避免频繁切换任务。如果有 15 个独立任务，3 个Agent是一个不错的起点。