agent-teams

Agent 团队

实验性：Agent 团队需要设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，并且可能会随 Claude Code 版本变化。

重大变更（Claude Code 2.1.178）：显式的 TeamCreate / TeamDelete 工具已被移除。现在，每个会话在设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 时都会有一个隐式团队——无需创建或拆除。之前接受该参数的工具（例如 Agent）仍接受但忽略 team_name 参数，因此旧调用不会报错；新代码中请省略该参数。其他协调方式不变：使用 Agent 工具生成队友，使用 SendMessage 进行协调，并使用 TaskCreate/TaskList/TaskUpdate 跟踪工作。

有关完整示例设置、通信片段、关闭流程、工作树路径解析恢复流程和常见任务分派模式，请参阅 REFERENCE.md。

何时使用此技能

在以下情况下使用 Agent 团队……	在以下情况下改用子 Agent……
多个 Agent 需要并行工作	任务是顺序执行且相互依赖的
需要 Agent 之间持续通信	一个专注任务只产生一个结果
后台任务需要报告进度	Agent 的输出会直接作为下一步的输入
复杂工作流需要任务协调	执行简单、范围明确且相互隔离
对同一代码库进行独立更改（使用工作树）	共享上下文可行且高效

子 Agent 注意事项：从主线程生成团队

即使父对话中有 Agent 和相关的并行生成工具，这些工具也可能不会出现在 子 Agent 的工具界面中。旨在协调自身团队的子 Agent 可能会悄然退化为顺序单线程执行——内容相同，耗时约为 5 倍——而且直到完成后的摘要才会暴露这一问题。

情况	推荐模式
从主对话中分派多个任务	直接并行调用 Agent——可使用完整工具集
子 Agent 协调自己的团队	设计时避免：拆分工作，让主线程负责分派
子 Agent 必须协调团队	预先检测工具是否可用；将顺序回退作为首要结果报告

检测要求：向负责协调的子 Agent 说明以下要求：确认可调用 Agent 工具；如果不可调用，不要悄然回退——在摘要首行报告“此沙盒中无法并行分派；已按顺序执行。”，然后使用相同的输入约定继续顺序执行。尽可能在主对话中规划顶层协调工作。

原生团队工具

隐式团队（2.1.178）无需创建或删除步骤——这些工具会作用于会话已有的团队：

工具	用途
Agent	生成一名队友（为其指定 name；team_name 会被接受但忽略）
SendMessage	发送私信、广播、关闭请求和计划审批
TaskCreate / TaskList / TaskUpdate	创建、发现并分配或推进共享任务
TaskOutput	获取后台 Agent 的输出
TaskStop	停止正在运行的后台 Agent

设置流程——TaskCreate → 通过 Agent 工具生成队友（指定 name）→ 使用 TaskUpdate 分配任务 → 自动接收结果——请参阅 REFERENCE.md → 团队设置工作流 中的完整代码。 队友的消息会在轮次之间送达负责人收件箱；无需轮询。

任务管理

状态	含义
pending	尚未开始
in_progress	已分配且正在执行（每名队友一次只能处理一项）
completed	已成功完成
blocked	正在等待另一项任务（blocked_by 字段）

队友通过 TaskList + TaskUpdate 按ID 顺序（从低到高）认领任务，并跳过被阻塞的任务，直到其阻塞项完成。

通信（SendMessage）

类型	使用场景
message	向特定队友发送私信（recipient = name，而不是 agentId）
broadcast	向全体团队成员发布重要公告（N 位队友 = N 次往返通信——请谨慎使用）
shutdown_request / shutdown_response	队友优雅退出握手
plan_approval_response	批准或拒绝队友的计划

DM、broadcast 和发现（Read ~/.claude/teams/<name>/config.json → members）示例见 REFERENCE.md → Communication。

队友规则要点

• 同一时间恰好将一个任务标记为 in_progress。
• 使用 TaskUpdate（而非 SendMessage）报告任务完成情况。
• 每轮之后处于空闲状态是正常的——空闲 ≠ 不可用；收到消息后队友会被唤醒。
• 所有通信都必须通过 SendMessage——纯文本输出对负责人不可见。
• recipient 使用 name 字段（而非 agentId）。

负责人预检清单

在起草 PRP 并启动 Agent 之前，花 30 秒检查一遍，可避免 Agent 返回后需要进行大量多文件重命名工作：

检查项	命令	原因
下一个 ADR/PRD/PRP 序号	ls docs/blueprint/adrs/ | sort -V | tail -1	避免并行编写文档时发生编号冲突
文件名冲突	git ls-files | grep <filename>	范围表无法防止对目录树形成过时的主观认知
硬件引脚预算（嵌入式）	阅读 pin_config.h 或同等文件	避免 Phase 1 Agent 分配的引脚相互重叠

范围外发现协议

当 Agent 拥有专属写入范围时，请在每个 Agent 的提示词中加入范围外发现协议，以避免“调查范围外内容 → 耗尽预算 → 摘要被截断”的失败模式。请从 REFERENCE.md → Out-of-scope discovery protocol 复制原文：遇到范围外依赖时，Agent 立即停止，将其列在摘要的 Out-of-scope dependencies 小节下，然后退出，由负责人进行分流处理。

Worktree 隔离风险

Worktree 隔离的 Agent 可能会让 Edit/Write 将相对路径静默解析到父级仓库，而非其 worktree 中（上游 bug #1091），从而在没有即时提示的情况下将提交放到错误的分支。请为每个 worktree 隔离 Agent 的提示词添加绝对路径前置说明，运行负责人事后检查（从父级目录执行 git diff origin/main..HEAD + git status --porcelain），并使用 cherry-pick + rebase 恢复流程——所有内容均见 REFERENCE.md → Worktree path resolution。 另请参阅 .claude/rules/agent-coworker-detection.md。

恢复 Worktree 隔离的 Agent

对已完成的 worktree 隔离 Agent（Agent，且 isolation: "worktree"）使用 SendMessage 恢复，会失去 worktree 隔离——恢复后的运行会在编排器的主检出目录中执行，而非 worktree。对于并行修改文件的工作，请重新派发一个全新的 isolation: "worktree" Agent，而不要恢复原 Agent；仅将 SendMessage 恢复用于只读工作或单检出目录中的后续任务。参见 parallel-agent-dispatch → “恢复 Agent：SendMessage 会失去 worktree 隔离”（问题 #1546）。

沙盒注意事项

在 Web 会话中（CLAUDE_CODE_REMOTE=true）：

• 子 Agent（队友）执行 git push 时可能遇到 TLS 错误——请将所有推送/PR 操作交给负责人。
• 每位队友都在各自独立的进程上下文中运行。
• 对彼此独立的文件系统更改，建议使用 worktree 隔离。

Agent 式优化

上下文	方法
快速并行审查	启动 2–4 位队友并分配任务
拆分大型代码库	将不同目录子集分配为独立任务
长时间运行的工作	让队友在后台工作，并通过 TaskList 轮询
尽量降低 API 成本	优先使用 message，而非 broadcast
快速关闭	向每位队友发送 shutdown_request（无需拆除团队）

快速参考

工作流检查清单

• 已设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（隐式团队已存在；无需创建）
• 为每个工作单元调用 TaskCreate
• 通过 Agent 工具启动队友并指定 name（无需指定 team_name）
• 调用 TaskUpdate 分配任务（或让队友自行认领）
• 自动接收消息；通过 SendMessage 回复
• 完成后向每位队友发送 SendMessage shutdown_request（无需调用 TeamDelete）

关键路径

路径	内容
~/.claude/teams/	隐式团队状态（成员：name、agentId、agentType）
~/.claude/tasks/	共享任务列表状态

通过启动时指定的 name 称呼队友——这是可靠的标识，与磁盘上的任何布局无关。

常见错误

错误	正确做法
使用 agentId 作为接收方	使用启动时指定的 name
调用已移除的 TeamCreate/TeamDelete	团队是隐式的（2.1.178）；使用 Agent 启动，并通过 shutdown_request 关闭
传入 team_name 并期待消息路由	系统会接受该参数，但会忽略——只有一个隐式团队
每次更新都发送广播	单接收方通信使用 message
轮询消息	消息会自动送达——只需等待
发送 JSON 状态消息	状态使用 TaskUpdate，消息使用纯文本
子 Agent 推送到远程仓库	将推送任务委派给主协调者

相关技能和规则

• parallel-agent-dispatch — 工作树预检、范围预算，以及每位队友退出时必须提供的返回约定。团队调度是普通并行分发的超集；两者都要遵循。
• .claude/rules/agent-development.md — Agent 文件结构、模型选择、工作树隔离
• .claude/rules/agentic-permissions.md — 细粒度工具权限模式
• .claude/rules/sandbox-guidance.md — Web 沙箱限制和推送委派