cybernetic-systems-engineering

name	cybernetic-systems-engineering
description	用“系统工程 + 工程控制论 + 总体设计（GDA）”的方法做软件工程闭环控制。 适用：真实代码库中的 bugfix、feature、refactor、性能、迁移、事故复盘、测试设计、架构审计、门禁验证。 尤其适合：问题复杂、跨模块、需要最小可验证变更、需要离线/在线双层验证、需要防止“测试全绿但真实环境失败”的任务。 不适用：纯知识问答、翻译、创作、一次性聊天建议、无需验证的单句结论。

Cybernetic Systems Engineering（CSE）

把软件开发当作一个闭环控制系统来做：

• 被控对象（Plant）：代码库 + 运行时环境 + 依赖 + 数据 + 测试系统
• 控制器（Controller）：你（Agent）+ 你的计划、策略、节奏控制
• 传感器（Sensors）：测试、构建日志、运行日志、指标、复现脚本、审计文档
• 执行器（Actuators）：代码修改、配置变更、依赖升级、回滚、文档更新、测试补强
• 参考输入（Reference）：需求、issue、验收标准、SLO/SLA、业务边界
• 输出（Output）：实际行为（通过/失败测试、运行结果、性能数据、门禁结果）
• 误差（Error）：参考输入与输出之间的差距
• 扰动（Disturbance）：环境差异、并发、flake、脏状态、真实 schema 漂移
• 时滞（Delay）：慢测试、CI 排队、真实环境依赖、发布窗口

本 skill 的目标不是“让你会用控制论术语”，而是让你在复杂工程任务中：

1. 先建立正确的观测与误差定义
2. 再用最小控制输入减少误差
3. 用分层验证防止振荡与假收敛
4. 用总体设计视角控制复杂性

项目级控制拓扑

CSE 不只处理“当前这一条任务怎么修”，还要先回答“这个项目由谁控制、在哪一层控制、跨模块如何协调”。

从控制层级看，CSE 默认同时存在两套闭环：

• 任务级闭环
  • 面向单个 issue、单次 patch、单轮验证
  • 关注最小控制输入、最小 failing case、分层验证
• 项目级控制拓扑
  • 面向多模块、多团队、多阶段演化
  • 关注总体设计部、控制结构、跨模块协调、边界冻结与升级路径

如果只建立任务级闭环，而没有项目级控制拓扑，常见结果是：

• 单个 patch 看起来正确，但把复杂性偷偷转移到别的模块
• 局部验证通过，但共享接口、共享状态或共享基础设施被无意破坏
• 每个人都在改“自己眼前那一层”，但没有人对整体误差负责

因此在以下场景，必须先补项目级控制拓扑，再进入具体修复：

• 改动跨 2 个及以上模块、服务或语言边界
• 需要同时改代码、配置、schema、运行流程中的两类以上对象
• 任务会影响共享接口、共享状态、共享基础设施或统一门禁

项目级控制拓扑至少要回答四个问题：

1. 总体设计部在哪里
   • 谁负责维护项目级参考输入、关键边界和最终裁决
2. 控制结构是什么
   • 本次问题主要落在哪些层，哪些层只能观测，哪些层允许施加控制输入
3. 跨模块协调怎么发生
   • 哪些模块存在强耦合，改动会沿什么路径外溢，谁需要被显式通知或升级
4. 哪些边界先冻结
   • 哪些接口、schema、门禁口径在本轮不能被顺手改写

控制面 / 数据面 / 状态面

为了避免“看起来只是改一行代码，实际上改穿了整个系统”，复杂任务开始前必须先识别本次改动主要落在哪一面：

• 控制面
  • 负责决定系统如何调节自己
  • 典型对象：限流、重试、熔断、路由、灰度、回滚、门禁、调度策略
• 数据面
  • 负责承载真实业务流量和核心处理路径
  • 典型对象：请求处理、任务执行、核心计算、主链调用、用户可见结果
• 状态面
  • 负责保存共享事实、恢复锚点与跨节点一致性
  • 典型对象：数据库、schema、缓存、队列、事件日志、检查点、幂等键

默认要求：

1. 先标出本次改动的主落点在哪一面
2. 再标出会被连带影响的次级面
3. 如果一次改动同时触碰两面以上，必须显式写出复杂性是如何转移的

一个典型例子：

• 把重试、限流从业务代码下沉到 mesh 或统一网关
  • 不是“复杂性消失了”
  • 而是复杂性从数据面转移到了控制面
• 把会话、任务进度或幂等信息从应用内存迁到 Redis / 数据库
  • 不是“状态更简单了”
  • 而是状态复杂性从节点内部转移到了状态面

如果主落点都判断不清，默认先不要改实现，而是先补控制结构说明。

复杂性转移账本

复杂性不会凭空消失，只会被下沉、上浮或转移到别处。

因此每次声称“系统更简单了”时，都应至少记一条复杂性转移账本：

字段	说明
复杂性原位置	复杂性原来压在哪一层、哪个模块、哪条链路
新位置	复杂性被转移到了哪里
收益	本次转移换来了什么
新成本	新增了什么依赖、运维成本或观测成本
失效模式	转移后最可能新增什么故障模式

典型例子：

• 把重试、限流、路由从应用代码下沉到 mesh
  • 复杂性原位置：数据面应用逻辑
  • 新位置：控制面基础设施
  • 收益：业务代码更薄、统一治理更强
  • 新成本：调试链变长、配置漂移风险上升
  • 失效模式：控制面误配导致全局放大
• 把会话、幂等键或任务恢复点外包到 Redis / 数据库
  • 复杂性原位置：节点内内存与本地状态
  • 新位置：状态面共享存储
  • 收益：重启恢复更稳定、横向扩展更容易
  • 新成本：一致性、超时、容量与运维复杂度上升
  • 失效模式：状态面抖动放大为全局故障
• 把同步调用改成异步补偿
  • 复杂性原位置：同步链路上的时延与阻塞
  • 新位置：队列、重试、补偿和对账流程
  • 收益：主链解耦、峰值承压更强
  • 新成本：最终一致性与对账成本上升
  • 失效模式：补偿堆积、重复消费、长尾未收敛

项目级控制拓扑的默认治理协议如下：

最小 owner matrix

角色	默认职责	有权决定什么	无权单独决定什么
总体设计部	维护项目级参考输入、关键边界、升级路径与最终裁决	跨模块优先级、冻结边界、变更窗口、最终 gate 口径	直接跳过模块 owner 的局部约束与证据
模块 owner	维护本模块不变量、主链入口与回归边界	模块内部实现、局部回归、局部重构	擅自改共享接口、共享状态、共享门禁
共享边界 owner	维护共享 API、schema、队列、缓存、统一门禁等共享事实源	共享契约演化节奏、兼容窗口、迁移前置条件	在未通知受影响模块时直接改共享契约

默认升级路径

按风险从低到高，默认这样升级：

1. 模块内局部改动
   • 模块 owner 可在本模块边界内完成分析、修改与验证
2. 跨模块但不改共享契约
   • 必须显式通知受影响模块 owner，并记录外溢路径
3. 触碰共享接口、共享状态、统一门禁
   • 必须升级到总体设计部裁决，再进入实现
4. 触碰冻结边界或发布窗口
   • 默认停止当前 patch，先拿到明确批准

接口冻结条件

以下任一对象在本轮默认视为冻结边界，不能顺手改写：

• 共享 API 输入输出结构
• 数据库 schema 与持久化字段语义
• 队列、缓存、事件格式等共享状态契约
• 统一门禁口径、核心指标口径、发布与回滚流程

要解冻这些边界，至少要同时满足：

1. 有明确变更理由，而不是“顺便改一下更优雅”
2. 有受影响模块清单与兼容路径
3. 有总体设计部或对应共享边界 owner 的显式裁决

跨模块裁决规则

凡是跨模块变更，最终裁决责任默认不属于“谁先改代码”，而属于总体设计部。

它至少要回答：

• 为什么这次改动值得跨模块扩散
• 哪些模块只需要被通知，哪些模块需要同步修改
• 哪些边界继续冻结，哪些边界被批准打开
• 如果跨模块协调失败，当前 patch 应该收缩到哪里

如果这些问题答不出来，默认结论不是“继续改”，而是：

• 先补控制拓扑
• 先画清边界
• 先确认谁对整体误差负责

后续章节中的 Control Contract、GDA 四步法、传感器工程与验证分层，都是建立在这层项目级控制拓扑之上执行的。

0. 何时触发

以下任一场景，优先使用本 skill：

• 需要修改代码并验证结果
• 任务跨多个模块/服务/语言边界
• 需要从 bugfix 推进到测试补强、门禁、handoff
• 用户要求做“严格 review”“系统性复盘”“架构与测试一起收口”
• 出现“离线通过，真实环境失败”“测试通过，业务不闭环”“修一个坏两个”的迹象

如果任务时间跨度长、步骤多、存在中断恢复需求，应同时配合 harness 使用。

1. 五维心智模型（执行时要内化）

执行任务时必须同时考虑以下五个维度：

1. 第一性原理

   • 找系统不变量、硬约束、物理边界
   • 不先问“用什么框架”，先问“系统真正不能妥协的是什么”

2. 公理化思维

   • 契约先于实现
   • 明确哪些接口、状态转换、schema、事件语义是不可破坏的公理

3. 多模型思维

   • 至少用 3 个视角看问题：
     • 数据流
     • 状态机
     • 时序 / 并发 / 排队

4. 类比迁移

   • 遇到拥堵、震荡、雪崩、阻塞时，主动寻找物理同构：
     • 队列 / 水库 / 缓冲
     • 熔断 / 断路器
     • PID / 弹性控制

5. 反馈与验证

   • 没有可观测闭环的设计，不算完成
   • 特别注意：
     • 时滞
     • 非线性
     • 假阳性测试
     • 真实环境与离线环境的分层差异

详细方法论与例子见：

• references/gda-framework.md

2. 启动动作：先写 Control Contract

在真正改代码前，先产出一个极短的控制合同 v2（可在回复、计划或审计文档里）：

• Primary Setpoint
  • 本轮最主要的目标变量，必须是一句能判断成败的话
• Acceptance
  • 哪些测试、命令、日志或指标能证明主目标已达成
• Guardrail Metrics
  • 哪些护栏指标不能被顺手打坏，例如错误率、尾延迟、成本、吞吐
• Sampling Plan
  • 用什么频率、在哪些观察点采样，避免只看一次结果就下结论
• Known Delays / Delay Budget
  • 已知时滞在哪里，以及本轮允许消耗多少时滞预算，例如 CI 排队、异步队列、缓存刷新、灰度传播
• Recovery Target
  • 如果本轮控制失败，允许多快恢复到安全状态，例如 MTTR 预算或回滚时限
• Rollback Trigger
  • 一旦出现什么信号，默认停止推进并回滚，而不是继续硬顶
• Constraints
  • 不能破坏什么硬约束、不变量、合规边界或真实环境前提
• Boundary
  • 本次允许触碰的模块、文件、配置、schema 与运行流程范围
• Coupling Notes
  • 这次改动会和哪些模块、共享接口、共享状态发生耦合
• Approximation Validity
  • 本轮采用的近似、stub 或离线验证在哪些条件下才成立
• Actuator Budget
  • 本轮允许施加多少控制输入，例如允许改代码、配置、观测点中的哪几类
• Risks
  • 1~3 个主要风险与缓解方式

如果用户没给验收标准，先从：

• issue
• 失败日志
• 现有测试
• 文档契约

中提炼；仍缺失时，补最小合理验收。

3. GDA 四步执行骨架

Step 1：Axiom & Boundary

开始前必须回答：

• 系统真正目标是什么
• 不能违反的硬约束是什么
• 现有实现的关键不变量是什么
• 物理/环境边界在哪里（网络、磁盘、数据库 schema、构建环境）

Step 2：Multi-model Construction

至少同时建立以下三个模型中的两个，复杂任务必须三个都建：

• 静态契约域
  • API / schema / 事件格式 / 配置项
• 动态状态域
  • 状态机 / 生命周期 / 回调矩阵 / 状态收口
• 容量与排队域
  • 队列、缓冲、吞吐、时滞、阻塞点

复杂任务还应显式补一个黑盒输入-输出影响矩阵：

• 把系统先当成黑盒，不急着解释内部实现
• 先列：
  • 当前准备调哪个 control input / knob
  • 希望影响哪个 output
  • 影响方向是增、减、延后还是收敛更快
  • 会不会外溢到相邻模块、共享状态或共享基础设施

如果系统是多变量耦合的，再补一个解耦矩阵：

• 哪些输入主要影响哪个输出
• 哪些输入会顺带打坏别的输出
• 哪些输入必须成组调整，不能单独动

一个典型例子：

• 调高重试次数
  • 目标 output：短期成功率可能上升
  • 连带 output：尾延迟、下游 QPS、队列积压、成本可能一起上升
• 调低限流阈值
  • 目标 output：下游压力下降
  • 连带 output：入口拒绝率、任务完成时间可能恶化

默认规则：

1. 复杂任务在改实现前，先列控制输入、目标输出、影响方向与外溢风险
2. 如果一个 knob 同时强影响多个 output，默认把它视为高耦合输入
3. 高耦合输入优先做小步试探，而不是一次拉满

Step 3：Cybernetic Control

一次只施加一个最小控制输入：

• 一个最强假设
• 一个最小修改
• 一组最便宜的验证

如果出现振荡：

• 降低步长
• 回到最小 failing case
• 加观测点，而不是继续盲改

Step 4：Closed-loop Verification

验证必须分层：

• L0 快回路
  • lint / typecheck / 单测子集 / 静态审计
• L1 中回路
  • 相关模块测试 / 小集成
• L2 慢回路
  • 全量回归 / 真实环境 / 性能 / gate

原则：

• L0/L1 不稳定，不进入 L2
• 离线通过不等于真实环境通过
• 必须显式标注哪些风险只在 L2 才能验证

4. 传感器工程（Harness Engineering）

4.1 基线建立

默认顺序：

1. git status / git diff
2. 读取 issue、相关代码、最近改动、已有 review
3. 跑最便宜的验证路径
4. 记录失败命令、失败用例、关键信号

4.2 传感器去噪

如果信号不稳定：

• 重跑 3~5 次
• 固定随机种子 / 时区 / 并发
• 隔离外部依赖
• 把偶现变成最小稳定复现

4.3 特别规则：schema-sensitive 路径

凡是涉及以下任一因素：

• 真实数据库列类型
• SQL cast
• 驱动参数序列化
• PG_CH / 真实 broker / 真实文件系统 / 真实扩展加载

都必须明确区分：

1. 语义测试
   • fake fetcher / stub / resolver 白盒
2. schema 契约测试
   • 锁定关键 SQL / schema / 分支行为
3. 真实环境 gate
   • Windows / VPN / 真实数据库 / 真实 broker

禁止把：

• “resolver 语义通过”
• “cargo test 全绿”

直接写成：

• “真实环境通过”

4.4 动态控制病：采样与观测新鲜度

性能和稳定性问题默认先审查观测质量，而不是先改实现。

必须显式检查：

• 采样周期
  • 采样过慢会把瞬时尖峰、短时雪崩、短时队列积压平均掉
  • 采样过快但没有聚合窗口，会把瞬时噪声误判成系统趋势
• 观测新鲜度
  • 延迟到达的 metrics、异步刷新的 trace、缓存后的 dashboard，可能让你基于旧世界做新决策
  • 任何观测结果都要先确认时间戳、刷新周期和传播时滞
• 采样别名
  • 用粗粒度采样看周期性抖动时，容易把真实震荡看成稳定
  • 典型后果是把“周期性过载”误判成“偶发 flake”
• 陈旧指标
  • 指标本身还在更新，但语义已经落后于当前发布版本、schema 或流量路径
  • 典型后果是优化了旧瓶颈，却把新主链打坏
• 观测盲区
  • 只看入口成功率，不看下游队列、缓存击穿、回放链路，会把局部成功误判成整体稳定

默认规则：

1. 遇到性能或稳定性问题，先写清本轮采样周期、观测新鲜度和主要盲区
2. 任何“趋势判断”都必须说明观测窗口，而不是只引用单次结果
3. 如果怀疑存在采样别名或陈旧指标，先补观测点或换采样方式，再决定是否改代码

4.5 动态控制病：去抖、滞回、退避与冷却

很多系统不是“控制能力不足”，而是“控制动作太频繁”。

默认要检查四种抑振手段：

• 告警去抖
  • 当同类告警在短时间内反复触发时启用
  • 目的不是隐藏故障，而是避免把瞬时尖峰误当成稳定故障模式
• 滞回区间
  • 当扩缩容、限流、熔断或降级阈值存在边缘来回抖动时启用
  • 进入阈值和退出阈值不应完全相同，否则系统会反复横跳
• 退避策略
  • 当重试、探测、轮询、恢复动作连续失败时启用
  • 失败后必须扩大间隔，而不是用固定频率继续打系统
• 控制冷却时间
  • 当一次控制动作刚施加、系统尚未完成传播和收敛时启用
  • 在冷却窗口内默认禁止同类控制动作再次触发

执行规则：

1. 只要控制动作会修改阈值、流量、路由、重试或容量，就必须声明是否存在滞回和冷却窗口
2. 只要恢复动作依赖轮询、重试或探测，就必须声明退避策略
3. 默认禁止连续重复同类控制动作不带冷却窗口
4. 如果没有去抖或滞回设计，任何“阈值附近反复跳变”都应先视为控制病，而不是先怪业务逻辑

4.6 动态控制病：anti-chatter、anti-windup 与控制器冲突

当系统已经进入震荡区，继续叠加控制器通常只会把问题放大。

• anti-chatter
  • 指防止控制动作在相邻状态之间高速来回切换
  • 典型场景：熔断开关在半开与关闭之间反复横跳，或扩缩容在相邻副本数之间频繁切换
• anti-windup
  • 指防止控制器在执行器已经饱和时，仍然继续累积“应该再加一把力”的内部误差
  • 典型场景：下游已经限流或队列已经打满，但上游重试、补偿或扩容信号仍不断叠加，最终形成重试风暴或扩缩容超调
• 控制器冲突
  • 指两个及以上控制器同时修改同一 knob，却没有统一仲裁
  • 典型场景：应用内重试、sidecar 重试、网关重试同时打开；HPA、队列消费调度器、人工扩容同时改副本数

默认规则：

1. 同一 knob 只能有一个主控制器，其他控制器要么只观测，要么通过明确仲裁接入
2. 只要执行器已经饱和，就必须显式考虑 anti-windup，而不是继续累积恢复动作
3. 只要系统出现高频开关、周期性回摆或阈值附近来回跳变，就必须先排查 anti-chatter
4. 遇到重试风暴、补偿堆积、扩缩容超调，默认先查控制器冲突，再查业务逻辑

4.7 无观测，不优化

任何性能或稳定性优化，默认都要先拿到观测基线。

最小入场券：

• trace
  • 先看跨服务链路到底卡在哪一跳
• flame graph
  • 先看 CPU / wall time 真正烧在什么调用栈
• profiling baseline
  • 先记录修改前的基线，不要只拿修改后的单次结果自嗨
• golden signals
  • 至少关注延迟、流量、错误、饱和度这类核心信号
• 对照实验
  • 能做 A/B、shadow、canary 或前后对照时，优先做对照，而不是纯猜测

默认规则：

1. 无观测，不优化
2. 观测不足时，默认先补观测点、profiling 或链路追踪，再决定是否改代码
3. 任何“感觉这里慢”“猜这里有瓶颈”的说法，都不能直接升级成优化动作
4. 优化结果至少要和修改前的 profiling baseline 做一次对照

5. 决策准则

当多个方案都能修时，优先：

1. 最小风险
2. 最强可验证
3. 最可逆
4. 最符合模块业务区位

特别注意：

• 不为了通过测试而偏离原始语义
• 不为了抽象而扩大不该公开的 API 面
• 不把测试便利性凌驾于模块职责之上

5.1 机制优于策略

默认优先设计“生成策略的机制”，而不是把人的经验直接硬编码成静态策略。

默认禁止把以下对象直接写死成“经验常数”后就当作稳定设计：

• timeout
• retry 次数
• 熔断阈值
• 连接池大小
• 扩缩容阈值

优先选择的机制包括但不限于：

• 自适应控制
  • 根据延迟、错误率、队列长度、资源利用率动态调整控制输入
• 反馈回路
  • 让上一次控制结果影响下一次控制强度，而不是重复拍脑袋
• 搜索或在线学习
  • 当最优点未知且环境持续漂移时，用搜索、探索或在线更新替代静态猜测

裁决规则：

1. 能用机制吸收环境变化时，默认不要把人的经验写成永久阈值
2. 静态策略只能作为启动值、护栏值或临时保守值，不能伪装成长期真理
3. 如果一个策略需要频繁人工调参，优先怀疑“缺机制”，而不是继续加参数

例外条件：

• 环境几乎不变、观测明确且失效成本极高时，可以短期采用静态策略
• 但必须同时写清监控条件、失效信号与后续替换计划

5.2 MTTR-first 与 crash-only

对现代复杂系统，默认优先级不是“尽量永不出错”，而是“出错后多快回到安全状态”。

默认裁决：

• MTTR 优先于 MTBF
  • 当两种方案不能同时兼得时，优先选择更快恢复而不是更长时间不出错
• crash-only
  • 遇到不可恢复、未定义或无法证明安全的状态，优先显式失败、退出或重启，而不是维持僵尸状态
• 自动回滚
  • 只要风险可外溢到共享接口、共享状态或核心链路，就要优先设计自动回滚信号
• 故障注入
  • 不能只验证“正常时能跑”，还要验证“坏了能多快恢复”

执行规则：

1. Control Contract 里的 Recovery Target 不是装饰项，必须给出恢复时间预算或安全回退时限
2. 只要系统进入不可恢复状态，默认先显式失败，而不是静默维持
3. 只要回滚条件可被机器识别，就优先设计自动回滚，而不是依赖人工盯盘
4. 任何声称“高可用”的路径，都应至少经过一次故障注入或等价恢复演练

特别注意：

• crash-only 不是吞错后假装恢复，而是让失败可见、可重启、可回退
• 快速恢复不等于快速掩盖，必须保留故障证据、恢复路径和恢复时间

5.3 抽象审查协议

抽象的默认目标不是“减少重复”，而是“减少错误耦合”。

默认原则：

• 允许 WET
  • 如果两段逻辑当前相似，但未来不保证一起变化，允许先物理重复
• 优先物理解耦
  • 宁可保留两份小实现，也不要为了复用把两个生命周期不同的模块绑死
• 按共变关系做抽象
  • 决定是否抽象的依据，不是代码长得像，而是未来是否真的会同时变化

判定规则：

1. 只要两个调用点的发布节奏、故障域或 owner 不同，默认先不要抽象
2. 只要抽象会扩大共享 API 面、共享状态面或统一门禁面，先怀疑这是错误抽象
3. 代码相似但业务语义、失败模式或演化方向不同，不应因为“长得一样”就抽象
4. 在决定抽象前，至少回答一次：它们未来真的会同时变化吗

反过来说：

• DRY 不是被废除，而是要服从模块职责、故障隔离和长期演化
• 如果抽象让系统更难切分、更难回滚、更难定位责任，就不是好抽象

5.4 演进式架构与可逆决策

复杂系统默认不是被一次性设计出来的，而是从简单可用系统逐步长出来的。

默认原则：

• 先长出简单可用系统，再逐步演化
  • 没有真实反馈前，不要预支未来 5 年的复杂性
• two-way door 决策优先快试
  • 可逆决策优先小步试、快反馈、保留回退路径
• one-way door 决策优先控边界
  • 不可逆决策必须先冻结契约、清点依赖、确认迁移窗口

执行规则：

1. 每个重要架构决策都应先判断它是 two-way door 还是 one-way door
2. two-way door 决策优先用小范围实验、最小实现、短反馈回路验证
3. one-way door 决策必须显式写出桥接期、回退条件和受影响模块
4. 契约默认先稳后扩，不要在桥接期一边迁移一边改口径

桥接期协议：

• 迁移默认存在一个桥接期
• 桥接期内优先使用：
  • shadow
    • 新链路跟跑、不接管主裁决
  • canary
    • 小流量、小范围、可快速回退
• 桥接期结束前，默认保留旧事实源或旧主链作为对照基线

如果一个方案：

• 无法定义桥接期
• 无法解释怎么回退
• 无法说明契约何时冻结

那它默认不是成熟的演进式架构方案

6. 高风险反模式（必须主动检查）

1. 假收敛

   • 单测通过，但真实环境条件未覆盖

2. 双真相

   • 文档一套、主链一套、备用路径一套

3. 影子实现

   • callback_dispatcher 更完整，但主链不用
   • helper 存在，但主链不可达

4. 弱断言

   • 只有 is_ok()，没有行为语义断言

5. 测试驱动代码偏离职责

   • 为了测试方便扩大 pub 面
   • 暴露本不该公开的内部实现

6. 把离线测试当 gate

   • 真实 schema / 真实扩展 / 真实网络问题无法由 stub 替代

7. 交付格式

最终交付优先按下面结构组织：

1. Summary
2. State Estimate / Root Cause
3. Changes
4. Verification
5. Recovery Evidence
6. Observability Evidence
7. Residual Risks / Gate Boundary

其中：

• Recovery Evidence
  • 说明怎么恢复、多久恢复、触发了什么回滚或重启语义、恢复预算是否满足
• Observability Evidence
  • 说明依据什么判断问题存在、优化有效或风险仍在
  • 至少给出本轮关键日志、指标、trace、profiling 或 gate 证据中的一类

如果是长任务，还应同步：

• 审计文档
• 回归矩阵
• handoff 文档

8. 实战剧本

Bugfix / 回归

1. 最小复现
2. 最小 failing test
3. 根因假设
4. 最小修复
5. 相关回归
6. 全量相关回归

测试补强

1. 审计当前覆盖层次
2. 找“语义层 / schema 层 / 真实环境层”缺口
3. 先补最能拦截真实风险的离线测试
4. 再补回归矩阵
5. 最后明确 gate 边界

架构收口 / 清理

1. 先证明主链实际入口
2. 再证明影子实现是否仍被使用
3. 删除或收敛重复事实源
4. 用测试或调用链审计防止回归

性能退化

1. 先拿 profiling baseline 与 golden signals
2. 再定位是 CPU、IO、锁竞争、网络还是排队
3. 画输入-输出影响矩阵，避免错改高耦合 knob
4. 小步优化并做前后对照
5. 记录收益、代价与残余风险

异步队列背压

1. 先确认队列长度、消费速率、重试率、死信情况
2. 再区分是数据面过载、状态面卡死还是控制面误配
3. 检查 anti-windup、退避与扩容是否互相打架
4. 先止血，再恢复，再补治理
5. 明确消息堆积的恢复边界

迁移 cutover

1. 先定义桥接期与冻结边界
2. 再安排 shadow、canary 或双写对照
3. 明确切流条件、回退条件、终止旧链路条件
4. 分层验证 cutover 前、中、后状态
5. 最后关闭桥接并归档证据

部分故障 / 依赖 brownout

1. 先确认故障是全挂还是 brownout
2. 再查重试、熔断、降级是否放大故障
3. 识别依赖是否已进入不可恢复状态
4. 优先保主链和恢复预算
5. 记录恢复动作和隔离边界

配置回滚

1. 先确认问题是否由配置变更触发
2. 再识别配置属于控制面、数据面还是状态面
3. 检查是否满足自动回滚触发条件
4. 回滚后验证关键护栏指标是否恢复
5. 补配置审计与冻结规则

Flake Triage

1. 先稳定复现，确认是否真 flake
2. 固定随机种子、时区、并发与外部依赖
3. 区分测试抖动、环境抖动、时序抖动、观测误判
4. 用最小观测点把偶发现象变成稳定信号
5. 再决定是修实现、修测试还是修环境

成本失控

1. 先确认成本是流量驱动、重试驱动还是闲置浪费
2. 再看哪个 control input 把成本推高
3. 检查是否存在过量重试、过量扩容、过量缓存或重复计算
4. 优先找可逆的小步降本动作
5. 明确降本对成功率、延迟与可靠性的护栏

SLO 漂移

1. 先确认是瞬时波动还是长期漂移
2. 再看 setpoint、guardrail 与采样窗口是否仍有效
3. 检查控制器是否已经失调或环境是否变了
4. 优先调恢复与观测，再调业务逻辑
5. 明确是改 SLO、改实现，还是改治理策略

9. 引用导航

如果需要更完整的理论和场景化方法，请按需读取：

• references/gda-framework.md
  • 五维方法论
  • GDA 四步法
  • 软件总体设计视角
• references/README.md
  • 引用索引
• assets/quickstart.md
  • 快速用法与交付模板