Back to Details

doc-brd-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-brd-validator

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参考

ItemValue
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
Layer1
Artifact TypeBRD
项值
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):
SectionTitleRequired
0Document ControlMANDATORY
1Executive SummaryMANDATORY
2Business ContextMANDATORY
3Stakeholder AnalysisMANDATORY
4Business RequirementsMANDATORY
5Success CriteriaMANDATORY
6Constraints and AssumptionsMANDATORY
7Architecture Decision RequirementsMANDATORY
8Risk AssessmentMANDATORY
9TraceabilityMANDATORY
10-18Additional sectionsPer 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. 文档控制必填字段

FieldDescriptionRequired
Project NameProject identifierMANDATORY
Document VersionSemantic versioning (X.Y.Z)MANDATORY
Date CreatedYYYY-MM-DD formatMANDATORY
Last UpdatedYYYY-MM-DD formatMANDATORY
Document OwnerOwner nameMANDATORY
Prepared ByAuthor nameMANDATORY
StatusDraft/In Review/Approved/SupersededMANDATORY
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:
#CategoryElement IDStatus Values
1InfrastructureBRD.NN.32.01Selected/Pending/N/A
2Data ArchitectureBRD.NN.32.02Selected/Pending/N/A
3IntegrationBRD.NN.32.03Selected/Pending/N/A
4SecurityBRD.NN.32.04Selected/Pending/N/A
5ObservabilityBRD.NN.32.05Selected/Pending/N/A
6AI/MLBRD.NN.32.06Selected/Pending/N/A
7Technology SelectionBRD.NN.32.07Selected/Pending/N/A
Element Type Code: 
32
= 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.01Selected/Pending/N/A
2数据架构BRD.NN.32.02Selected/Pending/N/A
3集成BRD.NN.32.03Selected/Pending/N/A
4安全BRD.NN.32.04Selected/Pending/N/A
5可观测性BRD.NN.32.05Selected/Pending/N/A
6AI/MLBRD.NN.32.06Selected/Pending/N/A
7技术选型BRD.NN.32.07Selected/Pending/N/A
元素类型代码: 
32
= 架构主题（参见
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

错误码

CodeSeverityDescription
BRD-E001ERRORMissing required tag 'brd'
BRD-E002ERRORMissing required tag 'layer-1-artifact'
BRD-E003ERRORInvalid document_type value
BRD-E004ERRORInvalid architecture_approaches format (must be array)
BRD-E005ERRORForbidden tag pattern detected
BRD-E006ERRORMissing required section
BRD-E007ERRORMultiple H1 headings detected
BRD-E008ERRORSection numbering not sequential
BRD-E009ERRORDocument Control missing required fields
BRD-E010ERRORMissing Business Objectives (Section 3)
BRD-E011ERRORMissing Business Requirements (Section 4)
BRD-E012ERRORMissing Traceability (Section 9)
BRD-E013ERRORMissing Section 7.2 (Architecture Decision Requirements)
BRD-E014ERRORMissing mandatory ADR topic category
BRD-E015ERRORADR topic missing required Status field
BRD-E016ERRORSelected ADR topic missing Alternatives Overview table
BRD-E017ERRORSelected ADR topic missing Cloud Provider Comparison table
BRD-E018ERRORN/A ADR topic missing explicit reason
BRD-E019ERRORInvalid element ID format (not BRD.NN.TT.SS)
BRD-E020ERRORElement type code not valid for BRD (see doc-naming)
BRD-E021ERRORDeprecated ID pattern used (BO-XXX, FR-XXX, etc.)
BRD-W001WARNINGObjectives not using BRD.NN.23.SS format
BRD-W002WARNINGRequirements not using BRD.NN.01.SS format
BRD-W003WARNINGMissing Success Metrics (Section 5)
BRD-W004WARNINGPRD-Ready Score below 90%
BRD-W005WARNINGMissing Stakeholder Analysis
BRD-W006WARNINGFile name does not match format BRD-NN_{slug}.md
BRD-W007WARNINGADR topic missing cost estimates in Alternatives Overview
BRD-W008WARNINGADR topic missing PRD Requirements field
BRD-W009WARNINGMissing Document Revision History table
BRD-I001INFOConsider adding regulatory compliance requirements
BRD-I002INFOConsider adding market analysis context
BRD-I003INFOConsider 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
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/
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
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
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

验证流程

  1. Parse YAML frontmatter
  2. Check required metadata fields (document_type, artifact_type, layer)
  3. Validate tag taxonomy (brd, layer-1-artifact)
  4. Verify section structure (18 sections)
  5. Validate Document Control table completeness
  6. Check business objectives format (BRD.NN.23.SS)
  7. Check business requirements format (BRD.NN.01.SS)
  8. 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)
  9. Calculate PRD-Ready Score (includes ADR completeness)
  10. Verify file naming convention
  11. Check element ID format compliance (per doc-naming)
  12. Detect deprecated patterns
  13. Generate validation report
  1. 解析YAML前置元数据
  2. 检查必填元数据字段（document_type, artifact_type, layer）
  3. 验证标签分类（brd, layer-1-artifact）
  4. 验证章节结构（18个章节）
  5. 验证文档控制表完整性
  6. 检查业务目标格式（BRD.NN.23.SS）
  7. 检查业务需求格式（BRD.NN.01.SS）
  8. 验证第7.2节ADR主题:
    • 验证所有7个必填类别是否存在
    • 检查状态字段（Selected/Pending/N/A）
    • 对于已选中的主题：验证替代方案概览表、云服务商对比表
    • 对于标记为N/A的主题：验证是否提供明确理由
    • 验证元素ID格式（BRD.NN.32.SS）
  9. 计算PRD就绪评分（包含ADR完整性）
  10. 验证文件命名规范
  11. 检查元素ID格式合规性（依据doc-naming）
  12. 检测已废弃格式
  13. 生成验证报告

Auto-Fix Actions

自动修复操作

IssueAuto-Fix Action
Invalid element ID formatConvert to BRD.NN.TT.SS format
Missing traceability sectionInsert from template
Missing Document Control fieldsAdd placeholder fields
Deprecated ID patternsConvert to unified format
Missing PRD-Ready ScoreCalculate 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

相关资源

  • Naming Standards: 
    .claude/skills/doc-naming/SKILL.md
    (element IDs, element type codes)
  • BRD Skill: 
    .claude/skills/doc-brd/SKILL.md
  • BRD Template: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
  • BRD Schema: 
    ai_dev_flow/01_BRD/BRD_MVP_SCHEMA.yaml
  • Creation Rules: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  • Validation Rules: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • 命名标准: 
    .claude/skills/doc-naming/SKILL.md
    （元素ID、元素类型代码）
  • BRD技能: 
    .claude/skills/doc-brd/SKILL.md
  • BRD模板: 
    ai_dev_flow/01_BRD/BRD-MVP-TEMPLATE.md
  • BRD Schema: 
    ai_dev_flow/01_BRD/BRD_MVP_SCHEMA.yaml
  • 创建规则: 
    ai_dev_flow/01_BRD/BRD_CREATION_RULES.md
  • 验证规则: 
    ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md

Version History

版本历史

VersionDateChanges
2.12026-02-10Added element type code 33 (Benefit Statement) to valid BRD codes per doc-naming v1.5
2.02026-02-08Complete 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.02025-01-06Initial version (outdated 12-section structure)
版本日期变更内容
2.12026-02-10根据doc-naming v1.5版本，新增元素类型代码33（收益声明）至BRD有效代码列表
2.02026-02-08完全重写：新增YAML前置元数据、集成doc-naming（BRD-E019/E020/E021）、更新章节结构至18个章节、修复带编号前缀的文件路径、新增PRD就绪评分验证
1.02025-01-06初始版本（采用已过时的12章节结构）