---
schema: workhub/loop/v1
name: 标准需求交付
entry: requirements
nodes:
  - id: requirements
    name: 需求分析
    agent: public/requirements-analyst
    rules:
      - 产出需求说明：背景、目标、功能清单、验收标准、不做什么
      - 明确判定涉及前端、后端还是两者，后续节点按这个判定执行
      - 需求要点经人确认后才进入下一步
    next:
      - {to: prototype, when: 需求已经人确认}
  - id: prototype
    name: 原型设计
    agent: public/prototype-designer
    rules:
      - 涉及前端时产出可点击的低保真 HTML 原型；只涉及后端时产出接口草案
      - 原型经人确认后才进入下一步
    next:
      - {to: [data-model, smoke-cases], when: 原型已经人确认}
      - {to: requirements, when: 发现需求不清或相互矛盾, max_loops: 2}
  - id: data-model
    name: 数据模型设计
    agent: public/data-modeler
    rules:
      - 写清实体、字段、关系、约束和对现有数据的影响；没有数据变更时写明“无数据变更”
      - 与冒烟用例设计并行，只写数据模型.md
    next:
      - {to: implement}
  - id: smoke-cases
    name: 冒烟用例设计
    agent: public/smoke-test-designer
    rules:
      - 每条验收标准至少对应一条冒烟用例，覆盖主流程
      - 与数据模型设计并行，只依据需求和原型，预期结果用业务语言写；只写冒烟用例.md
    next:
      - {to: implement}
  - id: implement
    name: 编码
    agent: public/fullstack-developer
    join: all
    rules:
      - 开始前核对冒烟用例与数据模型是否一致，不一致先修正设计文件
      - 按需求分析判定的范围实现前端、后端
      - 遵守项目规范；改了业务逻辑或代码结构，同一个提交里更新知识库
      - 补充单元测试，本地全部通过才进入冒烟测试
    next:
      - {to: smoke-test}
  - id: smoke-test
    name: 冒烟测试
    agent: public/smoke-tester
    rules:
      - 按冒烟用例逐条执行，结果记到用例文件里
      - 全部通过才结束；有失败就带着失败记录回到编码
    next:
      - {to: done, when: 全部用例通过}
      - {to: implement, when: 有用例失败, max_loops: 3}
---

## 说明

这是所有接入项目默认使用的需求交付流程，一个需求从提出到冒烟测试通过走一遍。

- **产出位置**：同一个需求的设计产出都放在 `<设计目录>/<需求主题>/` 下（设计目录默认 `docs/design/`，项目用映射方式时以 `.workhub/layout.yaml` 的 `design` 为准）。`<需求主题>` 用 `YYYYMMDD-简短主题`，如 `20261021-订单退款`：

  ```text
  docs/design/20261021-订单退款/
  ├── 需求.md          需求分析
  ├── 原型/            原型设计（HTML 原型或接口草案）
  ├── 数据模型.md       数据模型设计
  └── 冒烟用例.md       冒烟用例设计，冒烟测试的结果也记在这里
  ```

- **并行**：原型确认后，数据模型设计和冒烟用例设计同时进行，两者都完成后才进入编码（汇合）。执行方式：
  - 主 AI（当前会话）为每个分支启动一个子任务：Claude Code 用两个并行的子代理（subagent）；Codex 在后台启动两个 `codex exec` 进程，各自完成一个分支，主 AI 等两个进程都结束；环境不支持时按顺序执行，结果相同。
  - 子任务只写自己的产出文件（`数据模型.md` 或 `冒烟用例.md`），不改代码，不改 `.workhub/progress.yaml`，不提交。
  - `.workhub/progress.yaml` 和提交只由主 AI 负责：分叉时 `stage` 写“数据模型设计 + 冒烟用例设计”，汇合后写“编码”。
  - 汇合时主 AI 先核对两份产出：用例里用到的数据（字段、状态、取值）在数据模型里都能找到，数据模型的约束（必填、唯一、取值范围）在用例的异常情况里有体现；不一致就修正对应文件，再开始编码。
- **人工确认点**：需求要点、原型。这两处确认后才进入下一步，其他节点由 AI 按完成标准自行判断。
- **回环**：原型设计时发现需求不清，回到需求分析（最多 2 次）；冒烟测试有用例失败，回到编码（最多 3 次）。超过次数停下来问人。
- **进度**：进入新节点、遇到阻塞、需求完成时，按项目规范更新 `.workhub/progress.yaml`，工作项的 `stage` 写当前节点名称。
- 小改动（改文案、修一个明确的 bug）可以跳过原型和数据模型节点，但要在需求说明里写明跳过的理由，并经人确认。