# Workflow First Design

> 复杂功能、框架和跨模块重构的整体设计与落地规范。用于确定业务流程、模块职责、跨组件状态与资源协议、失败协调、并发性能取舍、迁移清理和集成验收；与 evidence-first-implementation 配合落实具体类和方法。局部实现问题不强制升级为架构设计。

- Skill: `alibaba/workflow-first-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add alibaba/workflow-first-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alibaba/workflow-first-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: alibaba (https://skillmd.com/u/alibaba)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/alibaba/workflow-first-design

---


# 整体设计与落地规范

设计的交付物是可解释、可实施、可验证的行为方案。类图、模式名称、状态枚举和代码量只是实现表达，不能替代方案成立的理由。

本规范约束 Agent 如何做设计，不预设串行化、乐观并发、事务、预留、事件驱动等技术路线。分析深度与改动风险相称，不要求每次输出完整长文档。

## 与类实现规范的分工

本 skill 与 [evidence-first-implementation](../evidence-first-implementation/SKILL.md) 组成一套开发规范，保留两个入口，按问题的决策范围使用：

| 问题                                                         | 主要负责的规范                | 交付要求                                                 |
| ------------------------------------------------------------ | ----------------------------- | -------------------------------------------------------- |
| 谁做决策、谁拥有状态、谁协调多个组件，失败后整个流程如何推进 | 本 skill                      | 行为契约、责任边界及落地顺序                             |
| 一个类如何维护约束，字段和方法如何表达职责，如何实现和验证   | evidence-first-implementation | 符合契约的代码、局部清理和验证证据                       |
| 已授权的复杂功能或框架改造                                   | 两者衔接使用                  | 完成纵向业务路径、调用迁移和集成验收，不停在方案或类骨架 |

已有明确方案时复用，不重新做一轮架构讨论。局部缺陷、单类调整直接使用类实现规范；只有涉及策略语义、跨组件所有权、公共协议或系统性能约束的变化，才回到本层补充受影响的设计。文件数量不是判断依据。只要求设计或评审时，不擅自实施。

两层共用一份行为契约，内容可以来自对话、代码和已有文档，无需另建文件或重复填表：

- **行为**：触发条件、可观察的成功结果、不得破坏的约束和策略取舍。
- **边界**：各组件负责什么；数据粒度、事实来源、修改者、可见时点和清理责任。
- **失败**：局部失败向上报告什么；谁决定等待、替代、重试或终止；部分成功和未知结果如何处理。
- **成本**：热路径、允许的重算与同步范围、已有性能门槛和待测假设。
- **迁移与验收**：具体改动位置、保留和删除项、实施依赖、需要证明的行为及测试环境。

本层定义这些约束，类实现层核对并落实。实现证据推翻某条假设时，只回到相关边界修正契约及其依赖，不重新讨论全部方案，也不把每个局部实现选择变成用户审批。

## 1. 先建立问题模型，不替现有实现辩护

提出方案前，明确：用户要改善的可观察行为、不能破坏的业务约束、当前问题的证据、尚未确认的假设。

严格区分：

- **目标**：为什么要改，例如降低重复计算、尾延迟或理解成本。
- **约束**：无论采用什么实现都必须成立的行为。
- **策略**：在多个可行行为中如何取舍，例如优先性能、亲和性或公平性。
- **机制**：为上述语义服务的锁、版本、队列、状态机等手段。

阅读相关代码和实际策略，不把现状当成约束，不把常见架构当成答案。不得为了实现方便，悄悄改变等待、降级、失败或优先级的业务含义。

## 2. 先定义行为，再决定抽象

先走通业务流程，再划分模块、类和接口。对影响设计的阶段，明确输入、输出、状态变化、可见时点、失败动作和执行责任。

涉及资源或副作用时，必须解释“成功”意味着什么：仅计算完成、本地登记成功、对外发布、远端确认，还是实际执行完成。结果未知不能按未发生处理。

对每份重要状态，能够回答：

- 表达什么事实，粒度是请求、尝试、节点还是一次操作？
- 谁创建和修改，谁读取，何时失效或清理？
- 是事实来源、派生统计、预测值还是协议承诺？
- 与其他状态重叠时，如何避免重复计算或相互矛盾？

不能仅因字段相似就合并，也不能仅因阶段不同就拆成多个持久结果对象。只有职责、生命周期或约束提供了依据，才建立新的边界。

## 3. 每个跨阶段操作都要有协调责任

多步骤方案不能以“各组件配合”结束说明。明确：谁推进流程，谁管理局部资源，谁处理部分成功，责任在什么条件下交接。

局部问题应在具备信息和权限的最小范围内解决；只有改变上层决策的结果才向上传递。内部原因可以保留在诊断中，不必都暴露成上层状态。

若操作可能重试，明确重试范围、停止条件、旧状态处理和重复执行后果。清理失败不能伪装成普通可重试失败。幂等保护不能替代清晰的清理责任。

策略决定“做什么、为何等待或退让”；机制报告事实并保证操作；协调者推进跨步骤生命周期。这些是职责，不要求机械地新建三个类。

## 4. 正常流程与失败决策一起设计

在宣布方案成立前，用最能区分方案的失败路径检验它，不等实现后再逐个补状态。

针对相关边界写清：触发条件、当前已有副作用、立即处理、后续等待或重试、最终结束方式。避免含糊的“失败就重试”“资源不足就等待”“超时就释放”。

特别审查：

- 局部失败是否真的意味着整体不可行？
- 当前最优方案不可执行时，是否允许退到次优，还是必须等待？
- 等待的是特定对象、允许的对象集合，还是某种条件？由什么事件唤醒？
- 撤回、取消、超时是否代表实际副作用已经消失？
- 重放的是同一业务请求还是旧的执行尝试？

这些答案来自业务策略和协议，不由错误处理代码自行发明。

## 5. 用具体反例检验，而不是列机制名称

对并发、异步或分布式设计，选择必要的事件交错进行推演。例如两个执行者读到旧状态、操作只完成一半、资源释放与登记等待交错、旧回调晚于新尝试、配置或节点身份变化。

对于每个关键保证，指出成立的边界：谁能同时修改数据，检查与修改是否原子，何时对其他决策可见，保证只在进程内还是跨越远端。

不要将不同性质混同：无死锁不代表没有阻塞传播；不超额不代表没有流量集中；有版本不代表全局最优；有重试不代表最终能推进；接口返回成功不代表远端完成。

区分逻辑上能够证明的保证与需要运行测量的假设。

## 6. 性能和稳定性必须进入设计，而不是事后承诺

说明主要成本发生在哪里：扫描、计算、分配、锁持有、网络等待、重试与通知。高频路径上的新增机制要说明成本和收益，不能用“操作很短”代替验证。

局部变化优先触发局部更新。先检查依赖范围，再决定重算范围；重新比较缓存结果与重新执行全部昂贵计算是两回事。全局依赖变化时，不强行坚持局部刷新。

对会放大工作量的机制，审查热点竞争、重试循环、惊群、频繁迁移和饥饿。串行化与并行化都需要说明适用条件，不将任一方案默认视为更好。

期限、阈值、回退和绑定规则应来自策略或测量。缺少依据时明确待验证，不临时新增一个常量掩盖设计矛盾。

## 7. 比较取舍，保持判断，不迎合式改方案

存在实质性争议时，比较少数可行方案，说明各自适用前提、改变的行为、失败后果、性能代价和复杂度来源。说明推荐理由，以及什么新证据会使推荐改变。

收到用户反例后，必须判断它推翻了哪条假设；保留仍成立的约束，撤回失效结论及其衍生机制。不要每次先说“对”，再叠加一层补丁，也不要在两个极端方案间反复切换。

不得把用户对一个局部想法的认可扩大成对整个方案的授权。也不要让用户反复确认已经明确的内容。先从代码和上下文解决信息缺口，只询问会改变设计的未决业务语义。

## 8. 复杂度优化必须同时包含删除

评价复杂度时，看独立状态、交接次数、调用方需要掌握的隐含约束、失败恢复路径，以及一次局部修改牵涉的范围。不能仅用类数、字段数或行数衡量。

每引入一个新状态或抽象，说明其不可替代的信息或职责。每替换一个机制，列出失去意义的旧入口、重复登记、外层重试、兼容包装和分散清理。

单一事实来源可以有派生视图和性能缓存，但必须明确更新、失效与校验规则。不要为了“只存一份”删除有价值的快照，也不要让缓存再拥有一套独立业务生命周期。

## 9. 形成可实施的方案，而不是讨论纪要

根据任务规模，最终方案应提供足够的信息：

- 已确认的目标、不变量、策略语义，以及仍未证实的假设。
- 正常流程、关键失败分支、状态可见性和责任交接。
- 具体模块、类和接口的修改；影响的调用方、模式及协议。
- 删除清单、迁移顺序；确需过渡兼容时说明退出条件。
- 验证行为和性能主张的方法、验收依据及风险。

若关键业务含义或清理责任尚不明确，不得称为“最终可实施方案”；可以先开展不依赖未决问题的验证工作。这是设计完整性要求，不是新增审批流程。

用户已授权实施时，直接推进范围内的工作。实现偏离已确认语义时明确说明原因，不能用实现困难静默替换策略。

实施时按依赖顺序推进能够验证的纵向路径：先建立必要契约，再贯通真实入口、责任组件和完成或失败出口，随后迁移其他调用方与运行模式。每一步调用类实现规范完成具体代码与验证；不要先铺满抽象、类骨架和空接口，再等待最后联调。

本层持续负责整体闭环：局部类通过测试后，仍需核对组件间交接、正常和失败流程、兼容路径退出，以及跨模块性能主张。局部实现发现的问题按上述边界升级，不能交给各个类自行发明不一致的补救策略。

## 10. 以证据验收，防止补丁累积

测试应验证可观察行为和关键不变量，特别是能推翻设计的边界。现有测试通过不能证明旧设计合理；新测试通过也不能替代对真实运行路径的验证。

保留仍有效的断言，不为让结果通过而放宽指标。明确基线、实测范围、替代依赖和失败项，不把局部成功扩大为整体正确或没有性能回退。

最终检查整个改动是否形成一条清楚的主流程：新旧路径是否重复，状态是否还需多处拼接，原先失去依据的机制是否真正删除。若每次修复都新增状态、特例或回调，回到问题模型重新检查，而不是继续堆叠。

## 使用案例

需要具体反例时阅读 [FlexLB 讨论案例](references/flexlb-lessons.md)。案例用于说明上述规范，不将其中的调度、预留或失败处理选择推广为所有系统的固定方案。

