Genarrative/.hermes/skills/behavior-driven-development/SKILL.md

---
name: behavior-driven-development
description: 在 Genarrative 中需要用 BDD/行为驱动方式把 PRD、用户故事、验收标准转成可执行场景、Gherkin 用例、测试计划或 TDD 落地顺序时使用。
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [BDD, Gherkin, 验收标准, 用户故事, 测试, Genarrative]
    related_skills: [writing-plans, test-driven-development, systematic-debugging, requesting-code-review]
---

# BDD 行为驱动开发流程

用于在 Genarrative 项目中，把产品需求、用户故事、业务规则和验收标准沉淀成清晰、可讨论、可验证的行为场景，并进一步映射到前端测试、API 测试、领域服务测试或 E2E 测试。

BDD 的重点不是“先写一堆 UI 自动化脚本”，而是让团队先对“用户在什么上下文下做什么，系统应该给出什么可观察结果”达成一致。

## 适用场景

- 从 PRD、设计文档、用户故事中提炼验收标准。
- 功能需求容易产生理解偏差，需要先把行为边界说清楚。
- 涉及前端、后端、运行态、异步任务、权限、埋点或状态流转的跨层功能。
- 需要把“完成标准”写成 Given / When / Then 场景。
- 需要在编码前规划测试覆盖：单元测试、组件测试、API 测试、E2E 测试。
- 希望和 TDD 配合：先写行为场景，再把场景拆到 RED-GREEN-REFACTOR。
- 需要给产品、测试、前后端开发共同评审的一份中文验收说明。

不适用：

- 纯重构且对外行为不变，只需要 characterization tests 或回归测试。
- 一次性小改动，验收规则非常明确且无跨层状态。
- 只想记录实现细节、代码结构或技术方案；这类内容更适合技术设计文档。

## 必读约束

1. 先描述用户可观察行为，再讨论实现细节。
2. 场景必须可验证，避免“体验更好”“更智能”“合理展示”等不可判定表述。
3. 不要把 Gherkin 写成低层 UI 点击脚本；UI 细节只在确实属于业务行为时出现。
4. 中文 PRD、中文 UI 文案、中文剧情和注释不要擅自改成英文。
5. 如果项目文档不足以支持准确落地，应先补齐 `docs/` 下的 PRD/设计/技术文档，再进入编码。
6. BDD 场景要覆盖主要成功路径、关键失败路径、权限/登录态、边界条件和回归风险。

## 核心格式

推荐使用中文 Gherkin：

```gherkin
功能: <业务能力名称>
  为了 <用户/业务价值>
  作为 <角色>
  我希望 <能力>

  背景:
    假如 <所有场景共享的前置条件>

  场景: <具体行为名称>
    假如 <上下文/已有状态>
    当 <用户动作或系统事件>
    那么 <可观察结果>
    而且 <额外可观察结果>

  场景大纲: <带参数的行为名称>
    假如 <上下文中包含 <变量>>
    当 <动作>
    那么 <结果>

    例子:
      | 变量 | 期望 |
      | A    | X    |
      | B    | Y    |
```

英文关键字也可以使用：

```gherkin
Feature: Work publish permission
  Scenario: Anonymous user attempts to publish a draft
    Given an anonymous user has a generated draft
    When the user clicks publish
    Then the login modal should be shown
    And the draft should remain unchanged
```

在 Genarrative 项目内，若参与评审的人主要使用中文，优先中文场景；测试框架要求英文命名时，可以保留中文场景标题并在测试文件中使用英文 describe/it。

## 从需求提炼 BDD 场景

### Step 1: 识别角色和业务目标

先回答：

- 谁在使用？游客、已登录用户、创作者、管理员、审核人员、系统任务？
- 用户想完成什么？创建、生成、保存、发布、试玩、查看、兑换、导出？
- 业务价值是什么？降低创作门槛、保护权限、保证数据一致性、提升运营可见性？

### Step 2: 抽取领域词汇

建立统一术语，避免同一概念多种叫法：

- work / 作品
- draft / 草稿
- session / 创作会话
- runtime / 运行态
- publish / 发布
- profile / 我的页签
- invite code / 邀请码
- analytics event / 埋点事件

场景中优先使用业务词，不要直接写组件名、函数名、数据库表名，除非这些就是用户可见对象。

### Step 3: 列出行为切片

按用户旅程切分：

1. 入口是否出现、是否可点击。
2. 进入页面或工作台后的初始状态。
3. 用户提交输入后的成功路径。
4. 失败路径：未登录、参数无效、权限不足、网络/API 失败、异步任务失败。
5. 状态持久化：刷新、返回、重新进入、跨设备或重新登录。
6. 对外副作用：保存、发布、埋点、通知、导出、生成资产。
7. 回归风险：旧入口、旧数据、移动端布局、中文编码。

### Step 4: 把每个切片写成 Given / When / Then

检查每个场景：

- Given 只描述前置状态，不写动作过程。
- When 只描述一个主要触发动作或事件。
- Then 描述可观察结果，可以被测试或人工验收。
- 一个场景只验证一个核心行为；不要把完整长流程塞进一个巨型场景。

## Genarrative 场景模板

### 前端入口 / 页面行为

```gherkin
功能: 我的页签反馈入口
  为了让用户能从个人中心提交问题
  作为已登录用户
  我希望在我的页签打开独立的帮助与反馈页面

  场景: 已登录用户从我的页签进入反馈页面
    假如用户已登录并停留在我的页签
    当用户点击“帮助与反馈”入口
    那么系统应进入独立的反馈页面
    而且底部 tab 应保持选中“我的”
    而且页面不应展开在我的页签当前面板下方

  场景: 用户从反馈页面返回我的页签
    假如用户正在反馈页面
    当用户点击返回按钮
    那么系统应回到平台主页面
    而且当前 tab 应为“我的”
```

### 登录态 / 权限行为

```gherkin
功能: 需要登录的发布能力
  为了保护作品归属和发布链路
  作为游客
  我不能在未登录时发布作品

  场景: 游客尝试发布生成草稿
    假如游客已经生成一个草稿
    当游客点击发布按钮
    那么系统应打开登录弹窗
    而且不应创建正式作品
    而且草稿内容应保留在当前会话中
```

### 后端 API / 领域规则

```gherkin
功能: 作品正式游玩开始埋点
  为了统计不同玩法的正式游玩行为
  作为数据分析人员
  我希望每次用户进入正式作品运行态时记录统一事件

  场景大纲: 支持的玩法进入正式游玩
    假如存在一个已发布的 <玩法> 作品
    当用户从作品详情进入正式游玩
    那么后端应记录 work_play_start 事件
    而且 scope_kind 应为 work
    而且 metadata 应包含 playType、workId、sourceRoute 和 userId

    例子:
      | 玩法 |
      | puzzle |
      | match3d |
      | square-hole |
      | custom-world |
      | big-fish |
      | visual-novel |
```

### 异步生成 / SSE 行为

```gherkin
功能: AI 创作会话流式回复
  为了让用户看到生成进度
  作为创作者
  我希望提交创作指令后能收到流式反馈并最终得到可编辑草稿

  场景: 成功生成草稿
    假如用户已登录并创建了创作会话
    当用户提交有效的创作指令
    那么系统应开始展示流式回复
    而且生成结束后应展示草稿结果
    而且会话快照应包含最新用户输入和 AI 回复

  场景: 生成失败
    假如用户已登录并创建了创作会话
    当用户提交创作指令但后端生成失败
    那么系统应展示可理解的失败状态
    而且用户应能够重试
    而且不应覆盖上一次成功生成的草稿
```

## 映射到测试类型

| BDD 场景关注点 | 推荐测试层级 | 示例 |
| --- | --- | --- |
| 纯领域规则、状态机、校验 | Rust/TS 单元测试 | reducer、module-*、schema validator |
| DTO 契约、API 请求响应 | API/contract 测试 | Axum handler、shared-contracts serde |
| 页面渲染、按钮状态、表单校验 | 组件测试 | Vitest + Testing Library |
| 路由、tab、页面阶段切换 | 前端集成测试 | appPageRoutes、FlowShell 行为 |
| 登录态、发布、运行态完整链路 | E2E/smoke | Playwright 或项目 smoke 脚本 |
| 埋点、副作用、后台导出 | 后端集成/API 测试 | tracking event、admin export |

原则：

- 不是每个 BDD 场景都必须落成 E2E。
- 能在低层稳定验证的规则，不要强行放到脆弱的浏览器自动化里。
- E2E 只覆盖最关键的用户旅程和跨层集成风险。

## 与 TDD 的配合方式

BDD 先回答“行为是什么”，TDD 再推动“代码怎么长出来”。

推荐顺序：

1. 写 BDD 场景，确认业务行为和验收标准。
2. 给每个场景标注测试层级：unit / component / API / E2E。
3. 选择一个最小场景进入 TDD。
4. RED：先写失败测试，测试名称对应场景标题。
5. GREEN：实现最小代码让测试通过。
6. REFACTOR：清理重复、命名、边界和文档。
7. 回到下一个场景，直到主要路径和关键失败路径覆盖。

测试命名建议：

```ts
describe('帮助与反馈入口', () => {
  it('已登录用户从我的页签进入独立反馈页面', () => {
    // Given ...
    // When ...
    // Then ...
  })
})
```

Rust 测试命名建议：

```rust
#[test]
fn anonymous_user_cannot_publish_generated_draft() {
    // Given
    // When
    // Then
}
```

## 推荐产物

根据任务复杂度选择产物位置。使用本 skill 产出 Gherkin/BDD 场景时，必须先决定落点，不要把正式验收场景随手写在聊天记录里。

### Gherkin/BDD 场景默认落点

| 产物类型 | 推荐路径 | 适用场景 |
| --- | --- | --- |
| 实施前分析 / 临时计划 | `.hermes/plans/<task-name>-bdd-scenarios.md` | 某次 Hermes 开发任务前，用于澄清行为、拆测试、辅助实现；不一定作为长期产品依据。 |
| 正式产品验收 / PRD 场景 | `docs/prd/<FEATURE>_BDD_YYYY-MM-DD.md` | 产品、测试、开发都需要长期参考的验收标准、用户故事、功能边界。 |
| 技术/API/领域行为场景 | `docs/technical/<FEATURE>_BDD_YYYY-MM-DD.md` | 后端 API、领域规则、状态机、SpacetimeDB reducer/table、SSE/异步任务、埋点副作用。 |
| 自动化 Gherkin feature 文件 | `tests/features/*.feature` 或 `e2e/features/*.feature` | 项目已接入 Cucumber/Playwright BDD 等 Gherkin runner 时。未接入前不要随意新建测试 runner 目录。 |
| 稳定流程或团队经验 | `.hermes/shared-memory/` 或 `.hermes/skills/` | 不是某个功能验收，而是长期可复用的团队流程、坑点、执行规范。 |

默认规则：

1. 用户只说“先用 BDD 梳理一下/写场景/写 Gherkin”，默认写到 `.hermes/plans/<task-name>-bdd-scenarios.md`。
2. 用户说“正式验收标准/PRD/产品文档/给测试验收”，写到 `docs/prd/<FEATURE>_BDD_YYYY-MM-DD.md`。
3. 用户说“API 行为/后端规则/状态机/埋点/异步任务/SpacetimeDB”，写到 `docs/technical/<FEATURE>_BDD_YYYY-MM-DD.md`。
4. 用户明确要求“可执行 feature 文件”且项目已有 runner，再写 `.feature` 文件；否则先写 Markdown BDD 文档，并在测试映射中标注未来自动化落点。
5. 如果 BDD 场景会作为编码依据，文档中必须包含“测试映射”表，标注场景要落到哪些测试文件。

命名建议：

```text
.hermes/plans/profile-feedback-bdd-scenarios.md
docs/prd/PROFILE_FEEDBACK_BDD_2026-05-11.md
docs/technical/WORK_PLAY_TRACKING_BDD_2026-05-11.md
tests/features/profile-feedback.feature
e2e/features/invite-code.feature
```

### 其他配套产物

除 BDD/Gherkin 场景外，相关配套内容可放在：

- 实施计划：`.hermes/plans/<task-name>.md`
- 产品/验收文档：`docs/prd/<FEATURE>_PRD_YYYY-MM-DD.md`
- 技术设计：`docs/technical/<FEATURE>_TECHNICAL_YYYY-MM-DD.md`
- 共享经验或稳定流程：`.hermes/shared-memory/` 或 `.hermes/skills/`

BDD 文档建议包含：

```markdown
# <功能名> BDD 验收场景

## 背景
- 需求来源：
- 相关文档：
- 相关入口/接口：

## 角色与目标
- 角色：
- 目标：
- 非目标：

## 场景清单

### 功能: <能力>

```gherkin
场景: <场景名>
  假如 ...
  当 ...
  那么 ...
```

## 测试映射

| 场景 | 测试层级 | 目标文件 | 状态 |
| --- | --- | --- | --- |
| ... | component | ... | planned |

## 开放问题
- ...
```

注意：上面的 Markdown 模板中如果嵌套代码块，需要在真实文档里调整围栏长度，避免代码块提前闭合。

## 评审检查清单

- [ ] 每个场景都有清晰角色或业务上下文。
- [ ] Given / When / Then 没有混入过多实现细节。
- [ ] Then 都是可观察、可测试、可人工验收的结果。
- [ ] 覆盖成功路径、失败路径、权限/登录态、边界条件。
- [ ] 明确哪些场景需要自动化，哪些只需人工验收。
- [ ] 自动化测试层级合理，没有把所有行为都塞进 E2E。
- [ ] 中文文案、剧情、注释、文档没有被无意翻译或改写成英文。
- [ ] 涉及中文文件修改时计划运行编码检查。

## 常见坑

1. **把 BDD 写成 UI 操作流水账。** 例如“点击第一个按钮，再点第二个按钮”。应改为用户意图和业务结果。
2. **Then 不可验证。** “体验更顺滑”不是验收标准；要写成加载状态、错误提示、数据状态、页面阶段等可观察结果。
3. **一个场景塞太多断言。** 长流程应拆成多个小场景，避免失败时不知道真正坏在哪里。
4. **只写 happy path。** Genarrative 常见风险在登录态、刷新恢复、异步失败、端口/后端不可用、旧数据兼容和移动端布局。
5. **把实现方案当成业务规则。** “调用某函数”通常不是用户行为；除非是 API/技术验收，否则放到技术设计或测试实现里。
6. **BDD 和 TDD 脱节。** 写完场景后要映射测试层级和目标文件，否则场景容易停留在文档层。
7. **场景词汇不统一。** work、draft、session、runtime、publish 等概念要和项目现有文档/代码保持一致。
8. **忽略文档先行约束。** 若 PRD 不足以编码落地，先补文档，再开始工程修改。

## 验证与收口

执行 BDD 相关任务后，至少确认：

- [ ] 已产出或更新 BDD 场景文档/计划。
- [ ] 场景已映射到具体测试层级和目标文件。
- [ ] 若进入编码，已按 TDD 或等价方式先补测试。
- [ ] 已运行相关验证命令，例如：

```bash
npm run check:encoding
npm run typecheck
npm run test -- --run <相关测试文件>
```

- [ ] 若涉及后端 Rust/API，按相关 DDD/SpacetimeDB 文档运行对应 cargo/npm/API smoke 验证。
- [ ] 若产生长期有效经验，已同步到 `.hermes/shared-memory/` 或合适的仓库级 skill。