Claude Code多Agent机制怎么选
“这个问题能不能多开几个 Agent 一起查？”
很多小伙伴第一次接触多 Agent，最先想到的是把数量拉上去。实际项目里，Agent 数量只是一个参数。任务能否拆开、多个分支会不会改同一批文件、谁负责汇总证据、权限请求由谁处理，这些问题更影响结果。
单个 Claude 主线能完成的任务可以保持单线程。出现相互独立、验收标准明确的调查分支后，再考虑并行。并行可以缩短等待时间，也会增加上下文、Token、协调和代码冲突。
先看一个库存对账案例
凌晨库存对账任务报警，同一个入库单在账面库存里增加了两次。仓库原始流水只有一条，inventory_ledger 却出现两条金额和数量完全相同的记录。
现在有四条调查线：
- 查消费端是否重复消费了消息；
- 查数据库有没有业务唯一约束；
- 查补偿任务会不会与实时消费同时写账；
- 补一组并发回归测试，稳定复现重复入账。
四条线看起来适合并行，但它们的写入风险不一样。前三条可以先只读调查，第四条要改测试代码。主 Agent 如果一上来让四个角色都自由修改仓库，大家很可能同时碰 InventoryLedgerService、Mapper 和同一个测试类。
一个更稳的分工是：
| 角色 | 输入 | 允许动作 | 输出 |
|---|---|---|---|
| 主 Agent | 报警、仓库、日志入口 | 统一计划，最后整合 | 根因链路、修改方案、验证结果 |
| 消息调查 Agent | 消费者和消息字段 | 只读搜索 | Ack、重试、幂等键证据 |
| 数据调查 Agent | 表结构和写入语句 | 只读搜索 | 索引、事务、并发窗口证据 |
| 测试 Agent | 已确认的可疑路径 | 独立 Worktree 写测试 | 可复现用例和运行结果 |
这张任务图先解决了“哪些工作可以同时做”。接下来才轮到 Claude Code 里的具体机制。
四种机制解决的问题不一样
Claude Code 当前常见的并行或分支能力可以放进一张表里看：
| 机制 | 所在位置 | 上下文关系 | 协作特点 | 我会用在什么地方 |
|---|---|---|---|---|
| Subagent | 主会话内部 | 有自己的上下文窗口，接收主 Agent 交代的任务 | 完成后把结果交回主 Agent | 搜索、审查、测试、专项调查 |
/subtask | 当前会话中的支线任务 | 从当前任务派生，在会话里跟踪 | 适合把一个明确支线交给后台处理 | 不想打断主线的短调查或验证 |
/fork | 独立后台 Session | 从当前会话复制出新的独立 Session | 分叉后各走各的，可单独继续 | 同一上下文下探索另一套方案 |
| Agent Teams | 多个独立 Claude Code 实例 | 每个 Teammate 有独立上下文 | 共享任务列表，可互相通信 | 规模较大的研究、评审和多模块并行 |
这四种能力没有固定的强弱顺序。面试中如果只回答“Agent Teams 最强”，面试官很容易继续追问：一个十分钟的只读检索为什么要启一个团队？多个成员如何避免改到同一个类？花掉的 Token 怎么控制？
Subagent适合边界清楚的专项工作
Subagent 是主 Agent 派出的专门角色。它有自己的上下文，主对话里大量聊天记录不会全部塞进这个窗口；主 Agent 会把任务说明交给它，它完成后再返回结果。
这种隔离有两个直接价值：
- 大范围搜索产生的中间噪声留在 Subagent 里；
- 可以给角色配置更窄的工具和更具体的系统提示。
例如我们可以定义一个只读的数据库审查角色：
---
name: ledger-schema-reviewer
description: 调查库存台账的表结构、唯一约束、事务边界和写入入口，只返回带文件位置的证据。
tools: Read, Grep, Glob
model: sonnet
---
检查库存台账重复写入风险。输出必须包含：
1. 表结构和索引位置；
2. 所有INSERT入口；
3. 事务注解或事务模板位置；
4. 仍无法确认的事实。
不要修改文件，也不要根据类名猜测运行行为。
项目级自定义 Subagent 通常放在 .claude/agents/，用户级角色可以放在 ~/.claude/agents/。通过 /agents 可以查看和管理当前可用角色。团队想共享审查规范时，项目级配置更方便进入版本管理。
Subagent的任务说明要能单独验收
下面这种委派太宽：
帮我看看库存为什么错了，顺便修一下。
Subagent 不知道报警时间、订单标识、允许修改的范围，也不知道最终要交证据还是交代码。它很容易把猜测写成结论。
我会改成：
只读调查库存台账重复入账。样本入库单为 IN-20260806-1042，
两条ledger记录相差420ms。请搜索消息消费者、补偿任务和所有
inventory_ledger写入口，输出文件路径、方法名、调用关系以及三个
最可能的竞争窗口。不要修改文件，不要启动外部服务。
任务说明里至少要有样本、范围、动作边界和输出格式。能否并行，往往在这一步就能看出来。
Explore角色用于搜索，不要记死它的模型
Claude Code 内置的 Explore Subagent 擅长快速搜索和读取代码。当前官方说明中，从 v2.1.198 开始，Explore 会继承主会话使用的模型。面试时把它固定说成某个轻量模型，很容易被版本更新打脸。
更稳的回答方式是说清角色：Explore 面向只读代码探索，具体模型以当前配置和版本为准。
/subtask适合当前会话里的支线
主线正在分析重复入账调用链时，我还想让 Claude 在后台跑一组现有库存测试。这项工作与当前分析有关，结果也要回到当前会话，但没有必要让主线停在那里等命令结束。
这类支线可以考虑 /subtask。它仍属于当前会话的任务管理范围，用户能够查看状态和结果。适合的任务通常有三个特点：
- 开始条件已经满足；
- 执行过程不需要频繁向用户追问；
- 结果可以用一段清楚的摘要或测试日志交付。
如果后台任务很可能弹出权限请求，主线仍然要留意。把任务放进后台不等于它自动获得更多权限。
/fork适合保留现场后另开一条路
有时主会话已经积累了完整上下文，我想保留这条调查线，同时试另一套思路。例如：
- 当前 Session 继续沿“消息重复投递”排查；
- Fork 出来的 Session 改查“补偿任务并发写入”；
- 两边各自保留推理和工具记录，互不挤占后续对话。
/fork 会把当前会话复制成独立的后台 Session。分叉发生以后，两条 Session 独立推进，后续消息不会自动双向同步。
因此，Fork 之前最好在上下文里留下一个短状态块：
当前已确认：
- IN-20260806-1042存在两条ledger；
- 两条记录来自不同trace_id；
- 消费者与补偿任务都调用appendLedger。
未确认：
- 两个入口是否使用同一幂等键；
- 唯一索引是否覆盖warehouse_id和receipt_no。
本分支目标：只调查补偿任务与实时消费的并发窗口。
这样两个 Session 都从可核对的事实出发。Fork 只是复制起点，分支之间的结论整合仍要由人或某个明确的主线完成。
Agent Teams用于需要成员直接协作的任务
Agent Teams 会启动一个 Team Lead 和多个 Teammate。每个成员拥有独立上下文，团队共享任务列表，成员之间还能发送消息。它比“主 Agent 派几个只返回最终结果的 Subagent”多了一层协作能力。
库存案例扩大后，Agent Teams 才开始有价值。假设问题牵涉三个仓储服务、一个消息平台和一套数据修复工具：
- Teammate A 调查入库服务；
- Teammate B 调查库存台账服务；
- Teammate C 审查数据修复方案；
- Team Lead 维护依赖关系、汇总证据并控制最终修改。
如果 B 发现幂等键来自 A 负责的消息字段，它可以直接把字段证据发给 A。共享任务列表也能标出哪些调查已经完成、哪些工作被依赖阻塞。
Agent Teams当前仍要显式开启
Agent Teams 目前属于实验能力，默认关闭。启用方式和配置项可能随着版本变化，使用前要查当前官方文档。把实验功能引入团队流程时，还要先约定失败后的回退方式，例如退回主 Agent 加 Subagent 的协作模式。
什么时候团队显得太重
下面几种任务，我通常不会启动 Agent Teams：
- 只需要查三个类和一张表；
- 所有分支最终都要修改同一个 Service；
- 任务没有明确的完成条件；
- 项目很小，启动成员和同步上下文的成本已经接近实际工作量；
- 用户需要频繁确认每一步，成员会反复等待同一个决策。
团队机制会增加通信、任务认领、状态同步和结果整合。任务本身缺少边界时，多开成员会把模糊放大。
权限不会因为多Agent自动放宽
主 Agent 能使用某个工具，不代表所有子任务都应该拿到同样范围。自定义 Subagent 可以限制工具，也可以配置权限模式。权限设计我一般按最小动作来做：
| 角色 | 建议权限 |
|---|---|
| 代码搜索 | Read、Grep、Glob |
| 测试执行 | Read、Bash，限制可执行命令 |
| 文档整理 | Read、Edit，只允许目标目录 |
| 安全审查 | 只读，不允许网络和写文件 |
| 修复实现 | 按任务开放Edit、Write、Bash，保留高风险确认 |
Subagent 执行中遇到未授权动作时，权限请求会回到主流程处理。后台任务如果正在等待批准，看起来就像“卡住了”。排查时应该先看任务状态和权限提示，别盲目重启一份相同任务。
高风险操作仍由权限系统、Sandbox、基础设施账号和人工审批兜住。提示词中的“不要操作生产”只能表达意图，无法替代真正的访问控制。
共享工作区最容易制造假并行
多个 Agent 在同一目录里写代码，会共享文件系统状态。A 修改了 InventoryLedgerService.java，B 下一次读取时就可能看到这份尚未验证的修改。它们还可能同时格式化、重命名或覆盖同一文件。
这种协作有几个典型风险：
- 修改归属不清：很难确认哪段代码来自哪个任务；
- 前提悄悄变化：后启动的 Agent 基于别人未完成的代码继续推理；
- 测试互相污染：一个分支改了配置，另一个分支的测试结果随之变化；
- 覆盖用户改动：工作区原本就有未提交内容时，风险更大。
开始并行写入前，先记录 git status --short。发现已有修改后，要把它当作用户的工作保留下来，不能默认可以清理。
独立写入可以用Git Worktree隔开
如果两个实现分支真的互不依赖，可以给它们不同 Worktree：
git worktree add ../inventory-ledger-review -b review/inventory-ledger
git worktree add ../inventory-replay-test -b review/inventory-replay-test
每个 Worktree 有独立工作目录和分支，文件修改不会互相覆盖。它们仍共享同一个 Git 对象库，所以占用通常比复制两份仓库小。
Worktree 解决文件隔离，还没有解决逻辑冲突。两个分支如果都改了幂等组件，最终合并仍然可能冲突。分配任务时要标清目录所有权、公共接口变更和合并顺序。
多Agent的成本怎么算
每个独立上下文都要读取任务说明、相关代码和返回材料。并行节省的是墙上时间，也就是人实际等待的时间；总 Token 和总计算量通常会上升。
可以把成本粗略拆成：
总成本 = 各Agent读取与推理 + Agent之间通信 + 主线整合 + 冲突返工
任务拆得太细时，每个 Agent 都要重复理解仓库背景。任务拆得太粗时，它们又会在内部做大量无关搜索。一个实用判断是：单个分支能否用三到五句话写清输入、边界、交付物和验收。 写不清时，先继续拆任务模型，别急着启动。
控制成本的六个动作
- 让调查角色先只读，确认根因后再开放写入；
- 给每个角色限定目录、样本编号和输出格式；
- 返回结论时带文件位置，少贴大段原始日志；
- 主 Agent 只把必要背景发给分支；
- 同一个问题已有分支在查时，不重复启动第二份；
- 设定停止条件，证据不足就明确标成未知。
调度失败时会出现什么症状
多 Agent 出问题时，表面症状经常是进度慢或结论乱。沿着证据、权限、任务状态和工作区隔离检查，通常能找到具体原因。
大家都很忙，没人能给根因
任务被拆成“看看消息”“看看数据库”“看看测试”，输出只有概括，没有文件、方法、日志或数据。主 Agent 收到三份泛泛的总结后仍要重查一遍。
修正方法是把证据格式写进任务：文件路径、关键字段、调用入口、确认事实、未确认事实。
两个Agent给出相反结论
先比较它们使用的输入版本和样本范围。一个查的是实时消费者，另一个查的是旧版补偿任务，结论当然可能不同。主 Agent 应该回到原始证据，不能用“少数服从多数”替代验证。
后台任务一直没有结果
依次检查：
- 是否在等待工具权限；
- 是否缺少用户选择；
- 命令是否持续运行；
- 任务范围是否没有结束条件；
- 所在 Session 是否已经与主线分叉。
合并后测试全坏了
分别在各 Worktree 验证，再检查公共接口和配置变更。单分支通过只能证明局部状态可用，最终组合仍要跑集成测试。
给库存案例安排一套可执行方案
我会把整个过程分为四轮。
第一轮：主Agent固定现场
- 记录
git status --short； - 保存异常入库单、两条台账ID、时间差和trace_id；
- 找到消费者、补偿任务和台账写入的入口；
- 明确当前阶段只读，不做数据修复。
第二轮：并行调查
- Subagent A 查消息Ack、重试和幂等字段；
- Subagent B 查索引、事务和所有INSERT；
- Subagent C 查补偿任务的扫描条件与锁；
- 主 Agent 继续还原生产时间线。
三个分支只返回证据，不改代码。这样它们可以安全共享工作区。
第三轮：单点确定根因
假设证据最终显示：实时消费按 message_id 去重，补偿任务按 receipt_no 查询完成状态；两个入口在检查后都调用 appendLedger，台账表也没有 (warehouse_id, receipt_no, line_no) 唯一索引。
这里存在典型的先查后写竞争窗口。主 Agent 应先确认业务唯一键，再决定数据库约束、写入语句和异常处理。根因没有确认前，让多个 Agent 各自实现一版幂等会产生更多分歧。
第四轮：隔离实现和验证
- 一个 Worktree 实现唯一约束与原子写入；
- 另一个 Worktree 先写并发复现测试；
- 主线审查迁移脚本对历史重复数据的影响；
- 合并后运行单元测试、并发测试和迁移演练。
这套安排里，并行主要用于调查和独立测试。最终业务键与数据修复方案仍由一条主线决策，责任比较清楚。
面试回答可以这样组织
Claude Code里的多Agent能力要按协作关系来选。Subagent有独立上下文，适合主Agent派出搜索、测试和专项审查，结果再回到主线；/subtask适合当前会话中的后台支线；/fork复制当前上下文并形成独立Session，适合保留现场后探索另一条路线；Agent Teams提供独立成员、共享任务列表和成员通信，适合多模块协作，目前仍是实验能力。并行前我会检查任务是否可以独立验收、是否会写同一批文件、权限怎样回流以及总Token成本。只读调查可以共享工作区，独立写入优先使用Git Worktree。最终结论由主线根据代码、日志、数据和测试统一验证。