--- 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/-bdd-scenarios.md` | 某次 Hermes 开发任务前，用于澄清行为、拆测试、辅助实现；不一定作为长期产品依据。 | | 正式产品验收 / PRD 场景 | `docs/prd/_BDD_YYYY-MM-DD.md` | 产品、测试、开发都需要长期参考的验收标准、用户故事、功能边界。 | | 技术/API/领域行为场景 | `docs/technical/_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/-bdd-scenarios.md`。 2. 用户说“正式验收标准/PRD/产品文档/给测试验收”，写到 `docs/prd/_BDD_YYYY-MM-DD.md`。 3. 用户说“API 行为/后端规则/状态机/埋点/异步任务/SpacetimeDB”，写到 `docs/technical/_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/.md` - 产品/验收文档：`docs/prd/_PRD_YYYY-MM-DD.md` - 技术设计：`docs/technical/_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。