Back to Details

doc-bdd-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-bdd-validator

doc-bdd-validator

Validate Behavior-Driven Development (BDD) documents against Layer 4 schema standards.
针对第4层 Schema 标准验证行为驱动开发（BDD）文档。

Activation

触发时机

Invoke when user requests validation of BDD documents or after creating/modifying BDD artifacts.
当用户请求验证BDD文档时，或在创建/修改BDD工件后调用。

Validation Schema Reference

验证Schema参考

Schema: 
ai_dev_flow/BDD/BDD_SCHEMA.yaml
Layer: 4 Artifact Type: BDD
Schema: 
ai_dev_flow/BDD/BDD_SCHEMA.yaml
层级: 4 工件类型: BDD

Validation Checklist

验证检查清单

0. Folder Structure Validation (BLOCKING)

0. 文件夹结构验证（阻塞性检查）

Nested Folder Rule: ALL BDD documents MUST be in nested folders regardless of size.
Required Structure:
BDD TypeRequired Location
Markdown
docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.md
Feature
docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.feature
Validation:
1. Check document is inside a nested folder: docs/04_BDD/BDD-NN_{slug}/
2. Verify folder name matches BDD ID pattern: BDD-NN_{slug}
3. Verify file name matches folder: BDD-NN_{slug}.md or .feature
4. Parent path must be: docs/04_BDD/
Example Valid Structure:
docs/04_BDD/
├── BDD-01_f1_iam/
│   ├── BDD-01_f1_iam.md           ✓ Valid
│   ├── BDD-01_f1_iam.feature      ✓ Valid (optional companion)
│   ├── BDD-01.R_review_report_v001.md
│   └── .drift_cache.json
├── BDD-02_f2_session/
│   └── BDD-02_f2_session.md       ✓ Valid
Invalid Structure:
docs/04_BDD/
├── BDD-01_f1_iam.md               ✗ NOT in nested folder
Error Codes:
CodeSeverityDescription
BDD-E020ERRORBDD not in nested folder (BLOCKING)
BDD-E021ERRORFolder name doesn't match BDD ID
BDD-E022ERRORFile name doesn't match folder name
This check is BLOCKING - BDD must pass folder structure validation before other checks proceed.
嵌套文件夹规则: 所有BDD文档无论大小，都必须存放在嵌套文件夹中。
必填结构:
BDD类型必填存放位置
Markdown
docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.md
Feature
docs/04_BDD/BDD-NN_{slug}/BDD-NN_{slug}.feature
验证步骤:
1. 检查文档是否在嵌套文件夹内: docs/04_BDD/BDD-NN_{slug}/
2. 验证文件夹名称是否匹配BDD ID格式: BDD-NN_{slug}
3. 验证文件名是否与文件夹名称匹配: BDD-NN_{slug}.md 或 .feature
4. 父路径必须为: docs/04_BDD/
示例有效结构:
docs/04_BDD/
├── BDD-01_f1_iam/
│   ├── BDD-01_f1_iam.md           ✓ 有效
│   ├── BDD-01_f1_iam.feature      ✓ 有效（可选配套文件）
│   ├── BDD-01.R_review_report_v001.md
│   └── .drift_cache.json
├── BDD-02_f2_session/
│   └── BDD-02_f2_session.md       ✓ 有效
无效结构:
docs/04_BDD/
├── BDD-01_f1_iam.md               ✗ 未存放在嵌套文件夹中
错误码:
代码严重程度描述
BDD-E020ERRORBDD未存放在嵌套文件夹中（阻塞性检查）
BDD-E021ERROR文件夹名称与BDD ID不匹配
BDD-E022ERROR文件名与文件夹名称不匹配
此检查为阻塞性检查 - BDD必须通过文件夹结构验证后，才能进行其他检查。

1. Metadata Validation

1. 元数据验证

yaml
Required custom_fields:
  - document_type: ["bdd", "template"]
  - artifact_type: "BDD"
  - layer: 4
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - bdd (or bdd-template)
  - layer-4-artifact

Forbidden tag patterns:
  - "^behavior-driven$"
  - "^bdd-\\d{3}$"
yaml
Required custom_fields:
  - document_type: ["bdd", "template"]
  - artifact_type: "BDD"
  - layer: 4
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - bdd (or bdd-template)
  - layer-4-artifact

Forbidden tag patterns:
  - "^behavior-driven$"
  - "^bdd-\\d{3}$"

2. Structure Validation

2. 结构验证

Required Sections:
  • Title (H1): 
    # BDD-NNN: Title
  • Document Control (Section 1)
  • Feature Overview (Section 2)
  • Scenarios (Section 3)
  • Scenario Outlines (Section 4)
  • Background Steps (Section 5)
  • Tags and Hooks (Section 6)
  • Test Data (Section 7)
  • Traceability (Section 8)
  • Change History (Section 9)
Document Control Required Fields:
  • BDD ID
  • Document Name
  • Version
  • Date Created
  • Last Updated
  • Author
  • Status
  • Source EARS
File Naming: Pattern: 
BDD-NNN_descriptive_name.md
必填章节:
  • 标题（H1）: 
    # BDD-NNN: 标题
  • 文档控制（第1节）
  • 功能概述（第2节）
  • 场景（第3节）
  • 场景大纲（第4节）
  • 背景步骤（第5节）
  • 标签与钩子（第6节）
  • 测试数据（第7节）
  • 可追溯性（第8节）
  • 变更历史（第9节）
文档控制必填字段:
  • BDD ID
  • 文档名称
  • 版本
  • 创建日期
  • 最后更新日期
  • 作者
  • 状态
  • 来源EARS
文件命名: 格式: 
BDD-NNN_descriptive_name.md

3. Content Validation

3. 内容验证

Gherkin Syntax:
gherkin
Feature: [Feature Name]
  As a [role]
  I want [feature]
  So that [benefit]

  Scenario: [Scenario Name]
    Given [context]
    When [action]
    Then [expected outcome]
    And [additional outcome]
Scenario Format:
  • Pattern: 
    Scenario: Description
  • Required steps: Given, When, Then
  • Optional steps: And, But
Scenario Outline Format:
gherkin
Scenario Outline: [Description]
  Given [context with <variable>]
  When [action with <variable>]
  Then [outcome with <variable>]

  Examples:
    | variable | value |
    | data1    | val1  |
ADR-Ready Score:
  • Minimum threshold: 90%
  • Components: Scenario coverage, step clarity, data completeness, traceability
Gherkin语法:
gherkin
Feature: [Feature Name]
  As a [role]
  I want [feature]
  So that [benefit]

  Scenario: [Scenario Name]
    Given [context]
    When [action]
    Then [expected outcome]
    And [additional outcome]
场景格式:
  • 格式: 
    Scenario: 场景名称
  • 必填步骤: Given, When, Then
  • 可选步骤: And, But
场景大纲格式:
gherkin
Scenario Outline: [Description]
  Given [context with <variable>]
  When [action with <variable>]
  Then [outcome with <variable>]

  Examples:
    | variable | value |
    | data1    | val1  |
ADR就绪分数:
  • 最低阈值: 90%
  • 组成部分: 场景覆盖率、步骤清晰度、数据完整性、可追溯性

4. Traceability Validation

4. 可追溯性验证

Layer 4 Cumulative Tags:
  • @brd: BRD.NN.01.SS (required)
  • @prd: PRD.NN.07.SS (required)
  • @ears: EARS.NN.24.SS (required)
Downstream Expected:
  • ADR documents
  • SYS requirements
  • Test implementations
Same-Type References:
  • @related-bdd: BDD-NN
  • @depends-bdd: BDD-NN
第4层累积标签:
  • @brd: BRD.NN.01.SS (必填)
  • @prd: PRD.NN.07.SS (必填)
  • @ears: EARS.NN.24.SS (必填)
预期下游关联:
  • ADR文档
  • SYS需求
  • 测试实现
同类型引用:
  • @related-bdd: BDD-NN
  • @depends-bdd: BDD-NN

Error Codes

错误码

CodeSeverityDescription
BDD-E001errorMissing required tag 'bdd'
BDD-E002errorMissing required tag 'layer-4-artifact'
BDD-E003errorInvalid document_type
BDD-E004errorInvalid architecture_approaches format
BDD-E005errorForbidden tag pattern detected
BDD-E006errorMissing required section
BDD-E007errorMultiple H1 headings detected
BDD-E008errorSection numbering not sequential
BDD-E009errorDocument Control missing required fields
BDD-E010errorInvalid Gherkin syntax
BDD-E011errorScenario missing Given-When-Then
BDD-E012errorMissing Traceability (Section 8)
BDD-E013warningFile name does not match format
BDD-W001warningScenario missing Then step
BDD-W002warningMissing upstream tags (@brd, @prd, @ears)
BDD-W003warningADR-Ready Score below 90%
BDD-W004warningScenario Outline missing Examples
BDD-W005warningTest data incomplete
BDD-I001infoConsider adding Background steps
BDD-I002infoConsider adding negative scenarios
代码严重程度描述
BDD-E001error缺失必填标签 'bdd'
BDD-E002error缺失必填标签 'layer-4-artifact'
BDD-E003error无效的document_type
BDD-E004errorarchitecture_approaches格式无效
BDD-E005error检测到禁用的标签模式
BDD-E006error缺失必填章节
BDD-E007error检测到多个H1标题
BDD-E008error章节编号不连续
BDD-E009error文档控制缺失必填字段
BDD-E010error无效的Gherkin语法
BDD-E011error场景缺失Given-When-Then步骤
BDD-E012error缺失可追溯性章节（第8节）
BDD-E013warning文件名不符合格式
BDD-W001warning场景缺失Then步骤
BDD-W002warning缺失上游标签 (@brd, @prd, @ears)
BDD-W003warningADR就绪分数低于90%
BDD-W004warning场景大纲缺失Examples
BDD-W005warning测试数据不完整
BDD-I001info建议添加Background步骤
BDD-I002info建议添加负面场景

Validation Commands

验证命令

bash
undefined
bash
undefined

Validate single BDD document

验证单个BDD文档

python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/BDD-001_example.md
python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/BDD-001_example.md

Validate all BDD documents

验证所有BDD文档

python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/
python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/

Validate .feature files

验证.feature文件

python ai_dev_flow/scripts/validate_bdd.py tests/bdd/features/
python ai_dev_flow/scripts/validate_bdd.py tests/bdd/features/

Check with verbose output

启用详细输出验证

python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/ --verbose
undefined
python ai_dev_flow/scripts/validate_bdd.py docs/04_BDD/ --verbose
undefined

Validation Workflow

验证流程

  1. Parse YAML frontmatter
  2. Check required metadata fields
  3. Validate tag taxonomy
  4. Verify section structure (1-9)
  5. Validate Document Control table
  6. Check Gherkin syntax compliance
  7. Verify Given-When-Then structure
  8. Validate Scenario Outline Examples
  9. Validate upstream references
  10. Calculate ADR-Ready Score
  11. Verify file naming convention
  12. Generate validation report
  1. 解析YAML前置元数据
  2. 检查必填元数据字段
  3. 验证标签分类
  4. 校验章节结构（1-9）
  5. 验证文档控制表格
  6. 检查Gherkin语法合规性
  7. 验证Given-When-Then结构
  8. 验证场景大纲的Examples
  9. 验证上游引用
  10. 计算ADR就绪分数
  11. 验证文件命名规范
  12. 生成验证报告

Gherkin Pattern Detection

Gherkin模式检测

python
patterns = {
    'feature': r'^Feature:\s+.+',
    'scenario': r'^Scenario:\s+.+',
    'scenario_outline': r'^Scenario Outline:\s+.+',
    'given': r'^\s*Given\s+.+',
    'when': r'^\s*When\s+.+',
    'then': r'^\s*Then\s+.+',
    'and': r'^\s*And\s+.+',
    'but': r'^\s*But\s+.+',
    'background': r'^Background:',
    'examples': r'^\s*Examples:'
}
python
patterns = {
    'feature': r'^Feature:\s+.+',
    'scenario': r'^Scenario:\s+.+',
    'scenario_outline': r'^Scenario Outline:\s+.+',
    'given': r'^\s*Given\s+.+',
    'when': r'^\s*When\s+.+',
    'then': r'^\s*Then\s+.+',
    'and': r'^\s*And\s+.+',
    'but': r'^\s*But\s+.+',
    'background': r'^Background:',
    'examples': r'^\s*Examples:'
}

Integration

集成

  • Invoked by: doc-flow, doc-bdd (post-creation)
  • Feeds into: trace-check (cross-document validation)
  • Reports to: quality-advisor
  • 调用方: doc-flow, doc-bdd（创建后）
  • 输出至: trace-check（跨文档验证）
  • 报告至: quality-advisor

Output Format

输出格式

BDD Validation Report
=====================
Document: BDD-001_example.md
Status: PASS/FAIL

Scenario Summary:
- Total Scenarios: N
- With Given-When-Then: N
- Scenario Outlines: N
- With Examples: N

Errors: N
Warnings: N
Info: N

[Details listed by severity]
BDD验证报告
=====================
文档: BDD-001_example.md
状态: PASS/FAIL

场景摘要:
- 总场景数: N
- 包含Given-When-Then步骤: N
- 场景大纲数: N
- 包含Examples: N

错误数: N
警告数: N
信息提示数: N

[按严重程度列出详情]

Version History

版本历史

VersionDateChangesAuthor
1.12026-02-11Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); BDD must be in 
docs/04_BDD/BDD-NN_{slug}/
folders; Added error codes BDD-E020, BDD-E021, BDD-E022
1.02026-02-08Initial validator skill definition with YAML frontmatterSystem
版本日期变更作者
1.12026-02-11嵌套文件夹规则: 新增第0节文件夹结构验证（阻塞性检查）；BDD必须存放在
docs/04_BDD/BDD-NN_{slug}/
文件夹中；新增错误码BDD-E020、BDD-E021、BDD-E022
1.02026-02-08初始验证器技能定义，包含YAML前置元数据系统