Claude Code 多AI代理实操指南：Subagents与Teams核心用法与场景解析

你花了一晚上把 Claude Code 的配置文件改好了，Subagent 定义文件也写了，MCP 服务也装了。打开终端，面对那个闪烁的光标，突然愣住了：

“然后呢？我该输入什么？”

这感觉就像你组装好了一台高配电脑，系统装好了，驱动打好了，结果坐在键盘前不知道该按哪个键开机。配置文件是“注册能力”，但“激活能力”这一步，很多人卡住了。

Claude Code 内置了两套协同机制 —— Subagents（子代理）和 Agent Teams（代理团队）。触发方式比你想的简单：跟它说人话就行。

这篇文章分两个实操练习。练习一带你从零创建并触发一个 Subagent，练习二带你开启并使用 Agent Teams。每一步都有具体的命令和预期结果，跟着做就行。

准备工作：先确认你的环境没问题

开始之前，跑三个命令确认环境就绪。

1. 确认 Claude Code 已安装

打开终端，输入：

claude --version

你应该看到类似 claude-code 1.x.x 的版本号。如果提示“command not found”，说明还没装，需要先去官网安装。

2. 确认你在一个项目目录里

Subagent 和 Teams 都依赖项目上下文。随便 cd 到一个你正在开发的项目目录，或者临时建一个测试用的：

mkdir ~/test-agents && cd ~/test-agents
git init

3. 确认 Claude Code 能正常启动

claude

看到对话界面就行。输入 exit 或按 Ctrl + C 先退出来，我们下面会重新进去。

三个都没问题？往下走。

Subagents 和 Agent Teams，到底有什么不同

在动手之前，先用 30 秒把这两个概念掰扯清楚，因为选错了方案就像拿菜刀去拧螺丝 —— 不是不能用，是费劲。

Subagents 是“专家顾问”。你把一个具体任务交给它，它埋头干完把结果交回来。整个过程在同一个会话里，Subagent 之间不通气，也不会自己再叫帮手。就像你公司里的法务顾问，你发个邮件问他合同条款的问题，他回复你结果，但他不会去找财务讨论。

Agent Teams 是“项目组”。一个 Lead（组长）会拉几个 Teammate（组员），每个人都是一个完整的 Claude Code 实例，有自己的上下文窗口。Teammate 之间可以直接互发消息、讨论甚至辩论。就像你拉了个微信群，前端、后端、测试各自负责一块，有问题群里直接吵。

对比维度	Subagents	Agent Teams
上下文	独立上下文，结果返回给调用者	独立上下文，完全自治
通信	只向主 Agent 汇报	Teammate 之间可以直接聊
协调	主 Agent 统一管理	共享任务列表，自行认领
Token 成本	较低（结果总结后返回）	较高（每个 Teammate 都是独立实例）
功能状态	正式功能，开箱即用	实验性功能，需要手动开启
适用场景	只要最终结果的聚焦任务	需要讨论和协作的复杂工程

简单说：任务明确、只要结果，用 Subagent。任务复杂、需要人互相碰，用 Teams。

练习一：从零创建并触发一个 Subagent

这个练习大约需要 5 分钟。跟着做完，你就能创建并触发一个自动审查代码的 Subagent。

第 1 步：了解 Claude Code 自带了哪些 Subagent

在你自己创建之前，先知道 Claude Code 已经内置了几个：

内置 Subagent	模型	干什么用
Explore	Haiku（快且便宜）	只读搜索和分析代码库，不会改文件
Plan	继承主会话	Plan 模式下做代码调研，为制定计划收集上下文
general-purpose	继承主会话	多步骤的复杂任务，既能读也能改

Explore 用的是 Haiku 模型，速度快、Token 消耗低，适合“帮我在代码库里找某个东西”这类活。general-purpose 什么都能干，读写改删都行。

这些内置 Agent 不需要你做任何配置，Claude 会根据任务自动调用。下面我们创建一个自定义的。

第 2 步：创建 Subagent 文件

有两种方式，任选一种。

方式 A：用 /agents 命令创建（交互式，推荐新手）

启动 Claude Code，然后输入：

/agents

你应该看到：一个列表，显示当前可用的所有 Agent（包括内置的 Explore、Plan 等）。

选 Create new agent -> 选 Project-level（这样 Agent 文件保存在当前项目的 .claude/agents/ 目录下）-> 选 Generate with Claude -> 当它问你想要什么 Agent 时，输入：

一个代码审查员，审查代码变更的质量、安全性和可维护性

你应该看到：Claude 帮你生成了一份 Agent 定义，包含 name、description 和系统提示词。按 e 可以编辑，没问题就直接保存。

方式 B：手动写文件（精确控制每个字段）

在项目根目录下创建文件：

mkdir -p .claude/agents

然后创建 .claude/agents/code-reviewer.md，把下面的内容复制进去：

---
name: code-reviewer
description: >
  专业的代码审查员。在代码编写或修改完成后，主动使用此代理来审查代码的
  质量、安全性和可维护性。当用户要求“审查代码”或“code review”时使用。
tools: [Read, Grep, Glob, Bash]
model: sonnet
---

你是一名高级代码审查员，负责确保代码库的高标准。

## 工作流程

1. 当被调用时，首先运行 `git diff` 查看最近的代码变更。
2. 专注于已修改的文件，并立即开始审查。
3. 根据以下清单进行审查。

## 审查清单

- 代码清晰可读，变量和函数命名良好
- 无重复代码
- 实现了完整的错误处理
- 没有暴露的密钥或 API 密钥
- 实现了输入验证
- 有充足的测试覆盖

## 输出格式

按优先级分类输出：
- **严重 (Critical)**：必须修复的问题
- **警告 (Warning)**：应该修复的问题
- **建议 (Suggestion)**：可以改进的地方

对每个问题，给出具体的修复示例。

这个文件的结构：上半部分 --- 之间是 YAML 配置，下半部分是系统提示词（告诉 Agent 它是谁、该怎么干活）。

第 3 步：验证 Subagent 已被识别

启动 Claude Code（如果已经在运行，需要退出重新启动，或者用 /agents 命令刷新）：

claude

进去之后输入：

/agents

你应该看到：列表里除了内置的 Explore、Plan 等，多了一个 code-reviewer。如果看到了，说明文件放对位置了，Claude 已经认识它了。

如果没看到，检查两件事：

• 文件路径是不是 .claude/agents/code-reviewer.md（注意是项目根目录下的 .claude，不是 ~/.claude）
• YAML 格式有没有写错（缩进用空格，不是 Tab）

第 4 步：触发 Subagent

先制造一点代码变更，让 Subagent 有东西可以审查。

在项目里随便创建或修改一个文件。比如：

echo 'password = "123456"' > test.py
git add test.py && git commit -m "add test file"

然后回到 Claude Code 的对话界面，输入：

使用 code-reviewer 审查一下最近的代码变更。

你应该看到：

1. 界面上出现类似 Spawning agent: code-reviewer 的提示，说明 Claude 正在调用你的 Subagent
2. Subagent 开始工作 —— 它会先跑 git diff，然后逐项审查
3. 几秒到几十秒后（取决于代码量），Subagent 返回审查结果，按严重/警告/建议分类列出

如果审查结果里提到了 password = "123456" 是个安全问题，恭喜你，Subagent 在正常工作。

触发没反应？ 三种排查方式：

现象	原因	解决
没有 “Spawning agent” 提示	Claude 没识别到你想用 Subagent	改用更明确的写法：使用 code-reviewer agent 来...
提示 Agent 不存在	文件没被加载	退出 Claude Code 重新启动，或跑 /agents 确认列表
Agent 启动了但报权限错误	工具权限被拒绝	在弹出的权限提示中选 Allow

触发 Subagent 的四种写法

刚才用的是“点名叫”，其实一共有四种触发方式。掌握这四种，基本够用了。

写法一：点名叫（最靠谱）

使用 code-reviewer 审查一下 src/auth/ 目录下的代码变更。

就像在办公室喊一声“小王，帮我看看这个报表”，明确无歧义。

写法二：描述任务，让 Claude 自己判断该叫谁

帮我审查一下最近提交的代码，看看有没有安全隐患。

当你的描述跟某个 Subagent 的 description 字段匹配度高的时候，Claude 会自动把任务派过去。你应该看到 界面上出现 “Delegating to code-reviewer…” 的提示。

如果 Claude 没有自动派发，有两个办法：一是回到方式一直接点名，二是优化你 Agent 文件里的 description，加上更多关键词。在描述里写 “use proactively” 或 “主动使用” 可以提高自动触发的概率。

写法三：通过 /agents 命令选择

输入 /agents，从列表里直接点选一个 Agent，然后描述任务。适合记不住 Agent 名字的时候。

写法四：用 CLI 参数临时创建一次性 Agent

不想写文件，只想快速试一下？启动 Claude Code 的时候直接传 JSON：

claude --agents '{
  "quick-reviewer": {
    "description": "快速代码审查。在代码变更后主动使用。",
    "prompt": "你是一名高级代码审查员。专注于代码质量、安全和最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "haiku"
  }
}'

这个 Agent 只在当前会话里有效，退出就没了。用完就扔，跟一次性筷子一个道理。

前台运行 vs 后台运行

刚才的操作中，Subagent 在前台运行 —— 主对话会等它干完。如果你想一边聊天一边让它在后面忙活，这么说：

在后台运行 code-reviewer 审查所有最近的变更。

你应该看到：Claude 先弹出权限确认（因为后台任务启动后不再弹窗，所以要提前确认），确认完后 Subagent 切到后台运行，你可以继续在主对话里干别的事。

另一个办法：当 Subagent 正在前台运行时，按 Ctrl + B 把它切到后台。

后台任务如果因为权限不够失败了，你可以在前台恢复它重新给权限。

YAML 配置字段速查表

创建 Agent 文件时，name 和 description 必填，其余都是选填：

字段	必填	说明
name	是	唯一标识，小写字母加中划线
description	是	触发关键：Claude 根据这个描述决定何时委托任务
tools	否	允许使用的工具列表，省略则继承所有工具
disallowedTools	否	禁止使用的工具列表
model	否	模型选择：sonnet、opus、haiku 或 inherit（默认继承）
permissionMode	否	权限模式：default、acceptEdits、dontAsk、plan 等
maxTurns	否	最大执行轮次
skills	否	启动时预加载的 Skills
mcpServers	否	可用的 MCP 服务器
hooks	否	生命周期钩子
memory	否	持久化记忆范围：user、project 或 local

Agent 文件放在不同位置，作用范围不一样：

存放位置	作用范围	说明
.claude/agents/	当前项目	可以提交到 Git，团队共享
~/.claude/agents/	你所有的项目	个人常用 Agent
--agents CLI 参数	当前会话	临时测试，不保存到磁盘

给 Subagent 装上“长期记忆”

如果你希望 Subagent 在多次审查之后越来越了解你的代码风格，可以在配置里加 memory 字段：

---
name: code-reviewer
description: 审查代码质量和最佳实践
memory: user
---

你是一名代码审查员。在审查代码的过程中，将你发现的模式、
惯例和反复出现的问题更新到你的 agent memory 中。

加了 memory: user 之后，这个 Agent 会在 ~/.claude/agent-memory/code-reviewer/ 目录下维护一个 MEMORY.md 文件。就像你公司里那个老员工，虽然每天做的事差不多，但他知道哪些坑踩过、哪些模式是好的。

怎么验证记忆在工作：让 Subagent 审查几次代码之后，打开 ~/.claude/agent-memory/code-reviewer/MEMORY.md 看看，里面应该有它积累下来的笔记。

记忆范围有三个级别：

范围	存储位置	适用场景
user	~/.claude/agent-memory/	跨所有项目通用的经验（推荐默认）
project	.claude/agent-memory/	项目专属知识，可提交到 Git
local	.claude/agent-memory-local/	项目专属但不应提交到仓库

到这里，练习一结束。你已经会创建、触发、后台运行一个 Subagent 了。

练习二：开启并使用 Agent Teams

这个练习大约需要 10 分钟。走完全程，你能让多个 AI 同时干活，互相发消息讨论。

第 1 步：开启 Agent Teams 功能

Agent Teams 目前是实验性功能，默认关着。你需要手动打开。

先退出 Claude Code（如果正在运行的话），然后编辑配置文件：

cat ~/.claude/settings.json

你应该看到：一个 JSON 文件的内容（如果文件不存在，下一步会创建它）。

现在往里面加环境变量。如果文件已经有内容，把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 加到 env 里。如果是空文件或不存在，直接写入：

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

保存之后，重新启动 Claude Code：

claude

怎么确认开启成功：进入 Claude Code 之后，输入以下内容：

请创建一个包含 2 个 Teammate 的 Agent Team 来讨论一下当前项目的代码结构。

如果 Agent Teams 开启成功，你应该看到 Claude 开始创建团队和 Teammate。如果它没有创建团队而是自己开始分析代码，说明功能没开启，回去检查 settings.json 的格式（JSON 格式很严格，少个逗号都不行）。

如果你只是想临时试试，不想改配置文件，也可以用环境变量的方式：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

第 2 步：选择显示模式

Agent Teams 有两种显示模式，看你用哪个终端：

模式	效果	要求
进程内模式（in-process）	所有 Teammate 在同一终端窗口，用快捷键切换	无，任何终端都行
分屏模式（tmux）	每个 Teammate 独立窗格，同时看到所有人的输出	需装 tmux 或用 iTerm2

如果你不确定选哪个，先用默认的 in-process 模式，什么都不用配。等熟悉了再切 tmux。

想用 tmux 分屏的话，先确认装了 tmux：

which tmux

有输出就行。然后在 settings.json 里加一行：

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

或者启动时临时指定：

claude --teammate-mode tmux

第 3 步：创建你的第一个 Agent Team

现在正式开始。进入 Claude Code，输入以下 Prompt（你可以直接复制）：

我想了解当前项目的代码质量。请创建一个 Agent Team：
- 一个 Teammate 负责检查代码风格和可读性
- 一个 Teammate 负责检查潜在的安全问题
完成后各自汇报发现。

你应该看到的执行过程（按时间顺序）：

1. Claude（Lead）说它要创建一个团队，并描述计划
2. 界面上出现 Teammate 被创建的提示（类似 Spawning teammate: style-checker）
3. 如果用 in-process 模式，主界面下方会多出 Teammate 的状态指示器
4. 如果用 tmux 模式，终端会分成多个窗格，每个窗格里一个 Teammate 在工作
5. Teammate 各自开始分析代码，你能看到它们在读文件、跑命令
6. 几分钟后，Lead 汇总各 Teammate 的发现，给你一份综合报告

如果卡在某一步：

卡住的位置	可能原因	解决
Claude 没创建团队，自己开始分析	功能没开启	检查 settings.json，确认环境变量值是字符串 "1" 不是数字 1
提示创建了 Teammate 但看不到	用了 in-process 模式	按 Shift + 下方向键 切换查看不同 Teammate
tmux 模式下没有分屏	不在 tmux 会话里	先 tmux 进入 tmux 会话，再在里面启动 claude

第 4 步：跟 Teammate 互动

团队跑起来之后，你不是只能干看着。你可以随时插手。

在 in-process 模式下：

1. 按 Shift + 上/下方向键 在不同 Teammate 之间切换。你应该看到底部的选中状态在变化。
2. 选中一个 Teammate 后，直接打字就是在给它发消息。比如选中 style-checker 后输入：

   也检查一下有没有超过 200 行的函数。

3. 按 Enter 可以展开查看选中 Teammate 的完整会话历史。
4. 按 Esc 可以打断一个 Teammate 当前正在做的事。

在 tmux 模式下：

直接用鼠标点进某个 Teammate 的窗格，就可以跟它交互，和正常使用 Claude Code 一模一样。

试一下 Delegate 模式：

按 Shift + Tab。你应该看到界面上有提示表明已切换到 Delegate 模式。在这个模式下，Lead 只负责协调（创建 Teammate、发消息、管任务），不会自己动手写代码。

为什么需要这个？因为 Lead 有时候会“手痒”，看到任务简单就自己上了，不等 Teammate。Delegate 模式相当于跟它说“你是项目经理，别碰键盘”。

再按一次 Shift + Tab 切回去。

查看任务列表：

按 Ctrl + T。你应该看到一个任务列表弹出来，显示每个任务的状态（待处理 / 进行中 / 已完成）和负责人。

第 5 步：关闭团队并清理

Teammate 都汇报完之后，善后操作：

先关闭 Teammate：

请让所有 Teammate 关闭。

你应该看到：每个 Teammate 依次收到关闭请求并退出。

然后清理团队资源：

清理团队。

你应该看到：提示团队已清理完毕。

注意两件事：

• 清理操作得让 Lead 来执行，别让 Teammate 自己清理，不然可能留下残余文件
• 团队配置存在 ~/.claude/teams/{team-name}/，任务列表存在 ~/.claude/tasks/{team-name}/，清理命令会删除这些

如果用了 tmux 模式，额外检查一下有没有残留的 tmux 会话：

tmux ls

有残留的话：

tmux kill-session -t <session-name>

到这里，练习二结束。Agent Teams 从开启到关闭，该踩的点都踩过了。

快捷键速查表

练习过程中用到的快捷键，汇总在这里方便查：

快捷键	功能	适用模式
Shift + 上/下	切换选中的 Teammate	in-process
Enter	查看选中 Teammate 的完整会话	in-process
Esc	中断 Teammate 当前操作	in-process
Ctrl + T	显示/隐藏共享任务列表	所有模式
Shift + Tab	切换 Delegate 模式	所有模式
Ctrl + B	前台任务切到后台	所有模式

四个实用场景的 Prompt 模板

两个练习做完了，基本操作差不多了。下面是四个常见场景的 Prompt 模板，直接复制改改就能用。

场景一：多维度代码审查

对一个 PR 做体检，拆成不同角度：

创建一个 Agent Team 来审查 PR #142。生成三个审查员：
- 一个专注于安全影响
- 一个检查性能问题
- 一个验证测试覆盖率
让他们各自审查并汇报发现。

单个审查员看代码容易盯着一个方向看。拆开之后安全、性能、测试三条线同时走，漏网的东西少很多。

场景二：竞争性假设调查

Bug 的根因不明确，让多个 Agent 各自提出假设，互相推翻：

用户报告应用在发送一条消息后就退出了，而不是保持连接。
生成 5 个 Agent Teammates 来调查不同的假设。
让他们互相交流，试图推翻彼此的理论，就像一场科学辩论。
将最终共识更新到 findings.md 中。

这种“辩论式调查”特别适合 Agent Teams。一个人查 Bug 容易“先入为主” —— 找到一个说得通的原因就停了。五个人互相挑刺，活下来的那个假设大概率才是真正的根因。

场景三：并行研究一个新方向

需要从多个角度同时探索一个问题：

我正在设计一个帮助开发者追踪 TODO 注释的 CLI 工具。
请创建一个 Agent Team 来从不同角度探索这个问题：
一个 Teammate 负责用户体验设计，
一个负责技术架构，
一个扮演魔鬼代言人的角色来挑战前两个人的想法。

场景四：高风险任务要求计划审批

让 Teammate 先出方案，Lead 审批后再动手：

生成一个架构师 Teammate 来重构认证模块。
要求在做出任何修改之前先获得计划审批。
只批准包含测试覆盖的计划。

你应该看到：Teammate 会先输出一份计划，然后发送审批请求给 Lead。Lead 审核通过后 Teammate 才开始动手。如果 Lead 觉得计划不行，会拒绝并给出反馈，Teammate 修改后重新提交。

进阶：让多 Agent 协作更顺滑

基础操作熟练之后，这两个技巧能帮你避开常见的坑。

用 Git Worktree 避免文件冲突

Agent Teams 并行开发时，两个 Teammate 改同一个文件会互相覆盖。解决方案是用 git worktree 给每人一个独立的工作目录：

使用 Agent Teams 的 delegate 模式来执行 GitHub Issue #557 的所有子任务。
为每个子任务创建一个独立的 git worktree 来隔离代码变更，
完成后 fast-forward merge 到父分支。

就像装修房子，水电工和木工各在各的房间施工，互不干扰，最后统一验收。

用 Hooks 自动拦截有问题的产出

Agent Teams 支持两个专属的 Hook 事件：

• TeammateIdle：Teammate 即将空闲时触发。Hook 脚本返回退出码 2 可以阻止空闲，把反馈发回去让它继续干。
• TaskCompleted：任务被标记完成时触发。返回退出码 2 可以阻止任务完成，发送反馈要求修改。

配合 PreToolUse Hook 还能做更精细的控制。比如创建一个只允许 SELECT 查询的数据库 Agent：

---
name: db-reader
description: 执行只读数据库查询
tools: Bash
hooks:
  PreToolUse:
  - matcher: "Bash"
    hooks:
    - type: command
      command: "./scripts/validate-readonly-query.sh"
---

Hook 脚本会在每次 Bash 命令执行前检查，发现 INSERT、UPDATE、DELETE 这些写操作直接拦截。相当于给数据库上了把只读锁。

什么场景用什么方案

你的需求	推荐方案	怎么触发
执行定义明确的单一任务	Subagent	“使用 test-runner 运行所有单元测试”
隔离大量输出的操作	Subagent（后台）	“在后台使用 log-analyzer 分析日志”
多角度并行研究	Agent Team	“创建一个三人团队分别研究…”
并行开发多个模块	Agent Team + Worktree	“组建团队并使用 git worktree 隔离开发”
高风险重构	Agent Team + 计划审批	“要求在修改前获得计划审批”
自动化代码审查	Hooks + Subagent	在 settings.json 中配置 stop hook

常见问题排查

问题	原因	解决方案
输入 Prompt 后 Agent Team 没创建	未启用实验性功能	检查 settings.json 中 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 是否为 "1"
Teammate 创建了但看不到	用了 in-process 模式	按 Shift + 下 切换查看，或改用 tmux 模式
Lead 自己开始写代码	未启用 Delegate 模式	按 Shift + Tab 切换，或在 Prompt 中说“等待 Teammates 完成”
Subagent 没有被自动触发	description 与指令不够匹配	改用显式触发（“使用 xxx agent…”），或优化描述中的关键词
tmux 会话结束后仍存在	清理不完整	tmux ls 查看，tmux kill-session -t <name> 清理
恢复会话后 Teammate 不存在	in-process 模式不支持恢复	让 Lead 重新创建 Teammate

写在最后

不管用 Subagent 还是 Teams，触发的核心方式都是自然语言。配置文件是“注册能力”，在对话框里说清楚你想干什么就是“激活能力”。Subagent 适合“给我结果就行”的活，Agent Teams 适合需要几个人碰头才能搞定的事。一个人能干的活不用拉群。

另外 Agent Teams 毕竟还是实验性功能，有些已知的毛病 —— in-process 模式下恢复会话不会恢复 Teammate，任务状态偶尔同步得慢，一个 Lead 同时只能管一个团队。拿它做正经项目之前，建议先拿小任务跑跑看。

对于后端开发和系统设计这类复杂任务，合理利用多AI代理可以显著提升分析和实施效率。如果你想了解更多关于这类工具的使用技巧和配置细节，可以查阅相关的技术文档和社区分享。

你在实际使用 Claude Code 多 Agent 协作时踩过什么坑？或者发现了什么好用的触发技巧？欢迎到技术社区交流讨论。