Back to Details

doc-adr-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-adr-validator

doc-adr-validator 文档ADR验证器

Validate Architecture Decision Records (ADR) against Layer 5 schema standards.
依据Layer 5 schema标准验证架构决策记录（ADR）。

Activation

触发时机

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

Validation Schema Reference

验证Schema参考

Schema: 
ai_dev_flow/ADR/ADR_SCHEMA.yaml
Layer: 5 Artifact Type: ADR
Schema: 
ai_dev_flow/ADR/ADR_SCHEMA.yaml
层级：5 工件类型：ADR

Validation Checklist

验证检查清单

0. Folder Structure Validation (BLOCKING)

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

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

1. Metadata Validation

1. 元数据验证

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

Required tags:
  - adr (or adr-template)
  - layer-5-artifact

Forbidden tag patterns:
  - "^architecture-decision$"
  - "^decision-record$"
  - "^adr-\\d{3}$"
yaml
必填自定义字段:
  - document_type: ["adr", "template"]
  - artifact_type: "ADR"
  - layer: 5
  - architecture_approaches: 数组格式
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

必填标签:
  - adr (或 adr-template)
  - layer-5-artifact

禁用标签格式:
  - "^architecture-decision$"
  - "^decision-record$"
  - "^adr-\\d{3}$"

2. Structure Validation

2. 结构验证

Document Parts:
  • PART 1: Decision Context and Requirements (Sections 1-6)
  • PART 2: Impact Analysis and Architecture (Sections 7-10)
  • PART 3: Implementation Strategy (Sections 11-13)
  • PART 4: Traceability and Documentation (Sections 14-15)
Required Sections:
  • Title (H1): 
    # ADR-NNN: Title
  • Section 1: Document Control
  • Section 2: Position in Development Workflow
  • Section 3: Status
  • Section 4: Context (Problem Statement, Background, Driving Forces, Constraints)
  • Section 5: Decision (Chosen Solution, Key Components, Implementation Approach)
  • Section 6: Requirements Satisfied
  • Section 7: Consequences (Positive, Negative Outcomes)
  • Section 8: Architecture Flow (Mermaid diagram)
  • Section 9: Implementation Assessment (Complexity, Dependencies)
  • Section 10: Impact Analysis
Optional Sections:
  • Section 11: Alternatives Considered
  • Section 12: Security Considerations
  • Section 13: Operational Considerations
  • Section 14: Traceability
  • Section 15: References
Document Control Required Fields:
  • Project Name
  • Document Version
  • Date
  • Document Owner
  • Prepared By
  • Status
File Naming: Pattern: 
ADR-NNN_descriptive_name.md
文档组成部分:
  • 第一部分：决策背景与需求（第1-6节）
  • 第二部分：影响分析与架构（第7-10节）
  • 第三部分：实施策略（第11-13节）
  • 第四部分：可追溯性与文档（第14-15节）
必填章节:
  • 标题（H1）：
    # ADR-NNN: 标题
  • 第1节：文档管控
  • 第2节：在开发流程中的定位
  • 第3节：状态
  • 第4节：背景（问题陈述、背景信息、驱动因素、约束条件）
  • 第5节：决策（选定方案、核心组件、实施方法）
  • 第6节：已满足的需求
  • 第7节：影响（正面、负面结果）
  • 第8节：架构流程（Mermaid图）
  • 第9节：实施评估（复杂度、依赖关系）
  • 第10节：影响分析
可选章节:
  • 第11节：备选方案考量
  • 第12节：安全考量
  • 第13节：运维考量
  • 第14节：可追溯性
  • 第15节：参考资料
文档管控必填字段:
  • 项目名称
  • 文档版本
  • 日期
  • 文档所有者
  • 编制人
  • 状态
文件命名规则: 格式：
ADR-NNN_描述性名称.md

3. Content Validation

3. 内容验证

Status Values:
  • Proposed
  • Accepted
  • Deprecated
  • Superseded
Context Subsections (Required):
  • 4.1 Problem Statement
  • 4.2 Background
  • 4.3 Driving Forces
  • 4.4 Constraints
Decision Subsections (Required):
  • 5.1 Chosen Solution
  • 5.2 Key Components
  • 5.3 Implementation Approach
Consequences Subsections (Required):
  • 7.1 Positive Outcomes
  • 7.2 Negative Outcomes
Architecture Flow:
  • Must contain Mermaid diagram
  • Allowed types: flowchart, sequenceDiagram, stateDiagram-v2
ADR-Ready Score:
  • Minimum threshold: 90%
  • Components: Problem statement, context, decision clarity, consequences, architecture diagram, implementation assessment, traceability
状态取值:
  • 提议中
  • 已通过
  • 已弃用
  • 已取代
背景子章节（必填）:
  • 4.1 问题陈述
  • 4.2 背景信息
  • 4.3 驱动因素
  • 4.4 约束条件
决策子章节（必填）:
  • 5.1 选定方案
  • 5.2 核心组件
  • 5.3 实施方法
影响子章节（必填）:
  • 7.1 正面结果
  • 7.2 负面结果
架构流程:
  • 必须包含Mermaid图
  • 允许的类型：flowchart、sequenceDiagram、stateDiagram-v2
ADR就绪度评分:
  • 最低阈值：90%
  • 评分组成：问题陈述、背景、决策清晰度、影响、架构图、实施评估、可追溯性

4. Traceability Validation

4. 可追溯性验证

Layer 5 Cumulative Tags:
  • @brd: BRD.NN.01.SS (required)
  • @prd: PRD.NN.07.SS (required)
  • @ears: EARS.NN.24.SS (required)
  • @bdd: BDD.NN.13.SS (required)
Downstream Expected:
  • SYS requirements
  • REQ documents
  • SPEC documents
Same-Type References:
  • @related-adr: ADR-NN
  • @supersedes: ADR-NN
  • @depends-adr: ADR-NN
Layer5 累积标签:
  • @brd: BRD.NN.01.SS（必填）
  • @prd: PRD.NN.07.SS（必填）
  • @ears: EARS.NN.24.SS（必填）
  • @bdd: BDD.NN.13.SS（必填）
预期下游关联:
  • SYS需求文档
  • REQ文档
  • SPEC文档
同类型引用:
  • @related-adr: ADR-NN
  • @supersedes: ADR-NN
  • @depends-adr: ADR-NN

Error Codes

错误代码

CodeSeverityDescription
ADR-E001errorMissing required tag 'adr'
ADR-E002errorMissing required tag 'layer-5-artifact'
ADR-E003errorInvalid document_type
ADR-E004errorInvalid architecture_approaches format
ADR-E005errorForbidden tag pattern detected
ADR-E006errorMissing required section
ADR-E007errorMultiple H1 headings detected
ADR-E008errorMissing Context section (Section 4)
ADR-E009errorMissing Decision section (Section 5)
ADR-E010errorMissing Consequences section (Section 7)
ADR-E011errorContext missing Problem Statement subsection
ADR-E012errorDecision missing Chosen Solution subsection
ADR-E013errorConsequences missing outcomes
ADR-E014warningFile name does not match format
ADR-W001warningMissing Architecture Flow Mermaid diagram
ADR-W002warningContext missing Constraints subsection
ADR-W003warningMissing upstream tags (@prd, @ears, @bdd)
ADR-W004warningImplementation Assessment missing Complexity
ADR-W005warningSYS-Ready Score below 90%
ADR-W006warningRequirements Satisfied table missing
ADR-I001infoConsider adding Alternatives Considered
ADR-I002infoConsider adding Security Considerations
ADR-I003infoConsider adding Rollback Plan
代码严重程度描述
ADR-E001错误缺失必填标签'adr'
ADR-E002错误缺失必填标签'layer-5-artifact'
ADR-E003错误无效的document_type
ADR-E004错误architecture_approaches格式无效
ADR-E005错误检测到禁用标签格式
ADR-E006错误缺失必填章节
ADR-E007错误检测到多个H1标题
ADR-E008错误缺失背景章节（第4节）
ADR-E009错误缺失决策章节（第5节）
ADR-E010错误缺失影响章节（第7节）
ADR-E011错误背景章节缺失问题陈述子章节
ADR-E012错误决策章节缺失选定方案子章节
ADR-E013错误影响章节缺失结果子章节
ADR-E014警告文件名不符合格式要求
ADR-W001警告缺失架构流程Mermaid图
ADR-W002警告背景章节缺失约束条件子章节
ADR-W003警告缺失上游标签（@prd、@ears、@bdd）
ADR-W004警告实施评估缺失复杂度分析
ADR-W005警告SYS就绪度评分低于90%
ADR-W006警告缺失已满足需求表格
ADR-I001信息建议添加备选方案考量章节
ADR-I002信息建议添加安全考量章节
ADR-I003信息建议添加回滚计划

Validation Commands

验证命令

bash
undefined
bash
undefined

Validate single ADR document

验证单个ADR文档

python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ADR-001_example.md
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ADR-001_example.md

Validate all ADR documents

验证所有ADR文档

python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/

Check with verbose output

查看详细输出

python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ --verbose
undefined
python ai_dev_flow/scripts/validate_adr.py docs/05_ADR/ --verbose
undefined

Validation Workflow

验证流程

  1. Parse YAML frontmatter
  2. Check required metadata fields
  3. Validate tag taxonomy
  4. Verify 4-part structure
  5. Validate required sections (1-10)
  6. Check Context subsections
  7. Check Decision subsections
  8. Check Consequences subsections
  9. Verify Mermaid diagram presence
  10. Validate upstream references
  11. Calculate SYS-Ready Score
  12. Verify file naming convention
  13. Generate validation report
  1. 解析YAML前置元数据
  2. 检查必填元数据字段
  3. 验证标签分类
  4. 验证四部分结构
  5. 验证必填章节（1-10节）
  6. 检查背景子章节
  7. 检查决策子章节
  8. 检查影响子章节
  9. 验证Mermaid图是否存在
  10. 验证上游引用
  11. 计算SYS就绪度评分
  12. 验证文件命名规范
  13. 生成验证报告

Integration

集成方式

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

Output Format

输出格式

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

Structure:
- Context: Complete/Incomplete
- Decision: Complete/Incomplete
- Consequences: Complete/Incomplete
- Architecture Flow: Present/Missing

Errors: N
Warnings: N
Info: N

[Details listed by severity]
ADR验证报告
=====================
文档: ADR-001_example.md
状态: 通过/失败

结构:
- 背景: 完整/不完整
- 决策: 完整/不完整
- 影响: 完整/不完整
- 架构流程: 存在/缺失

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

[按严重程度列出详细内容]

Version History

版本历史

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