---
name: workflow-designer
description: 把重复发生的团队操作、审批循环、发布检查或内容流程整理成可实施的工作流规格，明确触发、输入、状态、动作、检查点和责任人。
disable-model-invocation: true
---

# 工作流设计

为重复发生的流程编写可实施契约。一次性任务直接执行或进入 `/to-spec`；只有同一类工作会反复发生，并且需要稳定的触发与状态流转时，才设计工作流。

## 原则

- 先描述现有流程和真实约束，再设计自动化。
- 确定性转换优先使用脚本或规则；只有需要判断的环节才使用 agent。
- 人工检查点尽量靠后，并一次提供可作决定的摘要、差异和链接。
- 工作流规格记录稳定契约；持续变化的观察与操作笔记放在单独文档中。
- 不因为“可能有用”而增加定时器、agent、审批或持久状态。

## 过程

### 1. 建立现状图

读取已有 SOP、脚本、CI、issue 模板和自动化配置。向用户确认仍缺少的事实：流程由什么事件或时间触发，谁提供输入，当前由谁执行，结果交给谁，以及失败时谁负责处理。

**完成条件：** 能从一次真实触发开始，沿当前路径走到交付或失败，没有未知的参与者或系统。

### 2. 定义执行契约

逐项确定：

- **触发**：事件、时间、人工启动，以及漏触发后的补偿方式
- **输入**：来源、格式、必填字段、权限和新鲜度
- **状态**：需要持久化什么，幂等键是什么，如何安全重试
- **动作**：确定性步骤与需要判断的步骤
- **检查点**：谁决定什么，看到哪些摘要、差异和证据
- **输出**：产物、目标位置、完成信号和通知对象
- **失败**：可重试错误、终止条件、回滚或补偿、升级责任人
- **可观测性**：如何知道没有运行、卡住、重复运行或产生错误结果

检查点只保留真正需要人的决策。原始日志先整理成决策摘要，再交给人。

**完成条件：** 每个状态都有进入条件、退出条件和责任人；重试不会重复产生外部副作用。

### 3. 写入规格

默认保存到 `workflows/<名称>.md`；仓库已有约定时沿用。文档至少包含：目标与非目标、触发、输入、状态模型、步骤、人工检查点、输出、失败处理、权限边界、可观测性和验收场景。

把仍会变化的服务名称、联系人习惯和探索笔记放在相邻的 `NOTES.md` 或仓库已有的运行手册中，并从规格链接过去。

写完后用三个场景走查：正常完成、可重试失败、产生外部副作用后的部分失败。

**完成条件：** 实现者仅凭规格和所链接的一手资料，就能进入 `/to-spec` 或直接创建实现任务，无需重新询问工作流边界。