日常工作知识库

Appearance

SpecFlow AI 质量治理“三层金字塔”沉淀与落地方案 ​

归类：SpecFlow / AI 工程化与质量治理
发生时间：2026-09-15
状态：✅ 已落地 (SpecFlow v0.127.0+)

一、 问题背景与 AI 协同盲区 ​

随着团队全面引入 AI 辅助编程（AI Coding），开发效率得到了显着提升。然而在实际业务落地过程中，大语言模型（LLM）因对隐性业务校验约束、特殊边界格式（如千分位逗号）以及多字段物理级联依赖关系缺乏深度上下文感知，容易生成“表面合规但隐患极大”的代码：

  1. 假性完成与静默归 0：遇到转换异常时，AI 习惯性添加 try { ... } catch { return 0; } 导致错误被静默吞掉，造成财务数据失真。
  2. 局部盲修与级联死锁：按照 Surface 需求修改字段必填逻辑时，遗漏上游派生字段与关联策略的分支处理，导致保存提交时出现级联校验硬阻断。
  3. 审计疲劳与防线遗漏：传统的“人肉 Code Review + 线下人工测试”面对 AI 批量产出的代码极易产生审计疲劳。

为解决上述痛点，SpecFlow 提出了 “线上故障发生一次 ➔ 深度归因剖析 ➔ 沉淀为刚性 Rule + Few-Shot 案例 ➔ 全局 AI 自动防范” 的自动化防护闭环。

二、 线上故障典型案例归因剖析 ​

💥 Case 1：导入千分位金额格式化解析导致数据静默归 0 ​

  • 现象：用户在 Excel 批量导入金额时，只要金额超过 1,000.00 元（带千分位逗号），系统导入后金额全部显示为 0 元。
  • 深层根因：AI 生成的解析代码未对千分位逗号 , 进行预清洗，new BigDecimal("1,250.00") 抛出 NumberFormatException；AI 生成的代码习惯性使用了 try-catch 容错兜底并静默返回 0 / BigDecimal.ZERO，吞掉了关键报错。

💥 Case 2：新增折扣类型遗漏价格策略级联校验阻断 ​

  • 现象：合同配置保存时抛出错误 合同配置提交校验不通过:产品配置-第1行，价格策略为波动时，波动类型不能为空。
  • 深层根因：需求提出“新增折扣类型：无需单价”。AI 仅修改了单价 price 的非空校验，未分析单价上游派生的 pricePolicy (价格策略) 与 fluctuateType (波动类型) 的依赖树，导致选了“无需单价”后依然走入了价格策略分支并校验失败。

三、 SpecFlow “三层金字塔” 防线架构设计 ​

SpecFlow 将事故归因与防御规则划分为三层金字塔结构：

                    ┌─────────────────────────────────────────┐
                    │  1. 刚性规则层 (AGENTS.md Rules)        │ ──► P5 静态审计 & CLI 硬门禁 (一票否决)
                    ├─────────────────────────────────────────┤
                    │  2. Few-Shot 案例库 (examples/CASE-xxx)  │ ──► P1/P2/P3 动态 Prompt 注入 (引导 Reasoning)
                    ├─────────────────────────────────────────┤
                    │  3. 复盘知识库 (postmortems/YYYYMM-xxx) │ ──► 全局文档站与归档检索
                    └─────────────────────────────────────────┘

1. 第一层：刚性规则层 (AGENTS.md Rules) ​

  • 适用标准：通用性强、危害极大的硬性红线。
  • 沉淀案例：
    • Rule 47 (AMOUNT-PARSE-NO-ZERO-FALLBACK Rule)：所有外部获取的金额，转换前必须预清洗千分位 .replace(",", "")；绝对禁止静默 catch 归 0；解析失败必须显式抛出 BizException 阻断。
    • Rule 48 (ENUM-CASCADE-VALIDATION Rule)：新增枚举/业务类型时，强制在 P2 Plan 阶段全量探查依赖树，物理代码必须同步继承更新级联校验表达式。
    • Rule 49 (NEXT-STEP-COMMAND-PROMPT Rule)：完成任意 SDD 阶段交互后，必须在回复末尾自动渲染结构化的【📌 下一步实施指令推荐】卡片。

2. 第二层：Few-Shot 业务实战案例库 (specflow-hub/examples/) ​

  • 适用标准：包含完整场景 ❌ Bad Practice 与 🟢 Good Practice 对比的案例，作为 Prompt 引导 AI 模型深度推理。
  • 沉淀案例：
    • CASE-006-amount-thousandth-parser.md：带千分位金额文本解析与防静默归 0 代码及单测案例。
    • CASE-007-enum-extension-cascade-validation.md：新增业务枚举类型与关联级联校验一致性代码案例。

3. 第三层：复盘知识库 (specflow-hub/knowledge-base/postmortems/) ​

  • 适用标准：事故全貌记录、故障影响与履历归档。
  • 沉淀案例：202608-amount-format-zero-fallback.md 与 202609-enum-extension-missing-cascade-logic.md。

四、 跨语言通用与自适应匹配机制 ​

SpecFlow 的治理规则面向全语言全技术栈（Language-Agnostic），通过 三步自适应匹配引擎 实施：

  1. 物理技术栈探查：扫描项目 pom.xml 或 package.json 判定是 Java、TS/Vue 还是 Go 工程。
  2. 上下文范式转义：
    • 在 Java 仓下将 Rule 47 转义为 BigDecimal + StringUtils.replace + BizException；
    • 在 TS/Vue 仓下将 Rule 47 转义为 str.replace(/,/g, '') + Form Validator 正则拦截；
    • 在 后端与前端 形成端到端的双重防线（End-to-End Dual Guard）。
  3. P5 多语言 AST 静态门禁：specflow review 审查时根据文件后缀 (.java / .ts / .vue) 自动识别并调度相应的 AST 语法树解析器，探查违规代码并扣分。

五、 实施效果与自动化闭环 ​

  1. 动态 Few-Shot 挂载：Agent 执行 sddx 或 /specflow-task 提示词构建时，匹配到“导入”、“金额”关键词自动挂载 CASE-006，匹配到“枚举扩展”自动挂载 CASE-007。
  2. P5 Review 一票否决：发现带静默 catch 归 0 或遗漏级联校验的代码，直接触发 AMOUNT-PARSE-001 / ENUM-CASCADE-001 硬扣分卡点。
  3. 发布闭环：该设计已收录在 SpecFlow CLI v0.127.0 及 specflow-hub 中，完成 58 私有 Npm 源、SkillHub 技能市场、全局 CLI 客户端及 VitePress 文档站的物理强同步。