StormFlow

Appearance

开发工作流：SDD → TDD → BDD ​

概述 ​

StormFlow 采用 Spec-Driven Development 作为主干工作流。每个功能从写规格开始，测试在代码前编写，代码让测试变绿。

完整流程 ​

Step 0：检查 ADR ​

查阅 docs/decisions/，确认是否有已决策的架构约束。如果此次功能涉及重大技术选型，先写 ADR。

Step 1：写功能 Spec（WHAT 层） ​

在 docs/specs/{feature}.md 中按模板写规格：

  1. 明确一句话目标（用户视角，不提技术）
  2. 写行为约束（前置条件 / 行为 / 后置条件）
  3. 写状态机（如有状态转换）
  4. 列出 Acceptance Criteria — 每条可被测试验证
  5. 将 AC 转化为 BDD Gherkin Scenario
  6. 标注 TDD 单元测试要点

Spec 审查清单：

  • [ ] 每条 AC 是否可被单个测试验证？
  • [ ] Spec 中是否混入了 UI 细节（按钮颜色、像素数值）？如果是，移至 guides/design-system.md
  • [ ] 是否提到了具体实现技术？如果是，移至 decisions/

Step 2：更新模块契约 ​

如果此功能新增或修改了模块的边界、不变量或同步流程，先更新 docs/modules/{module}.md。

Step 3：写失败测试（RED） ​

3a. 单元测试：

从 Spec 的"TDD 单元测试要点"逐条创建，全部为 FAIL：

bash
pnpm test:unit --watch

3b. 集成测试骨架：

从 BDD 场景中标注为 集成测试 的条目创建测试，先用 it.skip 标记：

typescript
it.skip('场景描述', async () => {
  // Given / When / Then
})

标注为 手动 的 BDD 场景不写自动化测试，在发版前通过人工 checklist 验证。

Step 4：写最小实现（GREEN） ​

按以下顺序：

  1. shared/types/ + shared/utils/ — 类型定义和纯函数
  2. stores/ — 纯逻辑（让单元测试通过）
  3. services/ — 服务层
  4. components/ — UI 层（让集成测试通过）

规则： 只写让当前失败测试通过的最小代码，不超前实现。

Step 5：重构（REFACTOR） ​

所有测试保持绿色的前提下：提取重复、改善命名、整理结构。

Step 6：激活集成测试 & 执行人工验证 ​

移除 it.skip，运行集成测试：

bash
pnpm test:nuxt

对标注为 手动 的 BDD 场景，按 testing.md 中的人工验证 checklist 逐项确认。

Step 7：更新 Spec 状态 ​

将已完成的 AC 标记为 [x]。Spec 必须与实现同步，这是 SDD 的核心纪律。

规则 ​

  1. Spec 先行 — 没有 Spec 的功能不开始开发
  2. AC 即测试 — 每条 AC 必须有对应测试
  3. Spec 与代码同步 — 已实现的 AC 必须是 [x]，未实现的必须是 [ ]
  4. ADR 记录重大决策 — 技术选型、架构变更必须写 ADR，与代码一起提交

快速参考 ​

bash
# 开发时持续运行测试
pnpm test:unit --watch

# 提交前全量验证
pnpm test && pnpm typecheck && pnpm lint