Agent Team Handoff Agent Skill

多 Agent 协作交接（agent-team-handoff）

把一群 AI 助手变成一支有纪律的团队：谁在干什么、干到哪了、下一步是什么，全部落在文件里，任何成员随时接续。

一、共享目录约定（团队唯一事实源）

在项目外建一个共享目录（示例名 .team-shared/），固定放四份文件：

| 文件 | 内容 | 更新时机 |

|---|---|---|

| CURRENT-TASK.md | 当前任务交接单（状态/负责人/进度/下一步/证据） | 每次实质进展 |

| HANDOFF-RULES.md | 团队协作规则全文（本技能的本地化版本） | 规则变更时 |

| MEMORY-SNAPSHOT.md | 共享记忆快照（决策、偏好、踩坑） | 定期/重大决策 |

| AGENT-ROLES.md | 成员角色表与能力分工 | 编制变化时 |

> 规则：所有成员只认这份目录，聊天记录不算数。

二、铁律五条

• 先读再动：开始任何任务前，先读 CURRENT-TASK.md。
• 接续不重做：交接单状态为「进行中」时，从记录的当前步骤继续，禁止从头重来。
• 进展留痕：有实质进展立即回写交接单（进度 + 当前步骤 + 下一步 + 证据）。
• 切换先交接：暂停或移交前，把交接写完整，状态改为「等待接续」。
• 完成附证据：改「已完成」必须带验收证据（命令输出 / 截图 / 测试结果），没有证据不许说做完了。

三、任务状态机

待办(queued) → 进行中(in-progress) → 等待接续(handoff-wait) → 进行中 … → 已完成(done)
                                        ↘ 受阻(blocked)：写明具体阻塞条件，连续 3 轮未解决才允许标记

四、单写入者边界

• 同一时刻，一个文件只允许一个成员写入；其他人先读后排队。
• 改公共配置（构建脚本、部署配置、依赖清单）前必须先读当前值并声明改动，防止互相覆盖。
• 冲突处理：以交接单里最后一条带时间戳的记录为准。

五、角色分工模板（按能力分派，不是按头衔）

| 角色 | 职责 | 回退条件 |

|---|---|---|

| 总控 | 需求拆解、派发、验收、记忆与交接管理 | — |

| 调度员 | 任务路由、负载均衡、状态监控、超时熔断（优先用脚本/看板等确定性手段，不用 LLM 临场发挥） | 调度延迟高或误派发率上升 |

| 主开发 | 写代码、实现、修复、部署 | 连续失败 2 次切备用通道 |

| 审查员 | 只读评审代码/视觉/安全，不给主线改文件 | — |

| 专项通道 | 处理棘手故障与能力缺口，不与主开发并发改同一文件 | 问题关闭即退出 |

成本优先路由：日常任务走默认主力模型/订阅 → 失败重试一次 → 再失败切备用通道 → 疑难杂症才动用专项通道。不要因为一次小报错就切换主力。

六、记忆同步

• 每个成员的长期记忆各自维护；共享事实只进 MEMORY-SNAPSHOT.md。
• 提供一个同步脚本（示例）：把各成员当日摘要追加合并进快照，保留最近 N 条。
• 教训类内容（踩坑、纠错）优先级最高，必须进快照，防止同一个坑摔两次。

七、最小闭环示例

• 总控接到需求 → 在 CURRENT-TASK.md 写下目标、验收标准、指派主开发，状态=进行中。
• 主开发读完交接单开工 → 完成一个批次 → 回写进度与证据。
• 完成实现 → 总控派审查员只读评审 → 发现问题回写交接单转回主开发。
• 全部验收通过 → 状态=已完成，证据归档，MEMORY-SNAPSHOT.md 记录关键决策。

八、协同调度防翻车指南（八大坑与工程化解法）

> 适用场景：多个 AI 助手并行推进时的典型翻车点。每次组建多 Agent 团队前，逐条对照检查。

| # | 坑 | 症状 | 工程化解法 |

|---|---|---|---|

| 1 | 上下文爆炸 | 共享对话越滚越长，早期任务约束和验收标准被挤出窗口 | 交接单只存结论与状态（≤200行）；过程性讨论留在各自本地；每批次开始由总控重发「最小必要上下文」 |

| 2 | 幻觉传染 | 一个成员输出错误信息，经共享记忆被全员当作事实扩散 | 共享记忆分区：写入需总控标记「已验证」才可见；未验证内容放隔离区并标注来源与置信度 |

| 3 | 协作死锁 | A 等 B 的产出、B 等 C、C 又等 A，系统永久挂起 | 资源/产出申请按全局固定顺序排队；每个等待必须带超时（默认15分钟），超时自动升级总控裁决 |

| 4 | 状态不一致 | 两人手里的任务状态对不上，重复做或漏做 | 唯一事实源=交接单状态机；改状态即写文件；口头/会话内状态不作数 |

| 5 | 通信风暴 | 成员互相直聊，消息链路数随人数平方膨胀，延迟指数涨 | 星型拓扑：只允许「成员↔总控」通信，禁止成员互发；确需协作由总控转交 |

| 6 | Agent 蔓延 | 按功能细分拆出一堆角色，边界重叠、没人负全责 | 减法原则：新角色上线前先回答「能否并入现有角色的完整闭环」；每个角色必须端到端负责一段可交付物 |

| 7 | 调度靠 LLM 临场发挥 | 路由派发交给大模型自由决定，同一输入两次派发结果不同 | 调度确定性化：看板扫描+固定规则（按标签/负载/顺序）派发；LLM 只做需要理解力的规划，不做机械分发 |

| 8 | 无验收聚合 | 各自交付后没人拼装校验，缺陷在集成时才爆 | 总控设独立验收门禁：对照交接单验收标准逐条核验+运行证据；不合格整批退回，不带病合并 |

硬性红线（违反任意一条立即停止协作流程）

• 禁止两个成员同时写同一文件（单写入者边界，见第四节）。
• 禁止跳过交接单直接开工/直接交付。
• 禁止把「我认为完成了」当完成——必须附运行证据。
• 禁止成员间私相授受任务（一切派发过总控）。