StormFlow

Appearance

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

概述 ​

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

写 Spec → 写失败测试(RED) → 写最小实现(GREEN) → 重构(REFACTOR) → 更新 Spec
  ↑_________________________反馈回路_________________________↑

完整流程 ​

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. E2E 测试骨架：

从 Gherkin Scenario 创建 Playwright 测试，先用 test.skip 标记：

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

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

按以下顺序：

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

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

Step 5：重构（REFACTOR） ​

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

Step 6：激活 E2E 测试 ​

移除 test.skip，运行 E2E：

bash
pnpm test:e2e

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

# 查看 E2E 报告
pnpm test:e2e --reporter=html