目录
代理团队协调
概述
Claude Code 代理团队（Agent Teams）使多个 Claude CLI 进程能够通过基于文件系统的协调协议协作完成共享工作。每个团队成员作为独立的 claude 进程在 tmux 窗格中运行，通过受 fcntl 锁保护的 JSON 文件进行通信。无需数据库、守护进程或网络层。
此技能提供了有效编排代理团队的模式。
何时使用
- 跨多个文件或模块的并行实现
- 多代理代码审查（一个代理审查，另一个代理实施修复）
- 需要跨子系统协调更改的大型重构
- 具有自然并行性且能受益于并发代理的任务
何时不使用
- 单文件更改或小任务（开销超过收益）
- 需要紧密顺序推理的任务（代理之间松散协调）
- 当
claudeCLI 不可用或 tmux 未安装时
前提条件
# 验证 Claude Code CLI
claude --version
# 验证 tmux（需要分屏模式）
tmux -V
# 启用实验性功能（由生成器自动设置）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
协议架构
~/.claude/
teams/<team-name>/
config.json # 团队元数据 + 成员名册
inboxes/
<agent-name>.json # 每个代理的消息队列
.lock # fcntl 独占锁
tasks/<team-name>/
1.json ... N.json # 自动递增的任务文件
.lock # fcntl 独占锁
设计原则：
- 文件系统即数据库：JSON 文件，通过
tempfile+os.replace实现原子写入 - fcntl 锁定：防止收件箱和任务上的并发读/写损坏
- 编号任务：使用顺序文件命名自动递增 ID
- 松散耦合：代理轮询自己的收件箱；无推送通知
快速开始
1. 创建团队
# 程序化团队设置（通过 MCP 或直接 API）
# 团队配置写入 ~/.claude/teams/<team-name>/config.json
团队配置包含：
name,description,created_at（毫秒时间戳）lead_agent_id,lead_session_idmembers[]— LeadMember 和 TeammateMember 对象数组
2. 生成队友
每个队友是一个独立的 claude CLI 进程，使用身份标志启动：
claude --agent-id "backend@my-team" \
--agent-name "backend" \
--team-name "my-team" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
有关 tmux 窗格管理和颜色分配的详细信息，请参阅 modules/spawning-patterns.md。
3. 创建具有依赖关系的任务
{
"id": "1",
"subject": "实现 API 端点",
"description": "为用户管理创建 REST 端点",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
有关状态机和依赖管理的详细信息，请参阅 modules/task-coordination.md。
4. 通过消息协调
{
"from": "team-lead",
"text": "API 端点已准备好进行集成测试",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API 已就绪"
}
有关消息类型和收件箱操作的详细信息，请参阅 modules/messaging-protocol.md。
协调工作流程
agent-teams:team-created— 初始化团队配置和目录agent-teams:teammates-spawned— 在 tmux 窗格中启动代理agent-teams:tasks-assigned— 创建具有依赖关系的任务，分配负责人agent-teams:coordination-active— 代理认领任务，交换消息，标记完成agent-teams:team-shutdown— 通过批准协议优雅关闭
团队角色
每个团队成员都有一个 role，决定其能力和任务兼容性。定义了五种角色：implementer（默认）、researcher、tester、reviewer 和 architect。角色限制了代理可以处理的风险层级——有关完整的能力矩阵和角色-风险兼容性表，请参阅 modules/crew-roles.md。
健康监控
团队成员的健康状况可以通过心跳消息和认领到期进行监控。领导每 60 秒轮询一次团队健康状态，采用两阶段停顿检测协议（健康检查探针 + 30 秒等待）。停顿代理的任务将被释放，并按照“替换不等待”的原则重启或替换。有关完整协议和状态机，请参阅 modules/health-monitoring.md。
模块参考
- team-management.md：团队生命周期、配置格式、成员管理
- messaging-protocol.md：消息类型、收件箱操作、锁定模式
- task-coordination.md：任务 CRUD、状态机、依赖循环检测
- spawning-patterns.md：tmux 生成、CLI 标志、窗格管理
- crew-roles.md：角色分类法、能力矩阵、角色-风险兼容性
- health-monitoring.md：心跳协议、停顿检测、自动恢复
与 Conjure 集成
代理团队扩展了 conjure 委派模型：
| Conjure 模式 | 代理团队等效项 |
|---|---|
delegation-core:task-assessed | agent-teams:team-created |
delegation-core:handoff-planned | agent-teams:tasks-assigned |
delegation-core:results-integrated | agent-teams:team-shutdown |
| 外部 LLM 执行 | 队友代理执行 |
首先使用 Skill(conjure:delegation-core) 确定任务是否受益于多代理协调而不是单服务委派。
工作树隔离替代方案（Claude Code 2.1.49+）
对于修改文件的并行代理，isolation: worktree 提供了基于文件系统协调的轻量级替代方案。每个代理在自己的临时 git 工作树中运行，无需 fcntl 锁定或基于收件箱的冲突避免来处理共享文件。
- 何时优先选择工作树而非代理团队消息：代理处理重叠文件但不需要执行中通信时
- 何时优先选择代理团队消息：代理需要协调发现或根据彼此的进度调整计划时
- 两者结合使用：将代理团队用于协调，并为每个队友使用
isolation: worktree以确保文件系统安全
故障排除
常见问题
未找到 tmux
通过包管理器安装：brew install tmux / apt install tmux
过期的锁文件
如果代理在操作中崩溃，锁文件可能会持续存在。手动从 ~/.claude/teams/<team>/inboxes/ 或 ~/.claude/tasks/<team>/ 中删除 .lock 文件。
孤立任务
由崩溃代理认领的任务会无限期保持 in_progress 状态。使用 modules/health-monitoring.md 进行基于心跳的停顿检测和自动任务释放。健康监控协议在 60 秒 + 30 秒探针窗口内检测无响应代理，并释放其任务以供重新分配。
消息排序 文件系统时间戳分辨率各不相同（HFS+ = 1 秒粒度）。使用编号文件名或 UUID 排序名称以避免快速消息突发时的冲突。
Bedrock/Vertex/Foundry 上的模型错误（2.1.39 之前） 队友代理可能在企业提供程序上使用错误的模型标识符，导致 400 错误。升级到 Claude Code 2.1.39+ 以在所有提供程序上获得正确的模型 ID 限定。
嵌套会话保护（2.1.39+）
如果 claude 拒绝在现有会话中启动，请确保您使用的是 tmux 窗格拆分（而不是子 shell 调用）。此保护是有意为之——有关详细信息，请参阅 modules/spawning-patterns.md。
退出标准
- 已创建团队配置和目录
- 队友已生成并注册到配置中
- 已创建具有依赖图的任务（无循环）
- 代理通过收件箱消息进行协调
- 已完成优雅关闭