整体设计与落地规范
设计的交付物是可解释、可实施、可验证的行为方案。类图、模式名称、状态枚举和代码量只是实现表达,不能替代方案成立的理由。
本规范约束 Agent 如何做设计,不预设串行化、乐观并发、事务、预留、事件驱动等技术路线。分析深度与改动风险相称,不要求每次输出完整长文档。
与类实现规范的分工
本 skill 与 evidence-first-implementation 组成一套开发规范,保留两个入口,按问题的决策范围使用:
| 问题 | 主要负责的规范 | 交付要求 |
|---|---|---|
| 谁做决策、谁拥有状态、谁协调多个组件,失败后整个流程如何推进 | 本 skill | 行为契约、责任边界及落地顺序 |
| 一个类如何维护约束,字段和方法如何表达职责,如何实现和验证 | evidence-first-implementation | 符合契约的代码、局部清理和验证证据 |
| 已授权的复杂功能或框架改造 | 两者衔接使用 | 完成纵向业务路径、调用迁移和集成验收,不停在方案或类骨架 |
已有明确方案时复用,不重新做一轮架构讨论。局部缺陷、单类调整直接使用类实现规范;只有涉及策略语义、跨组件所有权、公共协议或系统性能约束的变化,才回到本层补充受影响的设计。文件数量不是判断依据。只要求设计或评审时,不擅自实施。
两层共用一份行为契约,内容可以来自对话、代码和已有文档,无需另建文件或重复填表:
- 行为:触发条件、可观察的成功结果、不得破坏的约束和策略取舍。
- 边界:各组件负责什么;数据粒度、事实来源、修改者、可见时点和清理责任。
- 失败:局部失败向上报告什么;谁决定等待、替代、重试或终止;部分成功和未知结果如何处理。
- 成本:热路径、允许的重算与同步范围、已有性能门槛和待测假设。
- 迁移与验收:具体改动位置、保留和删除项、实施依赖、需要证明的行为及测试环境。
本层定义这些约束,类实现层核对并落实。实现证据推翻某条假设时,只回到相关边界修正契约及其依赖,不重新讨论全部方案,也不把每个局部实现选择变成用户审批。
1. 先建立问题模型,不替现有实现辩护
提出方案前,明确:用户要改善的可观察行为、不能破坏的业务约束、当前问题的证据、尚未确认的假设。
严格区分:
- 目标:为什么要改,例如降低重复计算、尾延迟或理解成本。
- 约束:无论采用什么实现都必须成立的行为。
- 策略:在多个可行行为中如何取舍,例如优先性能、亲和性或公平性。
- 机制:为上述语义服务的锁、版本、队列、状态机等手段。
阅读相关代码和实际策略,不把现状当成约束,不把常见架构当成答案。不得为了实现方便,悄悄改变等待、降级、失败或优先级的业务含义。
2. 先定义行为,再决定抽象
先走通业务流程,再划分模块、类和接口。对影响设计的阶段,明确输入、输出、状态变化、可见时点、失败动作和执行责任。
涉及资源或副作用时,必须解释“成功”意味着什么:仅计算完成、本地登记成功、对外发布、远端确认,还是实际执行完成。结果未知不能按未发生处理。
对每份重要状态,能够回答:
- 表达什么事实,粒度是请求、尝试、节点还是一次操作?
- 谁创建和修改,谁读取,何时失效或清理?
- 是事实来源、派生统计、预测值还是协议承诺?
- 与其他状态重叠时,如何避免重复计算或相互矛盾?
不能仅因字段相似就合并,也不能仅因阶段不同就拆成多个持久结果对象。只有职责、生命周期或约束提供了依据,才建立新的边界。
3. 每个跨阶段操作都要有协调责任
多步骤方案不能以“各组件配合”结束说明。明确:谁推进流程,谁管理局部资源,谁处理部分成功,责任在什么条件下交接。
局部问题应在具备信息和权限的最小范围内解决;只有改变上层决策的结果才向上传递。内部原因可以保留在诊断中,不必都暴露成上层状态。
若操作可能重试,明确重试范围、停止条件、旧状态处理和重复执行后果。清理失败不能伪装成普通可重试失败。幂等保护不能替代清晰的清理责任。
策略决定“做什么、为何等待或退让”;机制报告事实并保证操作;协调者推进跨步骤生命周期。这些是职责,不要求机械地新建三个类。
4. 正常流程与失败决策一起设计
在宣布方案成立前,用最能区分方案的失败路径检验它,不等实现后再逐个补状态。
针对相关边界写清:触发条件、当前已有副作用、立即处理、后续等待或重试、最终结束方式。避免含糊的“失败就重试”“资源不足就等待”“超时就释放”。
特别审查:
- 局部失败是否真的意味着整体不可行?
- 当前最优方案不可执行时,是否允许退到次优,还是必须等待?
- 等待的是特定对象、允许的对象集合,还是某种条件?由什么事件唤醒?
- 撤回、取消、超时是否代表实际副作用已经消失?
- 重放的是同一业务请求还是旧的执行尝试?
这些答案来自业务策略和协议,不由错误处理代码自行发明。
5. 用具体反例检验,而不是列机制名称
对并发、异步或分布式设计,选择必要的事件交错进行推演。例如两个执行者读到旧状态、操作只完成一半、资源释放与登记等待交错、旧回调晚于新尝试、配置或节点身份变化。
对于每个关键保证,指出成立的边界:谁能同时修改数据,检查与修改是否原子,何时对其他决策可见,保证只在进程内还是跨越远端。
不要将不同性质混同:无死锁不代表没有阻塞传播;不超额不代表没有流量集中;有版本不代表全局最优;有重试不代表最终能推进;接口返回成功不代表远端完成。
区分逻辑上能够证明的保证与需要运行测量的假设。
6. 性能和稳定性必须进入设计,而不是事后承诺
说明主要成本发生在哪里:扫描、计算、分配、锁持有、网络等待、重试与通知。高频路径上的新增机制要说明成本和收益,不能用“操作很短”代替验证。
局部变化优先触发局部更新。先检查依赖范围,再决定重算范围;重新比较缓存结果与重新执行全部昂贵计算是两回事。全局依赖变化时,不强行坚持局部刷新。
对会放大工作量的机制,审查热点竞争、重试循环、惊群、频繁迁移和饥饿。串行化与并行化都需要说明适用条件,不将任一方案默认视为更好。
期限、阈值、回退和绑定规则应来自策略或测量。缺少依据时明确待验证,不临时新增一个常量掩盖设计矛盾。
7. 比较取舍,保持判断,不迎合式改方案
存在实质性争议时,比较少数可行方案,说明各自适用前提、改变的行为、失败后果、性能代价和复杂度来源。说明推荐理由,以及什么新证据会使推荐改变。
收到用户反例后,必须判断它推翻了哪条假设;保留仍成立的约束,撤回失效结论及其衍生机制。不要每次先说“对”,再叠加一层补丁,也不要在两个极端方案间反复切换。
不得把用户对一个局部想法的认可扩大成对整个方案的授权。也不要让用户反复确认已经明确的内容。先从代码和上下文解决信息缺口,只询问会改变设计的未决业务语义。
8. 复杂度优化必须同时包含删除
评价复杂度时,看独立状态、交接次数、调用方需要掌握的隐含约束、失败恢复路径,以及一次局部修改牵涉的范围。不能仅用类数、字段数或行数衡量。
每引入一个新状态或抽象,说明其不可替代的信息或职责。每替换一个机制,列出失去意义的旧入口、重复登记、外层重试、兼容包装和分散清理。
单一事实来源可以有派生视图和性能缓存,但必须明确更新、失效与校验规则。不要为了“只存一份”删除有价值的快照,也不要让缓存再拥有一套独立业务生命周期。
9. 形成可实施的方案,而不是讨论纪要
根据任务规模,最终方案应提供足够的信息:
- 已确认的目标、不变量、策略语义,以及仍未证实的假设。
- 正常流程、关键失败分支、状态可见性和责任交接。
- 具体模块、类和接口的修改;影响的调用方、模式及协议。
- 删除清单、迁移顺序;确需过渡兼容时说明退出条件。
- 验证行为和性能主张的方法、验收依据及风险。
若关键业务含义或清理责任尚不明确,不得称为“最终可实施方案”;可以先开展不依赖未决问题的验证工作。这是设计完整性要求,不是新增审批流程。
用户已授权实施时,直接推进范围内的工作。实现偏离已确认语义时明确说明原因,不能用实现困难静默替换策略。
实施时按依赖顺序推进能够验证的纵向路径:先建立必要契约,再贯通真实入口、责任组件和完成或失败出口,随后迁移其他调用方与运行模式。每一步调用类实现规范完成具体代码与验证;不要先铺满抽象、类骨架和空接口,再等待最后联调。
本层持续负责整体闭环:局部类通过测试后,仍需核对组件间交接、正常和失败流程、兼容路径退出,以及跨模块性能主张。局部实现发现的问题按上述边界升级,不能交给各个类自行发明不一致的补救策略。
10. 以证据验收,防止补丁累积
测试应验证可观察行为和关键不变量,特别是能推翻设计的边界。现有测试通过不能证明旧设计合理;新测试通过也不能替代对真实运行路径的验证。
保留仍有效的断言,不为让结果通过而放宽指标。明确基线、实测范围、替代依赖和失败项,不把局部成功扩大为整体正确或没有性能回退。
最终检查整个改动是否形成一条清楚的主流程:新旧路径是否重复,状态是否还需多处拼接,原先失去依据的机制是否真正删除。若每次修复都新增状态、特例或回调,回到问题模型重新检查,而不是继续堆叠。
使用案例
需要具体反例时阅读 FlexLB 讨论案例。案例用于说明上述规范,不将其中的调度、预留或失败处理选择推广为所有系统的固定方案。