---
title: "Workflow Tree Spec"
type: concept
tags: [workflow, specification, documentation, quality-assurance]
last_updated: 2026-04-25
---

## Definition
工作流树规范格式——为每个工作流生成的结构化规范文档，工程师可直接依据实现，QA 可直接导出测试用例，运维可理解系统行为，产品负责人可验证需求是否满足。

## Required Sections（必须章节）

1. **Overview**：2-3 句话描述工作流目标、触发者和产出
2. **Actors**：参与此工作流的所有角色（人/系统/Agent）
3. **Prerequisites**：工作流启动前必须满足的条件
4. **Trigger**：触发来源（用户操作/API调用/定时任务/事件）
5. **Workflow Tree**：每步的 Actor/Action/Timeout/Input/Output on SUCCESS/Output on FAILURE + Observable States
6. **ABORT_CLEANUP**：失败清理流程（含触发条件、清理动作顺序、客户视图、运维视图）
7. **State Transitions**：状态机转换图
8. **Handoff Contracts**：每个系统边界的交接合同
9. **Cleanup Inventory**：工作流创建的所有资源及其销毁方法
10. **Reality Checker Findings**：规范与代码对照验证结果
11. **Test Cases**：每个分支对应一个测试用例
12. **Assumptions**：所有未经代码验证的假设
13. **Open Questions**：待确认事项

## Branch Coverage（分支覆盖要求）
每个工作流规范必须覆盖 **7 类分支**：
1. 快乐路径（所有步骤成功，所有输入有效）
2. 输入验证失败（具体错误信息 + 客户看到什么）
3. 超时失败（每个步骤的超时值 + 超时后行为）
4. 瞬态失败（网络抖动/限流，可重试并退避）
5. 永久失败（无效输入/配额超限，立即失败并清理）
6. 部分失败（步骤7/12失败，已创建资源必须销毁）
7. 并发冲突（同一资源同时被创建/修改）

## Status Lifecycle
```
Draft → Review → Approved
           ↑
    Reality Checker 验证（必须，不可跳过）
```

## Source
- [[specialized-workflow-architect]]（Workflow Architect Agent）