handoff-protocol

name	handoff-protocol
description	定义工作流间的交接协议时使用。适用于多工作流协作项目、避免交接质量问题。优先使用"产物 + 上下文 + 验收标准"三要素 + 各工作流的具体交接清单。

工作流交接协议

参考来源：Agent Handoff Patterns、Skywork Best Practices for Handoffs

适用场景

• 多工作流协作项目
• 避免交接质量问题导致返工
• 跨阶段交付（设计→开发→测试→上线）

核心原则

交接是项目失败的高发区。
"reliability lives and dies in the handoffs"
（多 Agent 系统的可靠性，全在交接环节）

每次交接质量决定下游工作流的执行成本。
交接做好了，下游不用猜；做不好，整个项目要返工。

交接三要素

每次工作流交接必须包含：

1. 产物（Artifact）
   - 上游工作流的具体输出文件/文档/代码
   - 格式和位置明确
   - 可以被下游直接使用

2. 上下文（Context）
   - 为什么这样做
   - 做了哪些决策、为什么这样决策
   - 有哪些已知限制或风险
   - 下游需要注意什么

3. 验收标准（Acceptance）
   - 下游如何判断上游产物质量合格
   - 不合格时的退回机制
   - 退回后的修复责任归属

常见交接点和产物清单

产品经理 → 项目经理

□ PRD（含 14 节标准结构）
□ 功能清单 + 优先级
□ 验收标准
□ 风险清单
□ 未决问题

上下文：业务目标、用户场景、非目标范围
验收：项目经理能据此拆出任务列表

项目经理 → API 设计

□ 功能清单（含优先级）
□ 业务实体清单
□ 权限要求
□ 异常场景清单

上下文：哪些接口优先、前端需要什么数据
验收：API 设计师能据此输出 OpenAPI 文档

项目经理 → UI/UX 设计

□ 用户角色和场景
□ 核心流程清单
□ 页面目标
□ 状态说明（loading/error/empty）

上下文：用户旅程关键节点、设计约束
验收：设计师能据此输出页面结构和交互方案

API 设计 → 前端 + 后端

□ OpenAPI 文档
□ Mock 服务地址
□ 错误码表
□ 鉴权方式说明

上下文：哪些字段必填、分页策略、版本兼容
验收：前后端能据此独立开发且联调时字段一致

UI/UX 设计 → 前端

□ 页面清单 + 用户流程
□ 组件清单 + 状态说明
□ 交互规则
□ 响应式规则
□ 可访问性要求

上下文：设计意图、用户场景、品牌约束
验收：前端能据此拆出任务列表，不需要猜测任何状态

后端 → QA

□ 接口代码 + 接口说明
□ 测试账号和数据
□ 异常场景清单
□ 权限矩阵

上下文：核心路径、已知限制
验收：QA 能据此设计测试用例并执行

QA → DevOps

□ 测试报告
□ Bug 修复确认
□ 已知风险清单

上下文：测试覆盖范围、未覆盖场景、环境要求
验收：DevOps 确认可以进入部署流程

DevOps → SRE

□ 部署文档
□ 健康检查端点
□ 监控配置
□ 回滚方案

上下文：部署架构、依赖服务、流量预估
验收：SRE 能据此接管运维

交接质量自检

交接前问自己：
  □ 如果我是下游工作流，拿到这份材料能直接开始工作吗？
  □ 有没有需要猜测的地方？
  □ 有没有遗漏的异常场景？
  □ 验收标准是否可测试？
  □ 未决问题是否标注清楚？

交接失败处理

当下游工作流发现上游产物不可用时：

1. 明确标注问题（缺什么、哪里不对）
2. 退回给上游工作流（状态变为 rework）
3. 项目经理评估影响：
   - 是否影响关键路径
   - 是否需要调整后续计划
   - 是否需要增加缓冲
4. 上游修复后重新交接
5. 记录到 field-journal（避免下次同样问题）

工作流程

1. 识别项目中的所有交接点
   ↓
2. 对每个交接点：
   a. 列产物清单（来自上游）
   b. 列上下文要点（决策背景）
   c. 定义验收标准（下游怎么判断合格）
   ↓
3. 输出交接计划
   ↓
4. 项目执行中，每个交接发生时验证三要素
   ↓
5. 交接失败 → 走失败处理流程

输出格式

## 交接计划

### 交接点 1: 产品经理 → API 设计

**产物**：
- PRD v1.2（docs/prd-v1.2.md）
- 业务实体清单（docs/entities.md）
- 权限矩阵（docs/permissions.md）

**上下文**：
- 优先支持订单和支付，暂不支持退款
- 多租户隔离要求（每个商家独立）
- 审计日志要求

**验收标准**：
- API 设计师能据此输出至少 8 个核心端点
- 不需要再向产品经理询问
- 未决问题清单 ≤ 3 条

### 交接点 2: API 设计 → 前端 + 后端
...

常见坑

1. 只传文件不传上下文——下游不知道为什么这样做
2. 没有验收标准——下游拿到垃圾输入只能硬做
3. 交接清单不完整——漏了关键产物
4. 退回机制不明确——发现问题不知道找谁
5. 上下文写成废话——"按 PRD 实现"等于没说
6. 未决问题不标注——下游开始做才发现没法做
7. 交接是单向的——没有让下游确认理解

配套模板

• templates/handoff-plan-template.md — 单次交接 + 完整项目交接计划 + 交接质量自检清单

与其他 skill 的协作

上游：
  wbs-decomposition → 提供任务和工作流分配
  orchestration → 提供编排模式

下游：
  progress-tracking → 追踪交接状态
  change-control → 变更时通知所有交接相关方