日常工作知识库

Appearance

SpecFlow SDD P1~P7 物理与 AI 双重 Check 质量保障与美事回写容错兜底机制 ​

适用对象：业财研发部产研团队、架构师、AI Agent 治理团队
核心摘要：本文档沉淀了 SpecFlow SDD (Spec-Driven Development) 敏捷交付工作流中 P1~P7 各节点物理 Check (确定性底层防线) 与 AI Agent Reasoning Check (大脑深度推理纠偏) 的双重遵循机制，并定义了美事在线云端文档优先回写与物理规范仓 -spec/docs/temp/ 容错兜底落盘范式。

📌 一、 规范仓 (-spec) 资产读取与双重遵循机制 (Dual Compliance Mechanism) ​

在 SpecFlow 的物理架构中，业务工程（如 reimburse-pc）与同级规范仓（如 reimburse-pc-spec）物理解耦。规范资产的读取与遵循建立在 CLI 物理遵循 与 AI Agent 行为遵循 的双重机制之上：

1. CLI 的物理遵循逻辑 (Deterministic Physical Layer) ​

  • 上下文自动感知 (getAutoContext)：CLI 自动解析 Git 特性分支（如 specify/meeting-fee-intercept），物理定位专属需求目录 .specify/<reqName>/；
  • 全量图谱加载 (codegraph.json)：CLI 解析 -spec/docs/architecture/codegraph.json 依赖拓扑矩阵，物理校验并定位真实业务入口组件；
  • 质量指标比对 (metrics.json)：CLI 读取指标文件，校验单测覆盖率、扣分明细及 Fatal Error 阻断卡点。

2. AI Agent 的行为遵循与双重纠偏机制 (AI Reasoning Layer) ​

  • SKILL.md 硬约束：Skill 规范约束 Agent 必须通过 view_file 或 grep_search 调阅规范仓下的 docs/projects/<projectName>.md 项目级索引，禁止脱离项目架构盲目篡改代码；
  • PRD 级草稿驱动纠偏：Agent 读取原始需求描述或美事云端草稿，通过 LLM 推理补充逼真 Request/Response JSON 数据契约与 AC 验收标准；
  • Prompt 级交互式澄清 (Interactive Clarification Loop)：需求颗粒度不足时在 Chat 会话中主动抛出 1~3 个针对性关键切面提问；
  • 双通道追加回写与兜底策略：生成《本次开发工作流需求场景细化实施指南》，防范产研沟通失真。

📌 二、 美事云端文档回写与物理容错兜底机制 (Meishi Doc Fallback Strategy) ​

在 SDD P1 需求规格化阶段，针对生成《需求场景细化实施指南》建立美事云端优先回写 + 物理仓本地兜底的双重容错防护策略：

1. 优先通道：美事云端在线回写 (Online Sync) ​

  • 触发条件：工作流传入美事文档 URL（如 https://docs.58corp.com/#/space/2087811683069308931），且环境加载了 meishi-docs 技能；
  • 执行动作：Agent 唤醒 meishi-docs 技能，将推理沉淀的《需求场景细化实施指南》自动追加/覆盖至美事云端文档末尾，实现产研线上 PRD 契约强同步。

2. 兜底通道：物理规范仓本地容错落盘 (Physical Fallback) ​

  • 触发条件：缺乏美事技能、未配置认证凭证、API 越权失败或网络超时；
  • 执行动作：无缝容错降级，绝对不阻断工作流。Agent 自动将《需求场景细化实施指南》物理写入同级规范仓的 -spec/docs/temp/<reqName>-clarification-guide.md（或 ./temp/ 目录），保障需求澄清成果 100% 安全存盘。

📌 三、 SDD P1~P7 阶段物理 Check 与 AI Reasoning Check 质量保障拆解 ​

1. P1: Specify Check（需求规格化与智能澄清问询） ​

  • 物理 Check：ensureSpecDirStructure 校验 -spec 仓完备性 $\rightarrow$ 锁定 specify/<reqName> 特性分支 $\rightarrow$ 生成 .specify/<reqName>/<reqName>.spec.md $\rightarrow$ 美事云端同步/物理兜底 $\rightarrow$ 双仓 Git Commit 锁仓。
  • AI Check：唤醒 LLM Reasoning 深度分析原始草稿死角，主动发起交互式问答澄清（Interactive Clarification Loop），并在草稿源末尾/物理兜底目录写入《需求场景细化实施指南》。

2. P2: Plan Check（架构拆解与防重造轮子） ​

  • 物理 Check：解析 codegraph.json 匹配依赖节点 $\rightarrow$ 落盘 .specify/<reqName>/<reqName>.plan.md 打桩大纲 $\rightarrow$ 双仓 Git Commit。
  • AI Check：推演依赖链路影响面（Impact Range），校验既有 Util/组件，强约束 Agent 优先复用既有模块，拦截无脑新建页面与重复轮子。

3. P3: Task Check（物理编码插桩与防守硬拦截） ​

  • 物理 Check：执行 AST/代码非破坏性插桩校验（确保 Diff 符合 +N -0 范式） $\rightarrow$ 执行 TS/Java 静态编译与类型逃逸检查。
  • AI Check：推演场景隐患，强制在提交/保存入口物理植入空值防范与防御性 Toast/Alert 硬拦截，校验变量/组件命名规范。

4. P4: Testcase Check（单测硬门禁与边界用例推演） ​

  • 物理 Check：物理运行 Vitest/Jest 单元测试 $\rightarrow$ 硬性校验单测覆盖率 $\ge 85%$（低于阈值打断卡点） $\rightarrow$ 自动导出 test-cases/ 矩阵。
  • AI Check：针对 AC 规则 Reasoning 推演极端数值、并发竞争与异常响应测试用例，校验 Mock 数据拟真度，杜绝“假断言”凑覆盖率。

5. P5: Review Check（14+5 静态 AST 扫描与契约一致性审计） ​

  • 物理 Check：运行 14+5 静态 AST 规制扫描（包含安全、SQL注入、金额浮点计算、空 Catch 吞噬等） $\rightarrow$ 校验双层表格得分（硬性要求 $\ge 85$ 分且 0 Fatal Error）。
  • AI Check：比对物理代码 Git Diff 与 P1 阶段 .spec.md 的 5 维契约，审查是否存在“挂羊头卖狗肉”的语义偏离及架构死锁隐患。

6. P6: Report Check（质量审计归档与指标推送） ​

  • 物理 Check：将 P1~P5 汇总指标落盘至 .specify/<reqName>/metrics.json $\rightarrow$ 物理同步推送至 specflow-report 审计库。
  • AI Check：AI 大脑归因分析缺陷根因与开发习惯短板，自动生成提案反哺 Rule 规则库。

7. P7: Merge Check（iGit MR 物理创建与智能描述） ​

  • 物理 Check：物理调用 iGit API / Git CLI 发起 Merge Request $\rightarrow$ 自动将 P5 审查双层表格报告作为 Discussion 物理贴回评论区。
  • AI Check：AI 大脑解析全量 Diff，智能撰写具备高可读性的 MR 修改摘要、影响面评估与风险测试说明。

📌 四、 P1~P7 SLA 质量保障全景对照表 ​

SDD 阶段核心 Check 物理动作 (Deterministic Layer)AI Agent Reasoning Check 约束 (AI Reasoning Layer)硬性防线指标 (Gate Metric)
P1 Specify特性分支创建 + .specify/<reqName>/ 落盘 + 云端同步/物理兜底智能澄清问询 (Interactive Loop) + 美事云端/本地兜底回写5 维契约完备落盘
P2 PlanCodeGraph 拓扑匹配 + .plan.md 打桩大纲落盘依赖影响面推演 + 复用既有组件 (防重造轮子)阻断无脑新建页面/重复模块
P3 TaskAST 非破坏性插桩 + TS/Java 编译静态类型校验深度防守校验 (空值防范 + 提交前物理 Toast/Alert 硬拦截)物理 Diff +N -0 防破坏性重写
P4 TestcaseVitest/Jest 单测物理运行 + 测试矩阵文件导出结合 AC 推演极端数值/并发/异常流 + 拟真 Mock 校验单测覆盖率 >= 85%
P5 Review双表格 14+5 静态 AST 扫描与扣分计算Git Diff 与 .spec.md 契约语义一致性审计得分 >= 85分 且 0 Fatal Error
P6 Reportmetrics.json 数据落盘 + 远程数据归档缺陷根因 Reasoning 分析 + 反哺更新 Rule 规则库完成数据落盘与归档
P7 MergeiGit API 物理发起 MR + 评论区双表格贴回AI 智能撰写高可读性 MR 修改摘要与风险评估MR 创建贴回成功