# Handoff Protocol

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

- Skill: `zhaoxuya520/handoff-protocol` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhaoxuya520/handoff-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaoxuya520/handoff-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaoxuya520 (https://skillmd.com/u/zhaoxuya520)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhaoxuya520/handoff-protocol

---


# 工作流交接协议

参考来源：[Agent Handoff Patterns](https://www.augmentcode.com/guides/agent-handoff-patterns-human-agent-interface)、[Skywork Best Practices for Handoffs](https://skywork.ai/blog/ai-agent-orchestration-best-practices-handoffs/)

## 适用场景

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

## 核心原则

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

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

## 交接三要素

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

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

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

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

## 常见交接点和产物清单

### 产品经理 → 项目经理

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

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

### 项目经理 → API 设计

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

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

### 项目经理 → UI/UX 设计

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

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

### API 设计 → 前端 + 后端

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

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

### UI/UX 设计 → 前端

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

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

### 后端 → QA

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

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

### QA → DevOps

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

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

### DevOps → SRE

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

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

## 交接质量自检

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

## 交接失败处理

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

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

## 工作流程

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

## 输出格式

```markdown
## 交接计划

### 交接点 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 的协作

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

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