SuperAPI AI Directory

handoff-protocol

General & other

View repository

Updated 10-16 09:30

About this skill

Workflow Handoff Protocol

Reference sources:Agent Handoff Patterns、Skywork Best Practices for Handoffs

Applicable scenarios

  • Multi-workflow collaboration projects
  • Avoid rework caused by handoff quality issues
  • Cross-phase delivery (design→development→testing→launch)

Core principles

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

The quality of each handoff determines the execution cost of the downstream workflow. If the handoff is done well, downstream does not have to guess; if done poorly, the entire project will need rework.


## 交接三要素

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

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

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

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

Common handoff points and artifact checklists

Product Manager → Project Manager

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

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

Project Manager → API Design

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

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

Project Manager → UI/UX Design

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

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

API Design → Frontend + Backend

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

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

UI/UX Design → Frontend

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

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

Backend → QA

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

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

QA → DevOps

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

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

DevOps → SRE

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

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

Handoff quality self-check

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

Handoff failure handling

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

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

Workflow

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

Output format

## 交接计划

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

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

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

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

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

Common pitfalls

  1. Passing only files without context——downstream does not know why it was done this way
  2. No acceptance criteria——downstream can only force it through with garbage input
  3. Incomplete handoff checklist——missing key artifacts
  4. Unclear return mechanism——when a problem is found, no one knows who to go to
  5. Context written as useless filler——"implement according to the PRD" is as good as saying nothing
  6. Unresolved issues not marked——downstream only discovers it cannot be done after starting
  7. Handoff is one-way——downstream is not asked to confirm understanding

Supporting templates

  • templates/handoff-plan-template.md — single handoff + complete project handoff plan + handoff quality self-check checklist

Collaboration with other skills

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

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