doc-bdd

doc-bdd

用途

创建 行为驱动开发（BDD） 场景——SDD 流程的第 4 层。BDD 套件将 EARS 正式需求转换为结构化的 YAML 场景（放在 ```yaml 代码块中的 Given/When/Then 阶段列表，而非 Gherkin @ 标签），每个场景都包含元素级 ears: 追踪列表，以及一个指向其所覆盖 SPEC 章节的 spec_trace 后续链接。（如果运行器需要 .feature 文件，YAML 是权威源文件，可按需编写 .feature 生成器——当前并未随项目提供此类生成器；唯一随项目提供的转码器是一次性反向转换工具 tools/gherkin_to_bdd_yaml.py，用于将旧版 Gherkin 迁移为 YAML 格式。）

层级：第 4 层。上游：EARS（遵循必要上游契约；上游 PRD/BRD 的溯源链可通过 @ 标签链传递追溯）。 下游：ADR → SPEC → TDD → IPLAN → Code。

BDD 场景是验收的事实来源，TDD（第 7 层）会将其映射为具体测试用例。仅限在 QA 暂存环境中执行——绝不要在 CI 中运行 BDD（CI 应使用 TDD 单元／集成测试）。

何时使用

在以下情况下使用 doc-bdd：

• EARS（第 3 层）已存在，且需要可执行的验收场景。
• 使用具体的 Given-When-Then 行为验证 EARS 需求。
• 在 ADR/SPEC 之前定义需求到 SPEC 的追踪桥接（spec_trace）。

如需从 EARS、提示词或 IPLAN 端到端生成，请使用 ../doc-bdd-autopilot/SKILL.md。先创建上游制品；绝不要编造诸如 EARS-XXX 的占位符，也不要引用尚不存在的文档。

前置条件

BDD 属于第 4 层，因此必需的上游 EARS 必须已存在。编写前请确认其存在并阅读规范：

1. 模板（事实来源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
2. 层级 README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
3. ID 与标签标准： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
4. 编写风格： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

验证上游文档并检查 ID 是否冲突： ls docs/03_EARS/ docs/04_BDD/ 2>/dev/null。追踪标签中只能引用现有的 EARS 元素；上游 PRD/BRD 的溯源链可通过 EARS 文档自身的 @ 标签链传递追溯。

层级指南

必需结构（5 个部分）

根据 BDD-TEMPLATE.yaml，每份 BDD 文档都包含：

1. 文档控制——版本、状态、日期、作者、优先级，以及 ADR 就绪度评分。（不设 @ears/@prd/@brd 引用行——上游追踪信息位于每个场景的 ears: 列表中。）
2. 功能定义——一个 ```yaml feature: 块：名称与 EARS 需求相匹配，包含 As a / I want / So that 描述，以及 background（纯步骤文本 + IANA 时区，默认为 America/New_York）。功能本身不包含 ears——其 EARS 覆盖范围由所有场景的并集构成。
3. 场景结构——一个 ```yaml scenarios: 扁平列表（Given/When/Then 阶段列表），每个场景都包含五种类别之一的 type:（见下文）。
4. 可追溯性——派生的覆盖摘要 + 下游预期，以及健康度／覆盖度评分。
5. 术语表——项目专用术语的扁平列表。

各部分的具体内容和规范性场景架构见 BDD-TEMPLATE.yaml。

场景类别（第 3 节）

每个场景都是一个 YAML 映射，包含 id: BDD.NN.03.xxxx、name、type、 priority（p0-critical … p3-low）、元素级 ears: 列表、given / when / then 阶段列表，以及 spec_trace 列表（notes 可选）。

类别	type: 值	最少数量	优先级
成功	success	1 / EARS	p0–p1
错误	error	1 / error	p1–p2
恢复	recovery	1 / circuit-breaker	p1
参数化	parameterized	1 / multi-value	p1–p2
可选	optional	1 / optional param	p2–p3

parameterized 场景会增加 outline: true + examples: {headers, rows}。

场景 YAML 规则

• 场景采用结构化 YAML，而非 Gherkin @ 标签。追踪信息使用 ears: 列表（仅限元素级——REFGRAN01 会拒绝文档级格式的 EARS-NN）； id/type/priority 是字段，而非标签。
• 时间包含秒（HH:MM:SS），并使用 IANA 时区（America/New_York）， 绝不使用 EST 等缩写。
• 定量值使用 @threshold: 键，并内联写在步骤描述中（例如 … WITHIN @threshold:PRD.NN.perf.api.p95）——不得使用魔法数字。
• 场景应保持原子性（每个场景只描述一种行为）。每个模块使用一份 BDD 文档， 最多约 50,000 个 token；超过此限后，另起一份独立完整的 BDD 文档。

元素 ID 和上游追踪

• 分层元素 ID：BDD.{doc_id}.{section_id}.{hash}（例如 BDD.01.03.d7a2）。为每个元素生成一个稳定的 4 位十六进制标识符，在其所在 小节内不得重复（HASH01）；发生冲突时扩展为 8 位。本提示中不要计算 SHA-256—— 哈希格式是由确定性工具流程生成的规范化目标，且字节精确的字段提取仅针对 BRD §7 定义（BDD 将在第 2 阶段及以后定义）。权威来源：framework/governance/ID_NAMING_STANDARDS.md。 场景位于第 03 节，记录在每个场景的 id: 字段中。
• BDD 必需的上游追踪信息是每个场景的元素级 ears: 列表 （依据必要上游契约，满足 required_tags: [ears]）。 下游产物使用 @bdd: BDD.01.03.8f4c 标签引用 BDD 场景 （保持不变）。上游 PRD/BRD 的关联关系可通过 EARS 文档自身的 @ 标签链 传递追溯；不要在 BDD 中添加 @brd:/@prd:/@ears 标签。
• 已移除的模式（请勿使用）：SCENARIO-XXX、SCEN-XXX、TS-XXX、 STEP-XXX、数字类型代码、旧版三段式 BDD.NN.xxxx，以及 Gherkin @ears/@scenario-type/@scenario-id 标签（现在改为 YAML 字段）。

下游追踪（spec_trace）

每个场景都会记录其映射到的 SPEC 章节，例如 spec_trace: ["SPEC Section 3 (Interfaces)", "SPEC Section 5 (Behavior)"]。 这是需求到 SPEC 的桥接信息，供下游层级使用。

创建流程

1. 阅读上游文档 — 阅读驱动此 BDD 的 EARS（以及通过其 @ 标签链派生出的 PRD/BRD），以了解要测试的行为。
2. 预留 ID — 使用下一个空闲的 BDD-NN（两位数字，不额外添加前导零：BDD-01、BDD-99、BDD-102）。 按层独立（CLEANUP-PR-F 第 18 项）： 在你所在层的索引中选择下一个空闲编号 — 上游文档的编号不是你的编号（文档编号按层依次递增且彼此独立；请参阅 framework/governance/ID_NAMING_STANDARDS.md §跨层基数）。
3. 从模板创建文档：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml；填写全部 5 个章节，并将 Document Control 放在首位。
4. 编写 feature: 块和 scenarios: 列表（YAML），依据 EARS 需求覆盖五个类别；每个场景都包含 id、type、priority、元素级 ears: 列表、given/when/then 阶段列表、内联 @threshold:，以及 spec_trace。添加 feature background。
5. 为每个场景设置元素级 ears: 列表（这是必需的上游追溯），并设置唯一的 id: — 不使用 Gherkin @ 标签。
6. 在同一项变更中更新 BDD 索引 docs/04_BDD/BDD-00_index.md。
7. 验证（见下文），并将 BDD 与索引一并提交。

验证

此技能即为验证器（无运行时代码）。依据 ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md 和 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md 进行验证。

• Document Control 是第一个章节；全部 5 个章节均存在且非空。
• 每个场景都包含元素级 ears: 列表（满足必要的上游契约）；feature 不得包含 ears。
• 每个场景都有 id、type、priority、given/when/then 阶段列表，以及 spec_trace（符合 BDD-SCHEMA-001）。
• 五种场景 type 类别均有体现；场景均为原子场景。
• 定量值使用内联 @threshold: 键；时间采用带 IANA 时区的 HH:MM:SS 格式。
• 元素 ID 符合 BDD.NN.SS.xxxx；不得使用已移除的模式或 Gherkin 标签。
• 已更新可追溯性章节/索引；没有失效链接。
• 图表契约：如果用图示说明场景流程，则必须包含 sequence-diagram 标签（使用 ../charts-flow/SKILL.md）。

错误代码（严重级别均为 error）：XDOC-006 标签格式无效 · XDOC-008 内部链接失效 · XDOC-009 缺少可追溯性章节。

质量门禁（阻塞性）： ADR-Ready 评分达到 90/100 或以上后才能继续。如果发现问题，先修复并重新检查；如果无法修复，则记录下来以供人工审核。

下一项技能

../doc-adr/SKILL.md — ADR 会引用此 BDD（@bdd: BDD.NN.SS.xxxx）及其必需的 @ears，采用 Context-Decision-Consequences 格式记录架构决策，并引用用于验证每项决策的 BDD 场景。

适配

读取 .aidoc/profile.yaml；仅遵循此技能的可配置项（section_toggles、glossary）。忽略未知键；若没有配置文件，则使用框架默认值。规范来源： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 模板 / 编写规则：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
• 层级 README：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
• 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-00_index.TEMPLATE.md
• ID 和标签标准：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• 质量门禁：../doc-bdd-audit/SKILL.md · 修复：../doc-bdd-fixer/SKILL.md
• 生成流水线：../doc-bdd-autopilot/SKILL.md

快速参考

用途	结构化的 YAML Given/When/Then 验收场景
层级	4
上游追溯	场景 ears: 列表（遵循必要上游契约）
核心理念	EARS → 带有指向 SPEC 的 spec_trace 的 YAML 场景
必须包含	文档控制（置于首位）、5 类场景、阈值
执行	仅限 QA 预发布环境——绝不用于 CI
下一步	doc-adr