doc-brd-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

doc-brd-validator

Validate Business Requirements Documents (BRD) against Layer 1 MVP schema standards.

对照Layer 1 MVP schema标准验证业务需求文档（BRD）。

Purpose

用途

Validates BRD documents for:

YAML frontmatter metadata compliance
Section structure (18 sections for comprehensive template)
Document Control completeness
Traceability tag format and presence
PRD-Ready scoring
File naming conventions
Architecture Decision Requirements completeness

验证BRD文档是否符合以下要求：

YAML前置元数据合规性
章节结构（完整模板包含18个章节）
文档控制完整性
可追溯性标签格式与存在性
PRD就绪评分
文件命名规范
架构决策需求完整性

Activation

触发时机

Invoke when:

User requests validation of BRD documents
After creating/modifying BRD artifacts
Before generating downstream artifacts (PRD)
As part of quality gate checks

在以下场景调用：

用户请求验证BRD文档时
创建/修改BRD工件后
生成下游工件（PRD）前
作为质量门检查的一部分

Schema Reference

Schema参考

Item	Value
Schema	`ai_dev_flow/01_BRD/BRD_MVP_SCHEMA.yaml`
Template	`ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md`
Creation Rules	`ai_dev_flow/01_BRD/BRD_CREATION_RULES.md`
Validation Rules	`ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md`
Layer	1
Artifact Type	BRD

项	值
Schema	`ai_dev_flow/01_BRD/BRD_MVP_SCHEMA.yaml`
模板	`ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md`
创建规则	`ai_dev_flow/01_BRD/BRD_CREATION_RULES.md`
验证规则	`ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md`
层级	1
工件类型	BRD

Validation Checklist

验证检查清单

1. Metadata Validation

1. 元数据验证

yaml

Required custom_fields:
  document_type: ["brd", "template"]
  artifact_type: "BRD"
  layer: 1
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - brd (or brd-template)
  - layer-1-artifact

Forbidden tag patterns:
  - "^business-requirements$"
  - "^brd-\\d{3}$"

yaml

Required custom_fields:
  document_type: ["brd", "template"]
  artifact_type: "BRD"
  layer: 1
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - brd (or brd-template)
  - layer-1-artifact

Forbidden tag patterns:
  - "^business-requirements$"
  - "^brd-\\d{3}$"

2. Structure Validation

2. 结构验证

Required Sections (18 Total):

Section	Title	Required
0	Document Control	MANDATORY
1	Executive Summary	MANDATORY
2	Business Context	MANDATORY
3	Stakeholder Analysis	MANDATORY
4	Business Requirements	MANDATORY
5	Success Criteria	MANDATORY
6	Constraints and Assumptions	MANDATORY
7	Architecture Decision Requirements	MANDATORY
8	Risk Assessment	MANDATORY
9	Traceability	MANDATORY
10-18	Additional sections	Per template

Section Format:

## N. Title

(numbered H2 headings)

必填章节（共18个）:

章节	标题	是否必填
0	文档控制	必填
1	执行摘要	必填
2	业务背景	必填
3	干系人分析	必填
4	业务需求	必填
5	成功标准	必填
6	约束与假设	必填
7	架构决策需求	必填
8	风险评估	必填
9	可追溯性	必填
10-18	附加章节	依模板而定

章节格式:

## N. 标题

（带编号的二级标题）

3. Document Control Required Fields

3. 文档控制必填字段

Field	Description	Required
Project Name	Project identifier	MANDATORY
Document Version	Semantic versioning (X.Y.Z)	MANDATORY
Date Created	YYYY-MM-DD format	MANDATORY
Last Updated	YYYY-MM-DD format	MANDATORY
Document Owner	Owner name	MANDATORY
Prepared By	Author name	MANDATORY
Status	Draft/In Review/Approved/Superseded	MANDATORY
PRD-Ready Score	`XX/100 (Target: ≥90)`	MANDATORY

字段	描述	是否必填
项目名称	项目标识符	必填
文档版本	语义化版本（X.Y.Z）	必填
创建日期	YYYY-MM-DD格式	必填
最后更新日期	YYYY-MM-DD格式	必填
文档负责人	负责人姓名	必填
编制人	作者姓名	必填
状态	草稿/评审中/已批准/已取代	必填
PRD就绪评分	`XX/100（目标：≥90）`	必填

4. Content Validation

4. 内容验证

Business Objectives Format (Section 3):

Pattern:
```
BRD.NN.23.SS
```
(unified 4-segment format)
Required fields: ID, Objective, Priority, Success Criteria, Measurement Method

Business Requirements Format (Section 4):

Pattern:
```
BRD.NN.01.SS
```
(unified 4-segment format)
Required fields: ID, Requirement, Type, Priority, Source, Rationale
Priority values: Critical (P1), High (P2), Medium (P3), Low (P4)
Type values: Functional, Non-Functional, Regulatory, Operational

PRD-Ready Score:

Minimum threshold: 90%
Components: Business objectives, requirements completeness, success metrics, constraints, stakeholder analysis, risk assessment, traceability, ADR topics completeness

业务目标格式（第3章）:

格式:
```
BRD.NN.23.SS
```
（统一四段式格式）
必填字段：ID、目标、优先级、成功标准、衡量方法

业务需求格式（第4章）:

格式:
```
BRD.NN.01.SS
```
（统一四段式格式）
必填字段：ID、需求、类型、优先级、来源、理由
优先级取值：Critical（P1）、High（P2）、Medium（P3）、Low（P4）
类型取值：功能性、非功能性、合规性、操作性

PRD就绪评分:

最低阈值：90%
组成部分：业务目标、需求完整性、成功指标、约束条件、干系人分析、风险评估、可追溯性、ADR主题完整性

5. Architecture Decision Requirements (Section 7.2) - MANDATORY

5. 架构决策需求（第7.2节）- 必填

7 Mandatory ADR Topic Categories:

#	Category	Element ID	Status Values
1	Infrastructure	BRD.NN.32.01	Selected/Pending/N/A
2	Data Architecture	BRD.NN.32.02	Selected/Pending/N/A
3	Integration	BRD.NN.32.03	Selected/Pending/N/A
4	Security	BRD.NN.32.04	Selected/Pending/N/A
5	Observability	BRD.NN.32.05	Selected/Pending/N/A
6	AI/ML	BRD.NN.32.06	Selected/Pending/N/A
7	Technology Selection	BRD.NN.32.07	Selected/Pending/N/A

Element Type Code:

= Architecture Topic (see

doc-naming

skill)

Required Fields Per Topic (Status=Selected):

Status (Selected/Pending/N/A)
Business Driver
Business Constraints
Alternatives Overview table (Option | Function | Est. Monthly Cost | Selection Rationale)
Cloud Provider Comparison table (Criterion | GCP | Azure | AWS)
Recommended Selection
PRD Requirements

Required Fields Per Topic (Status=Pending):

Status with reason
Business Driver
Business Constraints
PRD Requirements

Required Fields Per Topic (Status=N/A):

Status with explicit reason
PRD Requirements (can be "None for current scope")

7个必填ADR主题类别:

#	类别	元素ID	状态取值
1	基础设施	BRD.NN.32.01	Selected/Pending/N/A
2	数据架构	BRD.NN.32.02	Selected/Pending/N/A
3	集成	BRD.NN.32.03	Selected/Pending/N/A
4	安全	BRD.NN.32.04	Selected/Pending/N/A
5	可观测性	BRD.NN.32.05	Selected/Pending/N/A
6	AI/ML	BRD.NN.32.06	Selected/Pending/N/A
7	技术选型	BRD.NN.32.07	Selected/Pending/N/A

元素类型代码:

= 架构主题（参见

doc-naming

技能）

每个主题必填字段（状态=Selected）:

状态（Selected/Pending/N/A）
业务驱动因素
业务约束
替代方案概览表（选项 | 功能 | 预估月度成本 | 选型理由）
云服务商对比表（评估标准 | GCP | Azure | AWS）
推荐选型
PRD需求

每个主题必填字段（状态=Pending）:

状态及理由
业务驱动因素
业务约束
PRD需求

每个主题必填字段（状态=N/A）:

状态及明确理由
PRD需求（可为"当前范围无相关需求"）

6. Naming Compliance (doc-naming integration)

6. 命名合规性（集成doc-naming）

Element ID Validation:

Format:
```
BRD.NN.TT.SS
```
(4-segment unified format)
Valid element type codes for BRD: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33
No legacy patterns (BO-XXX, FR-XXX, AC-XXX, BC-XXX)

File Naming Convention:

Pattern:
```
BRD-NN_{descriptive_slug}.md
```
```
NN
```
: 2+ digit number (01, 02, ... 99, 100)
```
descriptive_slug
```
: lowercase with underscores

Sectioned BRD Pattern:

docs/01_BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md

元素ID验证:

格式:
```
BRD.NN.TT.SS
```
（四段式统一格式）
BRD有效元素类型代码：01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33
禁止使用旧格式（BO-XXX, FR-XXX, AC-XXX, BC-XXX）

文件命名规范:

格式:
```
BRD-NN_{descriptive_slug}.md
```
```
NN
```
: 2位及以上数字（01, 02, ... 99, 100）
```
descriptive_slug
```
: 小写字母加下划线

分章节BRD格式:

docs/01_BRD/BRD-NN_{slug}/BRD-NN.S_{section}.md

7. Traceability Validation

7. 可追溯性验证

Layer 1 Tags:

No upstream artifacts required (BRD is the entry point)
Tag count: 0

Downstream Expected:

PRD documents (Layer 2)
EARS statements (Layer 3)
ADR documents (Layer 5)

Same-Type References:

```
@related-brd: BRD-NN
```
```
@supersedes-brd: BRD-NN
```
```
@depends-brd: BRD-NN
```

Layer 1标签:

无需上游工件（BRD是入口点）
标签数量: 0

预期下游工件:

PRD文档（Layer 2）
EARS语句（Layer 3）
ADR文档（Layer 5）

同类型引用:

```
@related-brd: BRD-NN
```
```
@supersedes-brd: BRD-NN
```
```
@depends-brd: BRD-NN
```

Error Codes

错误码

Code	Severity	Description
BRD-E001	ERROR	Missing required tag 'brd'
BRD-E002	ERROR	Missing required tag 'layer-1-artifact'
BRD-E003	ERROR	Invalid document_type value
BRD-E004	ERROR	Invalid architecture_approaches format (must be array)
BRD-E005	ERROR	Forbidden tag pattern detected
BRD-E006	ERROR	Missing required section
BRD-E007	ERROR	Multiple H1 headings detected
BRD-E008	ERROR	Section numbering not sequential
BRD-E009	ERROR	Document Control missing required fields
BRD-E010	ERROR	Missing Business Objectives (Section 3)
BRD-E011	ERROR	Missing Business Requirements (Section 4)
BRD-E012	ERROR	Missing Traceability (Section 9)
BRD-E013	ERROR	Missing Section 7.2 (Architecture Decision Requirements)
BRD-E014	ERROR	Missing mandatory ADR topic category
BRD-E015	ERROR	ADR topic missing required Status field
BRD-E016	ERROR	Selected ADR topic missing Alternatives Overview table
BRD-E017	ERROR	Selected ADR topic missing Cloud Provider Comparison table
BRD-E018	ERROR	N/A ADR topic missing explicit reason
BRD-E019	ERROR	Invalid element ID format (not BRD.NN.TT.SS)
BRD-E020	ERROR	Element type code not valid for BRD (see doc-naming)
BRD-E021	ERROR	Deprecated ID pattern used (BO-XXX, FR-XXX, etc.)
BRD-W001	WARNING	Objectives not using BRD.NN.23.SS format
BRD-W002	WARNING	Requirements not using BRD.NN.01.SS format
BRD-W003	WARNING	Missing Success Metrics (Section 5)
BRD-W004	WARNING	PRD-Ready Score below 90%
BRD-W005	WARNING	Missing Stakeholder Analysis
BRD-W006	WARNING	File name does not match format BRD-NN_{slug}.md
BRD-W007	WARNING	ADR topic missing cost estimates in Alternatives Overview
BRD-W008	WARNING	ADR topic missing PRD Requirements field
BRD-W009	WARNING	Missing Document Revision History table
BRD-I001	INFO	Consider adding regulatory compliance requirements
BRD-I002	INFO	Consider adding market analysis context
BRD-I003	INFO	Consider completing Pending ADR topics before PRD creation

错误码	严重程度	描述
BRD-E001	错误	缺失必填标签'brd'
BRD-E002	错误	缺失必填标签'layer-1-artifact'
BRD-E003	错误	document_type值无效
BRD-E004	错误	architecture_approaches格式无效（必须为数组）
BRD-E005	错误	检测到禁用的标签模式
BRD-E006	错误	缺失必填章节
BRD-E007	错误	检测到多个一级标题
BRD-E008	错误	章节编号不连续
BRD-E009	错误	文档控制缺失必填字段
BRD-E010	错误	缺失业务目标（第3章）
BRD-E011	错误	缺失业务需求（第4章）
BRD-E012	错误	缺失可追溯性（第9章）
BRD-E013	错误	缺失第7.2节（架构决策需求）
BRD-E014	错误	缺失必填ADR主题类别
BRD-E015	错误	ADR主题缺失必填状态字段
BRD-E016	错误	已选中的ADR主题缺失替代方案概览表
BRD-E017	错误	已选中的ADR主题缺失云服务商对比表
BRD-E018	错误	标记为N/A的ADR主题缺失明确理由
BRD-E019	错误	元素ID格式无效（非BRD.NN.TT.SS格式）
BRD-E020	错误	元素类型代码对BRD无效（参见doc-naming）
BRD-E021	错误	使用了已废弃的ID格式（BO-XXX, FR-XXX等）
BRD-W001	警告	目标未使用BRD.NN.23.SS格式
BRD-W002	警告	需求未使用BRD.NN.01.SS格式
BRD-W003	警告	缺失成功指标（第5章）
BRD-W004	警告	PRD就绪评分低于90%
BRD-W005	警告	缺失干系人分析
BRD-W006	警告	文件名不符合BRD-NN_{slug}.md格式
BRD-W007	警告	ADR主题的替代方案概览中缺失成本估算
BRD-W008	警告	ADR主题缺失PRD需求字段
BRD-W009	警告	缺失文档修订历史表
BRD-I001	信息	建议添加合规性需求
BRD-I002	信息	建议添加市场分析背景
BRD-I003	信息	建议在创建PRD前完成待处理的ADR主题

Validation Commands

验证命令

bash

undefined

bash

undefined

Validate single BRD document

验证单个BRD文档

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/BRD-01_example.md

Validate all BRD documents in directory

验证目录下所有BRD文档

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/

Validate with verbose output

启用详细输出验证

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/ --verbose

Validate with auto-fix

启用自动修复验证

python ai_dev_flow/scripts/validate_brd.py docs/01_BRD/ --auto-fix

Cross-document validation

跨文档验证

python ai_dev_flow/scripts/validate_cross_document.py --document docs/01_BRD/BRD-01.md --auto-fix

undefined

python ai_dev_flow/scripts/validate_cross_document.py --document docs/01_BRD/BRD-01.md --auto-fix

undefined

Validation Workflow

验证流程

Parse YAML frontmatter
Check required metadata fields (document_type, artifact_type, layer)
Validate tag taxonomy (brd, layer-1-artifact)
Verify section structure (18 sections)
Validate Document Control table completeness
Check business objectives format (BRD.NN.23.SS)
Check business requirements format (BRD.NN.01.SS)
Validate Section 7.2 ADR Topics:
- Verify all 7 mandatory categories present
- Check Status field (Selected/Pending/N/A)
- For Selected: Verify Alternatives Overview table, Cloud Provider Comparison table
- For N/A: Verify explicit reason provided
- Validate element ID format (BRD.NN.32.SS)
Calculate PRD-Ready Score (includes ADR completeness)
Verify file naming convention
Check element ID format compliance (per doc-naming)
Detect deprecated patterns
Generate validation report

解析YAML前置元数据
检查必填元数据字段（document_type, artifact_type, layer）
验证标签分类（brd, layer-1-artifact）
验证章节结构（18个章节）
验证文档控制表完整性
检查业务目标格式（BRD.NN.23.SS）
检查业务需求格式（BRD.NN.01.SS）
验证第7.2节ADR主题:
- 验证所有7个必填类别是否存在
- 检查状态字段（Selected/Pending/N/A）
- 对于已选中的主题：验证替代方案概览表、云服务商对比表
- 对于标记为N/A的主题：验证是否提供明确理由
- 验证元素ID格式（BRD.NN.32.SS）
计算PRD就绪评分（包含ADR完整性）
验证文件命名规范
检查元素ID格式合规性（依据doc-naming）
检测已废弃格式
生成验证报告

Auto-Fix Actions

自动修复操作

Issue	Auto-Fix Action
Invalid element ID format	Convert to BRD.NN.TT.SS format
Missing traceability section	Insert from template
Missing Document Control fields	Add placeholder fields
Deprecated ID patterns	Convert to unified format
Missing PRD-Ready Score	Calculate and insert

问题	自动修复操作
元素ID格式无效	转换为BRD.NN.TT.SS格式
缺失可追溯性章节	从模板插入
缺失文档控制字段	添加占位符字段
使用已废弃的ID格式	转换为统一格式
缺失PRD就绪评分	计算并插入

Integration

集成关系

Invoked by: doc-flow, doc-brd (post-creation), doc-prd-autopilot
Feeds into: trace-check (cross-document validation)
Reports to: quality-advisor

调用方: doc-flow, doc-brd（创建后）, doc-prd-autopilot
输出至: trace-check（跨文档验证）
报告至: quality-advisor

Output Format

输出格式

BRD Validation Report
=====================
Document: BRD-01_platform_architecture.md
Status: PASS/FAIL

PRD-Ready Score: 92% (Target: ≥90%) ✓

Errors: 0
Warnings: 2
Info: 1

[BRD-W006] WARNING: File name should use lowercase slug
[BRD-W009] WARNING: Missing Document Revision History table
[BRD-I001] INFO: Consider adding regulatory compliance requirements

BRD Validation Report
=====================
Document: BRD-01_platform_architecture.md
Status: PASS/FAIL

PRD-Ready Score: 92% (Target: ≥90%) ✓

Errors: 0
Warnings: 2
Info: 1

[BRD-W006] WARNING: File name should use lowercase slug
[BRD-W009] WARNING: Missing Document Revision History table
[BRD-I001] INFO: Consider adding regulatory compliance requirements

Related Resources

Version History

版本历史

Version	Date	Changes
2.1	2026-02-10	Added element type code 33 (Benefit Statement) to valid BRD codes per doc-naming v1.5
2.0	2026-02-08	Complete rewrite: Added YAML frontmatter, doc-naming integration (BRD-E019/E020/E021), updated section structure to 18 sections, fixed file paths with numbered prefixes, added PRD-Ready score validation
1.0	2025-01-06	Initial version (outdated 12-section structure)

版本	日期	变更内容
2.1	2026-02-10	根据doc-naming v1.5版本，新增元素类型代码33（收益声明）至BRD有效代码列表
2.0	2026-02-08	完全重写：新增YAML前置元数据、集成doc-naming（BRD-E019/E020/E021）、更新章节结构至18个章节、修复带编号前缀的文件路径、新增PRD就绪评分验证
1.0	2025-01-06	初始版本（采用已过时的12章节结构）

doc-brd-validator

Original

Translation

doc-brd-validator

doc-brd-validator

Purpose

用途

Activation

触发时机

Schema Reference

Schema参考

Validation Checklist

验证检查清单

1. Metadata Validation

1. 元数据验证

2. Structure Validation

2. 结构验证

3. Document Control Required Fields

3. 文档控制必填字段

4. Content Validation

4. 内容验证

5. Architecture Decision Requirements (Section 7.2) - MANDATORY

5. 架构决策需求（第7.2节）- 必填

6. Naming Compliance (doc-naming integration)

6. 命名合规性（集成doc-naming）

7. Traceability Validation

7. 可追溯性验证

Error Codes

错误码

Validation Commands

验证命令

Validate single BRD document

验证单个BRD文档

Validate all BRD documents in directory

验证目录下所有BRD文档

Validate with verbose output

启用详细输出验证

Validate with auto-fix

启用自动修复验证

Cross-document validation

跨文档验证

Validation Workflow

验证流程

Auto-Fix Actions

自动修复操作

Integration

集成关系

Output Format

输出格式

Related Resources

相关资源

Version History

版本历史