日常工作知识库

Appearance

SpecFlow SDD 规范驱动开发工作流指南与 specflow-hub 全解包架构 ​

📌 一、 概述 ​

SpecFlow 是 58 部门级规范驱动 AI 工程化工具链（Spec-Driven Development, 简称 SDD）。本文档定义了 SpecFlow 的双仓寻址引擎 (ctx.specDir / ctx.codeDir)、规范仓 (-spec) 资产物理隔离标准、specflow-hub 全量资产物理解包下发架构（含技能包与规制包）、标准 5 维说明书生成机制，以及 iGit MR API 创建与 409 竞态自动绑定发帖逻辑。

📌 二、 双仓寻址与规范物理隔离 (ctx.specDir vs ctx.codeDir) ​

在 58 研发实践中，部门推行 Sibling (并立同级) 规范部署体系：

text
specflow-examples/
├── reimburse-pc/                       # 👈 业务代码仓 ctx.codeDir (Pure Code Base)
│   ├── src/views/                      # 业务 Vue 组件 (只包含生产打包代码)
│   └── package.json
│
└── reimburse-pc-spec/                  # 👈 规范与大脑仓 ctx.specDir (Spec Base)
    ├── .agent/                         # Agent 指导指南与解包后的规制/技能资产
    │   ├── agents.md                   # Agent 执行指南
    │   ├── rules/DEPT_SHARED/          # 部门 5 大通用规制 (安全/财务大数/质量)
    │   ├── skills/                     # 📌 部门 AI 技能包 (skill-auditor, specflow-* 等)
    │   └── scripts/                    # 部门自动化脚本
    ├── .specify/                       # 📌 所有需求的 5 维契约集中保存在此
    │   └── reimburse-invoice-check/    # 需求隔离子目录
    │       ├── reimburse-invoice-check.spec.md
    │       ├── reimburse-invoice-check.plan.md
    │       └── test-cases/
    ├── temp/                           # 📌 本地草稿需求存放区 (如 draft.md)
    ├── specflow.config.json            # 架构索引契约
    └── docs/                           # VitePress 看板 (渲染 .specify/ 契约)

核心隔离原则 ​

  1. .specify/ 强约束：所有的 .specify/<reqName>/ 规范文件 物理强制存放在 ctx.specDir (reimburse-pc-spec)，业务仓 reimburse-pc 保持绝对纯净。
  2. 源码落盘约束：所有的 Vue/TS/Java 物理业务代码 物理落盘在 ctx.codeDir (reimburse-pc)。

📌 三、 specflow-hub 全量资产物理解包落盘机制 ​

当运行 specflow init 时，系统会自动从 58 远程能力中心或本地多层级同级目录解包，将 specflow-hub 的全量资产物理下发至 reimburse-pc-spec/.agent/：

资产类型解包来源路径物理落盘路径作用与约束机制
规则库 (Rules)specflow-hub/rules/.agent/rules/DEPT_SHARED/5大部门规制（SEC-001/FIN-002/QUAL-005）
技能包 (Skills)specflow-hub/skills/.agent/skills/包含 skill-auditor, specflow-review, specflow-testgen 等 AI 技能
脚本库 (Scripts)specflow-hub/scripts/.agent/scripts/部门自动化质检与同步脚本
指南 (Guide)specflow-hub/SKILL.md.agent/agents.mdAgent 交互指南与上下文指针绑定

📌 四、 标准 5 维 SDD 规格说明书 (5D Spec) 生成规范 ​

无论是通过美事在线文档、temp/ 本地草稿文件还是 sddx 贯穿，SpecFlow 均全自动生成并锁存 标准的 5 维 SDD 规格说明书 (.spec.md)：

  1. 一、 业务场景与用户故事 (User Story)：明确目标用户、核心价值与需求意图；
  2. 二、 接口与数据契约规范 (API & Data Contract)：定义接口路径、JSON Input/Output 与 BigDecimal 金额传输标准；
  3. 三、 交互与 UI/UX 规则 (UI & Behavioral Spec)：防重提交 Loading 状态、错误高亮滚屏；
  4. 四、 质量与安全合规防线 (Quality & Security Guardrails)：密钥安全 (SEC-001)、业财精度 (FIN-002)、异常兜底 (QUAL-005)；
  5. 五、 验收测试标准 (Acceptance Criteria)：AC-1/AC-2 与覆盖率 $\ge 85%$ 硬门禁。

📌 五、 双仓 Git 物理提交、Auto Push 与 iGit MR 竞态恢复 ​

1. 双仓提交与自动 Push 引擎 (pushDualRepos) ​

在 P3 Coding 或 specflow mr 阶段，CLI 自动切入需求分支 specify/<reqName>，并发起双仓 Git 操作：

  • 规范仓 (reimburse-pc-spec)：执行 git add . 与 git commit -m "feat(spec): ..."，并运行 git push -u origin specify/<reqName>；
  • 业务仓 (reimburse-pc)：执行源码 Commit，并运行 git push -u origin specify/<reqName>。

2. iGit MR 创建与 409 竞态恢复发帖 ​

  • 新建 MR：调用 iGit REST API 创建 Merge Request，拿到单号（如 !17）与 Web URL；
  • 竞态恢复 (409 Conflict)：若该分支已存在打开的 MR，API 自动拦截并调用列表 API 动态检索拿到已存在的 MR 单号 !17，自动将 AI 质检报告贴回评论区（Discussion Thread）。