Back to Details

doc-bdd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-bdd

doc-bdd

Purpose

目的

Create BDD (Behavior-Driven Development) test scenarios - Layer 4 artifact in the SDD workflow that defines executable test scenarios using Gherkin syntax.
Layer: 4
Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3)
Downstream: ADR (Layer 5), SYS (Layer 6), REQ (Layer 7)
创建**BDD（行为驱动开发）**测试场景——SDD工作流中的第4层工件，使用Gherkin语法定义可执行测试场景。
层级：4
上游：BRD（第1层）、PRD（第2层）、EARS（第3层）
下游：ADR（第5层）、SYS（第6层）、REQ（第7层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ 2>/dev/null
  2. Reference only existing documents in traceability tags
  3. Use 
    null
     only when upstream artifact type genuinely doesn't exist
  4. NEVER use placeholders like 
    BRD-XXX
    or 
    TBD
  5. Do NOT create missing upstream artifacts - skip functionality instead
Before creating BDD, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream BRD, PRD, EARS: Read artifacts that drive these test scenarios
  3. Template: 
    ai_dev_flow/04_BDD/BDD-SECTION-TEMPLATE.feature
  4. Creation Rules: 
    ai_dev_flow/04_BDD/BDD_CREATION_RULES.md
  5. Validation Rules: 
    ai_dev_flow/04_BDD/BDD_VALIDATION_RULES.md
  6. Splitting Rules: 
    ai_dev_flow/04_BDD/BDD_SPLITTING_RULES.md
在创建本文档之前，你必须：
  1. 列出已有的上游工件：
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ 2>/dev/null
  2. 在可追溯性标签中仅引用已存在的文档
  3. 仅当上游工件类型确实不存在时才使用
    null
  4. 绝不使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——跳过对应的功能即可
在创建BDD之前，请阅读：
  1. 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游BRD、PRD、EARS：阅读驱动这些测试场景的工件
  3. 模板：
    ai_dev_flow/04_BDD/BDD-SECTION-TEMPLATE.feature
  4. 创建规则：
    ai_dev_flow/04_BDD/BDD_CREATION_RULES.md
  5. 验证规则：
    ai_dev_flow/04_BDD/BDD_VALIDATION_RULES.md
  6. 拆分规则：
    ai_dev_flow/04_BDD/BDD_SPLITTING_RULES.md

When to Use This Skill

何时使用该技能

Use 
doc-bdd
when:
  • Have completed BRD (Layer 1), PRD (Layer 2), EARS (Layer 3)
  • Need to define executable test scenarios
  • Validating EARS formal requirements with Given-When-Then format
  • Creating acceptance criteria for features
  • You are at Layer 4 of the SDD workflow
在以下场景使用
doc-bdd
：
  • 已完成BRD（第1层）、PRD（第2层）、EARS（第3层）
  • 需要定义可执行测试场景
  • 使用Given-When-Then格式验证EARS正式需求
  • 为功能创建验收标准
  • 处于SDD工作流的第4层

Section-Based Structure (MANDATORY)

基于章节的结构（强制要求）

All BDD suites MUST use section-based structure. No backward compatibility with legacy formats.
所有BDD套件必须使用基于章节的结构，不兼容旧版格式。

Directory Structure

目录结构

Nested Folder Rule (MANDATORY): ALL BDD suites MUST use nested folders regardless of size.
docs/04_BDD/
├── BDD-02_knowledge_engine/           # Suite folder (REQUIRED)
│   ├── BDD-02.0_index.md              # Index file (MANDATORY)
│   ├── BDD-02.1_ingest.feature        # Section 1
│   ├── BDD-02.2_query.feature         # Section 2
│   ├── BDD-02.3.00_learning.feature   # Aggregator (if 5+ subsections)
│   ├── BDD-02.3.01_learning_path.feature    # Subsection 1
│   ├── BDD-02.3.02_bias_detection.feature   # Subsection 2
│   ├── BDD-02_README.md               # Optional companion
│   └── BDD-02_TRACEABILITY.md         # Optional companion
└── BDD-02_knowledge_engine.feature    # Redirect stub (0 scenarios)
CRITICAL: Never create BDD files directly in 
docs/04_BDD/
without a nested folder structure.
嵌套文件夹规则（强制要求）：所有BDD套件无论规模大小，都必须使用嵌套文件夹。
docs/04_BDD/
├── BDD-02_knowledge_engine/           # 套件文件夹（必填）
│   ├── BDD-02.0_index.md              # 索引文件（必填）
│   ├── BDD-02.1_ingest.feature        # 章节1
│   ├── BDD-02.2_query.feature         # 章节2
│   ├── BDD-02.3.00_learning.feature   # 聚合器（当子章节≥5个时使用）
│   ├── BDD-02.3.01_learning_path.feature    # 子章节1
│   ├── BDD-02.3.02_bias_detection.feature   # 子章节2
│   ├── BDD-02_README.md               # 可选配套文档
│   └── BDD-02_TRACEABILITY.md         # 可选配套文档
└── BDD-02_knowledge_engine.feature    # 重定向存根（0个场景）
关键注意事项：绝不要在
docs/04_BDD/
下直接创建BDD文件，必须使用嵌套文件夹结构。

Three Valid File Patterns (ONLY)

三种有效文件模式（仅允许）

PatternExampleUse When
Section-Only
BDD-02.14_query_result_filtering.feature
Standard section (≤500 lines, ≤12 scenarios)
Subsection
BDD-02.24.01_quality_performance.feature
Section requires splitting
Aggregator
BDD-02.12.00_query_graph_traversal.feature
Organizing multiple subsections (@redirect, 0 scenarios)
模式示例使用场景
仅章节
BDD-02.14_query_result_filtering.feature
标准章节（≤500行，≤12个场景）
子章节
BDD-02.24.01_quality_performance.feature
章节需要拆分时
聚合器
BDD-02.12.00_query_graph_traversal.feature
组织多个子章节（@redirect，0个场景）

Prohibited Patterns (ERROR)

禁止模式（错误）

PatternExampleFix
_partN suffix
BDD-02_query_part1.feature
Use 
BDD-02.2.01_query.feature
Single-file
BDD-02_knowledge_engine.feature
(with scenarios)		Use section-based format
features/ subdirectory
BDD-02_slug/features/
Put 
.feature
files at suite folder root
模式示例修复方案
_partN后缀
BDD-02_query_part1.feature
使用
BDD-02.2.01_query.feature
单文件
BDD-02_knowledge_engine.feature
（包含场景）		使用基于章节的格式
features/子目录
BDD-02_slug/features/
将.feature文件放在套件文件夹根目录

Critical Rules

关键规则

  1. All 
    .feature
    files in suite folder     - No 
    features/
    subdirectory
  2. Index file mandatory: 
    BDD-NN.0_index.md
    for all suites
  3. Max 500 lines per 
    .feature
    file (soft limit: 400)
  4. Max 12 scenarios per Feature block
  5. Section metadata tags required: 
    @section
    , 
    @parent_doc
    , 
    @index
  1. 所有.feature文件必须在套件文件夹中——禁止使用
    features/
    子目录
  2. 索引文件是必填项：所有套件都需要
    BDD-NN.0_index.md
  3. 每个.feature文件最多500行（软限制：400行）
  4. 每个Feature块最多12个场景
  5. 必须包含章节元数据标签：
    @section
    、
    @parent_doc
    、
    @index

Gherkin Syntax

Gherkin语法

Feature File Structure

特性文件结构

gherkin
undefined
gherkin
undefined

Traceability Tags (Gherkin-native, NOT in comments)

可追溯性标签（Gherkin原生标签，请勿放在注释中）

@section: 2.14 @parent_doc: BDD-02 @index: BDD-02.0_index.md @brd:BRD.02.01.03 @prd:PRD.02.07.02 @ears:EARS.02.14.01
Feature: BDD-02.14: Query Result Filtering As a data analyst I want filtered query results So that I can focus on relevant data
Background: Given the system timezone is "America/New_York" And the current time is "09:30:00" in "America/New_York"
@primary @functional Scenario: Successful filter application Given valid filter criteria When user applies filter Then filtered results are returned And response time is less than @threshold:PRD.02.perf.api.p95_latency
undefined
@section: 2.14 @parent_doc: BDD-02 @index: BDD-02.0_index.md @brd:BRD.02.01.03 @prd:PRD.02.07.02 @ears:EARS.02.14.01
Feature: BDD-02.14: 查询结果过滤 作为一名数据分析师 我希望获得经过过滤的查询结果 以便我可以专注于相关数据
Background: Given 系统时区为 "America/New_York" And 当前时间为 "09:30:00"（时区："America/New_York"）
@primary @functional Scenario: 成功应用过滤器 Given 存在有效的过滤条件 When 用户应用过滤器 Then 返回过滤后的结果 And 响应时间小于 @threshold:PRD.02.perf.api.p95_latency
undefined

Tags Placement (CRITICAL - E041)

标签位置（关键 - E041）

Tags MUST be Gherkin-native, NOT in comments.
gherkin
undefined
标签必须是Gherkin原生标签，请勿放在注释中。
gherkin
undefined

INVALID (frameworks cannot parse comment-based tags):

无效（框架无法解析注释中的标签）：

@brd: BRD.01.01.01

@brd: BRD.01.01.01

@prd: PRD.01.01.01

@prd: PRD.01.01.01

Feature: My Feature
Feature: 我的特性

VALID (Gherkin-native tags before Feature):

有效（Gherkin原生标签放在Feature之前）：

@brd:BRD.01.01.01 @prd:PRD.01.01.01 @ears:EARS.01.24.01 Feature: My Feature
undefined
@brd:BRD.01.01.01 @prd:PRD.01.01.01 @ears:EARS.01.24.01 Feature: 我的特性
undefined

Times and Timezones (MANDATORY)

时间与时区（强制要求）

  • All times include seconds: 
    HH:MM:SS
  • Use IANA timezone format: 
    America/New_York
    , 
    America/Los_Angeles
  • Avoid ambiguous abbreviations (EST/EDT/PST/PDT)
gherkin
Given the current time is "14:30:00" in "America/New_York"
And the system timezone is "America/New_York"
  • 所有时间必须包含秒：
    HH:MM:SS
  • 使用IANA时区格式：
    America/New_York
    、
    America/Los_Angeles
  • 避免使用模糊的缩写（EST/EDT/PST/PDT）
gherkin
Given 当前时间为 "14:30:00"（时区："America/New_York"）
And 系统时区为 "America/New_York"

Unified Element ID Format (MANDATORY)

统一元素ID格式（强制要求）

Pattern: 
BDD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeExample
Test Scenario14BDD.02.14.01
Step15BDD.02.15.01
REMOVED PATTERNS - Do NOT use:
  • SCENARIO-XXX
    , 
    TS-XXX
    → Use 
    BDD.NN.14.SS
  • STEP-XXX
    → Use 
    BDD.NN.15.SS
  • TC-XXX
    → Use 
    BDD.NN.14.SS
格式：
BDD.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，用点分隔）
元素类型代码示例
测试场景14BDD.02.14.01
步骤15BDD.02.15.01
已废弃格式 - 请勿使用：
  • SCENARIO-XXX
    、
    TS-XXX
    → 请使用
    BDD.NN.14.SS
  • STEP-XXX
    → 请使用
    BDD.NN.15.SS
  • TC-XXX
    → 请使用
    BDD.NN.14.SS

ADR-Ready Scoring System

ADR就绪评分系统

Purpose: Measures BDD maturity and readiness for ADR progression.
Format in Document Control:
markdown
| **ADR-Ready Score** | ✅ 95% (Target: ≥90%) |
目的：衡量BDD的成熟度和进入ADR阶段的就绪程度。
文档控制中的格式：
markdown
| **ADR就绪评分** | ✅ 95%（目标：≥90%） |

Status and ADR-Ready Score Mapping

状态与ADR就绪评分映射

ADR-Ready ScoreRequired Status
≥90%Approved
70-89%In Review
<70%Draft
ADR就绪评分要求状态
≥90%已批准
70-89%审核中
<70%草稿

Scoring Criteria

评分标准

Scenario Completeness (35%):
  • All EARS statements translated to BDD scenarios: 15%
  • Comprehensive coverage (success/error/edge): 15%
  • Observable verification methods specified: 5%
Testability (30%):
  • Scenarios are automatable: 15%
  • Data-driven Examples tables used: 10%
  • Performance benchmarks quantifiable: 5%
Architecture Requirements Clarity (25%):
  • Performance, security, scalability quality attributes specified: 15%
  • Integration points and external dependencies defined: 10%
Business Validation (10%):
  • Business acceptance criteria traceable: 5%
  • Measurable success outcomes defined: 5%
Quality Gate: Score <90% blocks ADR artifact creation.
场景完整性（35%）：
  • 所有EARS语句已转换为BDD场景：15%
  • 覆盖全面（成功/错误/边缘场景）：15%
  • 指定了可观察的验证方法：5%
可测试性（30%）：
  • 场景可自动化：15%
  • 使用了数据驱动的Examples表格：10%
  • 性能基准可量化：5%
架构需求清晰度（25%）：
  • 指定了性能、安全、可扩展性等质量属性：15%
  • 定义了集成点和外部依赖：10%
业务验证（10%）：
  • 业务验收标准可追溯：5%
  • 定义了可衡量的成功结果：5%
质量门：评分<90%将阻止ADR工件的创建。

Threshold Registry Integration (MANDATORY)

阈值注册表集成（强制要求）

All quantitative values MUST use 
@threshold:
keys. No hardcoded magic numbers.
所有定量值必须使用
@threshold:
键，禁止使用硬编码的魔法数字。

Inline Step Format

内联步骤格式

gherkin
undefined
gherkin
undefined

INVALID (hardcoded):

无效（硬编码）：

Then response time is less than 200ms
Then 响应时间小于200ms

VALID (threshold reference):

有效（引用阈值）：

Then response time is less than @threshold:PRD.035.perf.api.p95_latency
undefined
Then 响应时间小于 @threshold:PRD.035.perf.api.p95_latency
undefined

Scenario Tag Format

场景标签格式

gherkin
@threshold:PRD.NN.perf.api.p95_latency
Scenario: API responds within performance threshold
gherkin
@threshold:PRD.NN.perf.api.p95_latency
Scenario: API在性能阈值内响应

Common Threshold Categories

常见阈值类别

CategoryBDD UsageExample Key
perf.*
Performance validation
perf.api.p95_latency
sla.*
SLA validation
sla.uptime.target
limit.*
Rate limit testing
limit.api.requests_per_second
timeout.*
Timeout validation
timeout.request.sync
类别BDD用法示例键
perf.*
性能验证
perf.api.p95_latency
sla.*
SLA验证
sla.uptime.target
limit.*
速率限制测试
limit.api.requests_per_second
timeout.*
超时验证
timeout.request.sync

Cumulative Tagging Requirements

累积标签要求

Layer 4 (BDD): Must include tags from Layers 1-3 (BRD, PRD, EARS)
Tag Count: 3+ tags (@brd, @prd, @ears)
Format (Gherkin-native tags before Feature):
gherkin
@brd:BRD.01.01.03
@prd:PRD.01.07.02
@ears:EARS.01.24.01
Feature: Feature Name
第4层（BDD）：必须包含第1-3层的标签（BRD、PRD、EARS）
标签数量：至少3个标签（@brd、@prd、@ears）
格式（Gherkin原生标签放在Feature之前）：
gherkin
@brd:BRD.01.01.03
@prd:PRD.01.07.02
@ears:EARS.01.24.01
Feature: 特性名称

Tag Format Convention

标签格式约定

NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - document references
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQHierarchical artifacts - element references
符号格式工件用途
短横线TYPE-NNADR、SPEC、CTR技术工件 - 文档引用
点TYPE.NN.TT.SSBRD、PRD、EARS、BDD、SYS、REQ分层工件 - 元素引用

Scenario Types

场景类型

All 8 categories should be represented:
CategoryTagDescription
Success Path
@primary
Happy path scenarios
Alternative Path
@alternative
Optional parameters, different workflows
Error Conditions
@negative
Invalid inputs, error handling
Edge Cases
@edge_case
, 
@boundary
Boundary conditions, limits
Data-Driven
@data_driven
Parameterized with Examples tables
Integration
@integration
External system interactions
Quality Attributes
@quality_attribute
Performance, security, reliability
Failure Recovery
@failure_recovery
Error recovery, circuit breakers
应覆盖全部8个类别：
类别标签描述
成功路径
@primary
正常流程场景
备选路径
@alternative
可选参数、不同工作流
错误条件
@negative
无效输入、错误处理
边缘场景
@edge_case
、
@boundary
边界条件、限制值
数据驱动
@data_driven
使用Examples表格参数化
集成场景
@integration
外部系统交互
质量属性
@quality_attribute
性能、安全、可靠性
故障恢复
@failure_recovery
错误恢复、断路器

Success Path Example

成功路径示例

gherkin
@primary @functional
Scenario: User logs in successfully
  Given valid credentials
  When user submits login
  Then user is authenticated
gherkin
@primary @functional
Scenario: 用户成功登录
  Given 存在有效凭据
  When 用户提交登录请求
  Then 用户通过认证

Error Conditions Example

错误条件示例

gherkin
@negative @error_handling
Scenario: Trade rejected due to insufficient funds
  Given account balance is $1000
  When trade requires $5000
  Then trade is rejected
  And error code "INSUFFICIENT_FUNDS" is returned
gherkin
@negative @error_handling
Scenario: 因资金不足拒绝交易
  Given 账户余额为$1000
  When 交易需要$5000
  Then 交易被拒绝
  And 返回错误码 "INSUFFICIENT_FUNDS"

Edge Cases Example

边缘场景示例

gherkin
@edge_case @boundary
Scenario: Trade at exact position limit
  Given current delta is 0.499
  And position limit is 0.50
  When trade increases delta to 0.50
  Then trade is accepted
gherkin
@edge_case @boundary
Scenario: 达到精确仓位限制的交易
  Given 当前delta为0.499
  And 仓位限制为0.50
  When 交易将delta增加至0.50
  Then 交易被接受

Data-Driven Example

数据驱动示例

gherkin
@data_driven
Scenario Outline: Validate price precision
  Given instrument <symbol>
  When price is <price>
  Then precision should be <decimals> decimal places
  Examples:
    | symbol | price  | decimals |
    | SPY    | 450.25 | 2        |
    | AMZN   | 3250.5 | 1        |
gherkin
@data_driven
Scenario Outline: 验证价格精度
  Given 工具为<symbol>
  When 价格为<price>
  Then 精度应为<decimals>位小数
  Examples:
    | symbol | price  | decimals |
    | SPY    | 450.25 | 2        |
    | AMZN   | 3250.5 | 1        |

Section Metadata Requirements

章节元数据要求

All 
.feature
files MUST include section metadata tags:
gherkin
@section: NN.SS              # Section number (e.g., 2.1, 2.14)
@parent_doc: BDD-NN          # Parent BDD suite (e.g., BDD-02)
@index: BDD-NN.0_index.md    # Index file reference
@brd:BRD.NN.EE.SS            # Upstream BRD element
@prd:PRD.NN.EE.SS            # Upstream PRD element
@ears:EARS.NN.SS.RR          # Upstream EARS requirement
For subsections, add:
gherkin
@parent_section: NN.SS       # Parent section number
Feature Title Format:
gherkin
Feature: BDD-NN.SS: Domain Description
所有.feature文件必须包含章节元数据标签：
gherkin
@section: NN.SS              # 章节编号（例如：2.1、2.14）
@parent_doc: BDD-NN          # 父BDD套件（例如：BDD-02）
@index: BDD-NN.0_index.md    # 索引文件引用
@brd:BRD.NN.EE.SS            # 上游BRD元素
@prd:PRD.NN.EE.SS            # 上游PRD元素
@ears:EARS.NN.SS.RR          # 上游EARS需求
对于子章节，需添加：
gherkin
@parent_section: NN.SS       # 父章节编号
特性标题格式：
gherkin
Feature: BDD-NN.SS: 领域描述

Aggregator Files

聚合器文件

Use when: Section has 5+ subsections
Requirements:
  • @redirect
    tag MUST be present
  • 0 scenarios (redirect stub only)
  • List subsections in Feature description
gherkin
@redirect
@section: 2.12.00
@parent_doc: BDD-02
@index: BDD-02.0_index.md

Feature: BDD-02.12: Query Graph Traversal (Aggregator)

  This is a redirect stub. Test scenarios are in subsections:
  - BDD-02.12.01_depth_first.feature - Depth-first traversal tests
  - BDD-02.12.02_breadth_first.feature - Breadth-first traversal tests

Background:
  Given the system timezone is "America/New_York"
  # No scenarios in aggregator - redirect only
使用场景：章节包含5个以上子章节时
要求：
  • 必须包含
    @redirect
    标签
  • 0个场景（仅作为重定向存根）
  • 在Feature描述中列出所有子章节
gherkin
@redirect
@section: 2.12.00
@parent_doc: BDD-02
@index: BDD-02.0_index.md

Feature: BDD-02.12: 查询图遍历（聚合器）

  这是一个重定向存根，测试场景位于以下子章节：
  - BDD-02.12.01_depth_first.feature - 深度优先遍历测试
  - BDD-02.12.02_breadth_first.feature - 广度优先遍历测试

Background:
  Given 系统时区为 "America/New_York"
  # 聚合器中无场景 - 仅用于重定向

Index File Template

索引文件模板

Mandatory: 
BDD-NN.0_index.md
for each suite
markdown
undefined
必填：每个套件都需要
BDD-NN.0_index.md
markdown
undefined

BDD-02.0: Knowledge Engine Test Suite Index

BDD-02.0: 知识引擎测试套件索引

Suite Overview

套件概述

Purpose: Test scenarios for Knowledge Engine functionality Scope: Ingest, Query, Learning, Performance Monitoring
目的：知识引擎功能的测试场景 范围：数据摄入、查询、学习、性能监控

Section File Map

章节文件映射

SectionFileScenariosLinesStatusDescription
02.1BDD-02.1_ingest.feature8350ActiveIngest tests
02.2BDD-02.2_query.feature10420ActiveQuery tests
章节文件场景数行数状态描述
02.1BDD-02.1_ingest.feature8350活跃数据摄入测试
02.2BDD-02.2_query.feature10420活跃查询测试

Traceability Matrix

可追溯性矩阵

BDD SectionUpstream SourceDescription
BDD-02.1EARS.02.01-05Ingest requirements
BDD-02.2EARS.02.06-12Query requirements
undefined
BDD章节上游来源描述
BDD-02.1EARS.02.01-05数据摄入需求
BDD-02.2EARS.02.06-12查询需求
undefined

Creation Process

创建流程

Step 1: Read Upstream Artifacts

步骤1：阅读上游工件

Read BRD, PRD, and EARS to understand requirements to test.
阅读BRD、PRD和EARS，了解需要测试的需求。

Step 2: Reserve Suite ID

步骤2：预留套件ID

Check 
docs/04_BDD/
for next available ID (e.g., BDD-01, BDD-02).
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • ✅ Correct: BDD-01, BDD-99, BDD-102
  • ❌ Incorrect: BDD-001, BDD-009 (extra leading zero not required)
检查
docs/04_BDD/
获取下一个可用ID（例如：BDD-01、BDD-02）。
ID编号约定：从2位数字开始，仅在需要时扩展。
  • ✅ 正确：BDD-01、BDD-99、BDD-102
  • ❌ 错误：BDD-001、BDD-009（不需要额外前导零）

Step 3: Create Suite Folder

步骤3：创建套件文件夹

bash
mkdir -p docs/04_BDD/BDD-02_knowledge_engine/
bash
mkdir -p docs/04_BDD/BDD-02_knowledge_engine/

Step 4: Create Index File

步骤4：创建索引文件

bash
cp ai_dev_flow/04_BDD/BDD-SECTION-0-TEMPLATE.md docs/04_BDD/BDD-02_knowledge_engine/BDD-02.0_index.md
bash
cp ai_dev_flow/04_BDD/BDD-SECTION-0-TEMPLATE.md docs/04_BDD/BDD-02_knowledge_engine/BDD-02.0_index.md

Step 5: Design Section Split

步骤5：设计章节拆分

  • Identify logical domains or EARS groupings
  • Estimate scenarios per section (target: 6-10)
  • Plan for subsections if needed (>500 lines)
  • 识别逻辑领域或EARS分组
  • 估算每个章节的场景数（目标：6-10个）
  • 若需要（超过500行），规划子章节

Step 6: Create Section Files

步骤6：创建章节文件

bash
cp ai_dev_flow/04_BDD/BDD-SECTION-TEMPLATE.feature docs/04_BDD/BDD-02_knowledge_engine/BDD-02.1_ingest.feature
bash
cp ai_dev_flow/04_BDD/BDD-SECTION-TEMPLATE.feature docs/04_BDD/BDD-02_knowledge_engine/BDD-02.1_ingest.feature

Step 7: Add Section Metadata Tags

步骤7：添加章节元数据标签

  • @section
    , 
    @parent_doc
    , 
    @index
  • Upstream traceability: 
    @brd
    , 
    @prd
    , 
    @ears
  • @section
    、
    @parent_doc
    、
    @index
  • 上游可追溯性标签：
    @brd
    、
    @prd
    、
    @ears

Step 8: Write Scenarios

步骤8：编写场景

For each requirement from EARS/PRD:
  1. Success path scenario
  2. Error condition scenarios (2-3)
  3. Edge case scenarios (1-2)
  4. Scenario outlines for parameterized tests
针对EARS/PRD中的每个需求：
  1. 成功路径场景
  2. 错误条件场景（2-3个）
  3. 边缘场景（1-2个）
  4. 用于参数化测试的Scenario Outline

Step 9: Replace Magic Numbers with Thresholds

步骤9：用阈值替换魔法数字

  • Add to PRD threshold registry first if key missing
  • Use 
    @threshold:PRD.NN.category.key
    format
  • 若键不存在，先添加到PRD阈值注册表
  • 使用
    @threshold:PRD.NN.category.key
    格式

Step 10: Create Redirect Stub

步骤10：创建重定向存根

bash
undefined
bash
undefined

Create redirect stub at docs/04_BDD/ root

在docs/04_BDD/根目录创建重定向存根

touch docs/04_BDD/BDD-02_knowledge_engine.feature

Add minimal content with `@redirect` tag and 0 scenarios.
touch docs/04_BDD/BDD-02_knowledge_engine.feature

添加包含`@redirect`标签的最小内容，且0个场景。

Step 11: Update Index File

步骤11：更新索引文件

  • List all section files with scenario counts
  • Add traceability matrix
  • 列出所有章节文件及场景数
  • 添加可追溯性矩阵

Step 12: Validate BDD Suite

步骤12：验证BDD套件

bash
python3 scripts/validate_bdd_suite.py --root BDD
bash
python3 scripts/validate_bdd_suite.py --root BDD

Step 13: Commit Changes

步骤13：提交变更

Commit suite folder and redirect stub together.
将套件文件夹和重定向存根一起提交。

Validation

验证

Validation Error Codes Reference

验证错误码参考

CodeDescriptionSeverity
E001Document Control fields missingERROR
E002Gherkin syntax invalidERROR
E003ADR-Ready Score format invalidERROR
E004Upstream traceability tags missingERROR
E041Tags in comments (not Gherkin-native)ERROR
E008Element ID format invalidERROR
CHECK 9.1File naming pattern invalidERROR
CHECK 9.2Prohibited pattern detectedERROR
CHECK 9.3Aggregator requirements not metERROR
CHECK 9.4File size exceeds limitsERROR
CHECK 9.5Section metadata tags missingERROR
CHECK 9.6Index file missingERROR
CHECK 9.7Non-Gherkin content in .feature fileERROR
代码描述严重程度
E001缺失文档控制字段错误
E002Gherkin语法无效错误
E003ADR就绪评分格式无效错误
E004缺失上游可追溯性标签错误
E041标签放在注释中（非Gherkin原生）错误
E008元素ID格式无效错误
CHECK 9.1文件命名模式无效错误
CHECK 9.2检测到禁止模式错误
CHECK 9.3未满足聚合器要求错误
CHECK 9.4文件大小超过限制错误
CHECK 9.5缺失章节元数据标签错误
CHECK 9.6缺失索引文件错误
CHECK 9.7.feature文件中包含非Gherkin内容错误

Manual Checklist

手动检查清单

File Structure:
  • All 
    .feature
    files in suite folder (no 
    features/
    subdirectory)
  • Index file exists: 
    BDD-NN.0_index.md
  • Redirect stub at 
    docs/BDD/BDD-NN_slug.feature
    (0 scenarios)
  • No file exceeds 500 lines
  • No Feature block exceeds 12 scenarios
File Naming:
  • All files match one of 3 valid patterns
  • No prohibited patterns (_partN, single-file)
Tags and Metadata:
  • Tags are Gherkin-native (NOT in comments)
  • Section metadata: 
    @section
    , 
    @parent_doc
    , 
    @index
  • Cumulative tags: 
    @brd
    , 
    @prd
    , 
    @ears
  • All quantitative values use 
    @threshold:
    keys
  • Times include seconds (HH:MM:SS) with IANA timezone
Scenarios:
  • All 8 scenario categories represented
  • Given-When-Then structure
  • No subjective language ("fast", "reliable")
  • Observable outcomes in Then steps
Aggregators (if applicable):
  • Has 
    @redirect
    tag
  • Has 0 scenarios
  • Lists subsections in Feature description
文件结构：
  • 所有.feature文件都在套件文件夹中（无
    features/
    子目录）
  • 存在索引文件：
    BDD-NN.0_index.md
  • 在
    docs/BDD/BDD-NN_slug.feature
    存在重定向存根（0个场景）
  • 无文件超过500行
  • 无Feature块超过12个场景
文件命名：
  • 所有文件匹配三种有效模式之一
  • 无禁止模式（_partN、单文件）
标签与元数据：
  • 标签是Gherkin原生标签（不在注释中）
  • 包含章节元数据：
    @section
    、
    @parent_doc
    、
    @index
  • 包含累积标签：
    @brd
    、
    @prd
    、
    @ears
  • 所有定量值使用
    @threshold:
    键
  • 时间包含秒（HH:MM:SS）并使用IANA时区
场景:
  • 覆盖全部8种场景类别
  • 采用Given-When-Then结构
  • 无主观语言（如“快速”、“可靠”）
  • Then步骤中包含可观察的结果
聚合器（如适用）：
  • 包含
    @redirect
    标签
  • 0个场景
  • 在Feature描述中列出子章节

Common Pitfalls

常见误区

MistakeCorrection
Tags in comments 
# @brd:
Use Gherkin-native 
@brd:
before Feature
ADR-Ready Score: 95%
Use 
✅ 95% (Target: ≥90%)
response time < 200ms
(hardcoded)		Use 
@threshold:PRD.NN.perf.api.p95_latency
.feature
in 
features/
subdir		Put at suite folder root
BDD-02_query_part1.feature
Use 
BDD-02.2.01_query.feature
Missing @ears tagAll 3 upstream tags are MANDATORY
Only success scenariosInclude all 8 scenario categories
Status: Approved
(with <90% score)		Use 
Status: In Review
or 
Draft
File >500 linesSplit into subsections
09:30
(no seconds)		Use 
09:30:00
EST
timezone		Use 
America/New_York
错误修正方案
标签放在注释中
# @brd:
在Feature之前使用Gherkin原生
@brd:
标签
ADR-Ready Score: 95%
使用
✅ 95% (Target: ≥90%)
格式
response time < 200ms
（硬编码）		使用
@threshold:PRD.NN.perf.api.p95_latency
.feature
文件在
features/
子目录		放在套件文件夹根目录
BDD-02_query_part1.feature
使用
BDD-02.2.01_query.feature
缺失@ears标签必须包含全部3个上游标签
仅包含成功场景覆盖全部8种场景类别
Status: Approved
（评分<90%）		使用
Status: In Review
或
Draft
文件超过500行拆分为子章节
09:30
（无秒）		使用
09:30:00
EST
时区		使用
America/New_York

Post-Creation Validation (MANDATORY)

创建后验证（强制要求）

CRITICAL: Execute validation loop IMMEDIATELY after document creation.
关键注意事项：文档创建后立即执行验证循环。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python scripts/validate_bdd_suite.py --root BDD
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review
  5. IF clean: Mark VALIDATED, proceed
循环:
  1. 运行：python scripts/validate_bdd_suite.py --root BDD
  2. 若错误已修复：回到循环（重新验证）
  3. 若警告已修复：回到循环（重新验证）
  4. 若存在无法修复的问题：记录以便人工审核
  5. 若验证通过：标记为已验证，继续后续流程

Quality Gate

质量门

Blocking: YES - Cannot proceed to ADR creation until validation passes with 0 errors.
阻塞性：是 - 验证通过且无错误后，才能继续创建ADR。

Reserved ID Exemption

保留ID豁免

Pattern: 
BDD-00_*.md
or 
BDD-00_*.feature
Scope: Documents with reserved ID 
000
are FULLY EXEMPT from validation.
Document Types:
  • Index documents (
    BDD-00_index.md
    )
  • Traceability matrix templates
  • Glossaries, registries, checklists
模式：
BDD-00_*.md
或
BDD-00_*.feature
范围：使用保留ID 
000
的文档完全豁免验证。
文档类型：
  • 索引文档（
    BDD-00_index.md
    ）
  • 可追溯性矩阵模板
  • 术语表、注册表、检查清单

Next Skill

下一个技能

After creating BDD, use:
doc-adr
 - Create Architecture Decision Records (Layer 5)
The ADR will:
  • Document architectural decisions for topics identified in BRD/PRD
  • Include 
    @brd
    , 
    @prd
    , 
    @ears
    , 
    @bdd
    tags (cumulative)
  • Use Context-Decision-Consequences format
  • Reference BDD scenarios that validate the architecture
创建BDD后，使用：
doc-adr
 - 创建架构决策记录（第5层）
ADR将：
  • 记录BRD/PRD中确定的主题的架构决策
  • 包含
    @brd
    、
    @prd
    、
    @ears
    、
    @bdd
    标签（累积）
  • 使用Context-Decision-Consequences格式
  • 引用验证架构的BDD场景

Related Resources

相关资源

  • Template: 
    ai_dev_flow/04_BDD/BDD-MVP-TEMPLATE.feature
  • Index Template: 
    ai_dev_flow/04_BDD/BDD-SECTION-0-TEMPLATE.md
  • Subsection Template: 
    ai_dev_flow/04_BDD/BDD-SUBSECTION-TEMPLATE.feature
  • Aggregator Template: 
    ai_dev_flow/04_BDD/BDD-AGGREGATOR-TEMPLATE.feature
  • Creation Rules: 
    ai_dev_flow/04_BDD/BDD_CREATION_RULES.md
  • Validation Rules: 
    ai_dev_flow/04_BDD/BDD_VALIDATION_RULES.md
  • Splitting Rules: 
    ai_dev_flow/04_BDD/BDD_SPLITTING_RULES.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • ID Standards: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
  • 模板：
    ai_dev_flow/04_BDD/BDD-MVP-TEMPLATE.feature
  • 索引模板：
    ai_dev_flow/04_BDD/BDD-SECTION-0-TEMPLATE.md
  • 子章节模板：
    ai_dev_flow/04_BDD/BDD-SUBSECTION-TEMPLATE.feature
  • 聚合器模板：
    ai_dev_flow/04_BDD/BDD-AGGREGATOR-TEMPLATE.feature
  • 创建规则：
    ai_dev_flow/04_BDD/BDD_CREATION_RULES.md
  • 验证规则：
    ai_dev_flow/04_BDD/BDD_VALIDATION_RULES.md
  • 拆分规则：
    ai_dev_flow/04_BDD/BDD_SPLITTING_RULES.md
  • 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • ID标准：
    ai_dev_flow/ID_NAMING_STANDARDS.md

Quick Reference

快速参考

ItemValue
PurposeDefine executable test scenarios
Layer4
Tags Required@brd, @prd, @ears (3 tags)
ADR-Ready Score≥90% required for "Approved" status
Element ID Format
BDD.NN.14.SS
(scenarios), 
BDD.NN.15.SS
(steps)
File StructureNested suite folder: 
docs/04_BDD/BDD-NN_{slug}/
Max File Size500 lines (soft: 400)
Max Scenarios12 per Feature block
Time FormatHH:MM:SS with IANA timezone
Quantitative ValuesUse 
@threshold:PRD.NN.category.key
Next Skilldoc-adr
项值
目的定义可执行测试场景
层级4
必填标签@brd, @prd, @ears（3个标签）
ADR就绪评分达到≥90%才能标记为“已批准”
元素ID格式
BDD.NN.14.SS
（场景）、
BDD.NN.15.SS
（步骤）
文件结构嵌套套件文件夹：
docs/04_BDD/BDD-NN_{slug}/
最大文件大小500行（软限制：400行）
最大场景数每个Feature块12个
时间格式HH:MM:SS + IANA时区
定量值使用
@threshold:PRD.NN.category.key
下一个技能doc-adr

Version History

版本历史

VersionDateChangesAuthor
1.02026-02-08Initial skill definition with YAML frontmatter standardizationSystem
版本日期变更作者
1.02026-02-08初始技能定义，标准化YAML前置内容系统