doc-adr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

doc-adr

Purpose

目的

Create Architecture Decision Records (ADR) - Layer 5 artifact in the SDD workflow that documents architectural decisions with rationale, alternatives, and consequences.

Layer: 5

Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4)

Downstream Artifacts: SYS (Layer 6), REQ (Layer 7), Code (Execution Layer)

创建架构决策记录（ADR）——SDD流程中的第5层工件，用于记录架构决策及其依据、备选方案和影响。

层级: 5

上游工件: BRD（第1层）、PRD（第2层）、EARS（第3层）、BDD（第4层）

下游工件: SYS（第6层）、REQ（第7层）、代码（执行层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:

List existing upstream artifacts:

bash

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

Reference only existing documents in traceability tags
Use
null
only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like
```
BRD-XXX
```
or
```
TBD
```
Do NOT create missing upstream artifacts - skip functionality instead

Before creating ADR, read:

Shared Standards:

.claude/skills/doc-flow/SHARED_CONTENT.md

Technology Stack:
```
docs/ADR/ADR-00_technology_stack.md
```
(approved technologies)
Upstream BRD, PRD: Read Architecture Decision Requirements sections
Template:
```
ai_dev_flow/05_ADR/ADR-MVP-TEMPLATE.md
```

Creation Rules:

ai_dev_flow/05_ADR/ADR_CREATION_RULES.md

Validation Rules:

ai_dev_flow/05_ADR/ADR_VALIDATION_RULES.md

在创建本文档前，你必须：

列出已有的上游工件:

bash

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ 2>/dev/null

仅引用已存在的文档作为可追溯标签
仅当对应类型的上游工件确实不存在时，才使用
```
null
```
禁止使用
```
BRD-XXX
```
或
```
TBD
```
这类占位符
不要创建缺失的上游工件——而是跳过相关功能

创建ADR前，请阅读：

共享标准:

.claude/skills/doc-flow/SHARED_CONTENT.md

技术栈:
```
docs/ADR/ADR-00_technology_stack.md
```
（已批准的技术列表）
上游BRD、PRD: 阅读其中的架构决策需求章节
模板:
```
ai_dev_flow/05_ADR/ADR-MVP-TEMPLATE.md
```

创建规则:

ai_dev_flow/05_ADR/ADR_CREATION_RULES.md

验证规则:

ai_dev_flow/05_ADR/ADR_VALIDATION_RULES.md

When to Use This Skill

何时使用本技能

Use

doc-adr

when:

Have identified architectural topics in BRD/PRD Architecture Decision Requirements sections
Need to document technology choices with rationale
Evaluating alternatives for architectural patterns
Making decisions with long-term impact
You are at Layer 5 of the SDD workflow

当出现以下情况时使用

doc-adr

从BRD/PRD的架构决策需求章节中识别出需要决策的主题
需要记录技术选型及其依据
评估架构模式的备选方案
制定具有长期影响的决策
当前处于SDD流程的第5层

ADR Document Categories

ADR文档分类

Category	Filename Pattern	Validation Level	Description
Standard ADR	`ADR-NN_{decision_topic}.md`	Full (7 checks)	Architecture decision records
ADR-REF	`ADR-REF-NN_{slug}.md`	Reduced (4 checks)	Supplementary reference documents

分类	文件名格式	验证级别	描述
标准ADR	`ADR-NN_{decision_topic}.md`	完整（7项检查）	架构决策记录
ADR-REF	`ADR-REF-NN_{slug}.md`	简化（4项检查）	补充参考文档

Reserved ID Exemption (ADR-00_*)

保留ID豁免（ADR-00_*）

Scope: Documents with reserved ID

are FULLY EXEMPT from validation.

Pattern:

ADR-00_*.md

Document Types: Index, Traceability matrix, Glossaries, Registries, Checklists

Validation Behavior: Skip all checks when filename matches

ADR-00_*

pattern.

范围: 以保留ID

命名的文档完全豁免验证。

格式:

ADR-00_*.md

文档类型: 索引、可追溯性矩阵、术语表、注册表、检查清单

验证行为: 当文件名匹配

ADR-00_*

格式时，跳过所有检查。

ADR-Specific Guidance

ADR专项指南

1. Four-Part ADR Structure (17 Sections Total)

1. 四部分ADR结构（共17个章节）

Full Template: See

ai_dev_flow/ADR/ADR-TEMPLATE.md

for complete 17-section structure.

Part 1 - Decision Context and Requirements (Sections 1-6):

Document Control, Workflow Position, Status, Context, Decision, Requirements Satisfied

Part 2 - Impact Analysis and Architecture (Sections 7-12):

Consequences, Architecture Flow, Implementation Assessment, Impact Analysis, Verification, Alternatives Considered

Part 3 - Implementation and Operations (Sections 13-15):

Security, Related Decisions, Implementation Notes

Part 4 - Traceability and Documentation (Sections 16-17):

Traceability, References

完整模板: 查看

ai_dev_flow/ADR/ADR-TEMPLATE.md

获取完整的17章节结构。

第一部分 - 决策背景与需求（第1-6章）:

文档控制、流程定位、状态、背景、决策、已满足的需求

第二部分 - 影响分析与架构（第7-12章）:

影响、架构流程、实施评估、影响分析、验证、备选方案考量

第三部分 - 实施与运维（第13-15章）:

安全性、相关决策、实施说明

第四部分 - 可追溯性与文档（第16-17章）:

可追溯性、参考资料

2. ADR Lifecycle States

2. ADR生命周期状态

Proposed: Decision under consideration

Still evaluating alternatives
Seeking stakeholder feedback
Not yet implemented

Accepted: Decision approved and active

Chosen as the path forward
Implementation can proceed
Should be followed by all

Deprecated: Decision no longer recommended

Better alternative found
Context changed
Not deleted (historical record)

Superseded by ADR-XXX: Replaced by newer decision

Links to replacing ADR
Explains why replaced
Maintains audit trail

提议中: 决策正在考量中

仍在评估备选方案
寻求利益相关者反馈
尚未实施

已接受: 决策已获批并生效

被选为前进方向
可开始实施
所有相关人员需遵循

已弃用: 决策不再被推荐

已找到更优替代方案
背景已变化
不删除（作为历史记录保留）

被ADR-XXX取代: 被新决策替代

链接至替代的ADR
说明被替代的原因
保留审计追踪

3. SYS-Ready Scoring System

3. SYS就绪评分系统

Purpose: Measures ADR maturity and readiness for progression to System Requirements (SYS) phase.

Format in Document Control:

markdown

| **SYS-Ready Score** | ✅ 95% (Target: ≥90%) |

Status and SYS-Ready Score Mapping:

SYS-Ready Score	Required Status
≥90%	Accepted
70-89%	Proposed
<70%	Draft

Scoring Criteria:

Decision Completeness (30%): Context/Decision/Consequences/Alternatives process
Architecture Clarity (35%): Mermaid diagrams (REQUIRED - no text-based diagrams), component responsibilities, cross-cutting concerns
Implementation Readiness (20%): Complexity assessment, dependencies, rollback strategies
Verification Approach (15%): Testing strategy, success metrics, operational readiness

Quality Gate: Score <90% blocks SYS artifact creation.

目的: 衡量ADR的成熟度以及进入系统需求（SYS）阶段的就绪程度。

文档控制中的格式:

markdown

| **SYS就绪评分** | ✅ 95%（目标: ≥90%） |

状态与SYS就绪评分映射:

SYS就绪评分	要求的状态
≥90%	已接受
70-89%	提议中
<70%	草稿

评分标准:

决策完整性（30%）: 背景/决策/影响/备选方案流程
架构清晰度（35%）: Mermaid图表（必填 - 禁止使用纯文本图表）、组件职责、横切关注点
实施就绪度（20%）: 复杂度评估、依赖关系、回滚策略
验证方法（15%）: 测试策略、成功指标、运维就绪度

质量门禁: 评分<90%会阻止SYS工件的创建。

4. Element ID Format (MANDATORY)

4. 元素ID格式（必填）

Pattern:

ADR.{DOC_NUM}.{ELEM_TYPE}.{SEQ}

(4 segments, dot-separated)

Element Type	Code	Example
Decision	10	ADR.02.10.01
Alternative	12	ADR.02.12.01
Consequence	13	ADR.02.13.01

REMOVED PATTERNS - Do NOT use legacy formats:

❌
```
DEC-XXX
```
→ Use
```
ADR.NN.10.SS
```
❌
```
ALT-XXX
```
→ Use
```
ADR.NN.12.SS
```
❌
```
CON-XXX
```
→ Use
```
ADR.NN.13.SS
```

Reference: ID_NAMING_STANDARDS.md

格式:

ADR.{DOC_NUM}.{ELEM_TYPE}.{SEQ}

（4个段，以点分隔）

元素类型	代码	示例
决策	10	ADR.02.10.01
备选方案	12	ADR.02.12.01
影响	13	ADR.02.13.01

已废弃格式 - 禁止使用旧格式:

❌
```
DEC-XXX
```
→ 改用
```
ADR.NN.10.SS
```
❌
```
ALT-XXX
```
→ 改用
```
ADR.NN.12.SS
```
❌
```
CON-XXX
```
→ 改用
```
ADR.NN.13.SS
```

参考: ID_NAMING_STANDARDS.md

5. Threshold Management

5. 阈值管理

Dual Role: ADR documents both reference and define thresholds.

Reference platform-wide thresholds from PRD threshold registry:

yaml

performance:
  - "@threshold: PRD.NN.perf.api.p95_latency"
sla:
  - "@threshold: PRD.NN.sla.uptime.target"

Define architecture-specific thresholds unique to this decision:

yaml

circuit_breaker:
  - "@threshold: ADR.NN.circuit.failure_threshold"
  - "@threshold: ADR.NN.circuit.recovery_timeout"
retry:
  - "@threshold: ADR.NN.retry.max_attempts"
caching:
  - "@threshold: ADR.NN.cache.ttl_seconds"

双重作用: ADR既引用阈值也定义阈值。

引用PRD阈值注册表中的平台级阈值:

yaml

performance:
  - "@threshold: PRD.NN.perf.api.p95_latency"
sla:
  - "@threshold: PRD.NN.sla.uptime.target"

定义本决策特有的架构级阈值:

yaml

circuit_breaker:
  - "@threshold: ADR.NN.circuit.failure_threshold"
  - "@threshold: ADR.NN.circuit.recovery_timeout"
retry:
  - "@threshold: ADR.NN.retry.max_attempts"
caching:
  - "@threshold: ADR.NN.cache.ttl_seconds"

6. File Size Limits

6. 文件大小限制

Target: 300-500 lines per file
Maximum: 600 lines per file (absolute)
If document approaches/exceeds limits, split into section files

目标: 每个文件300-500行
最大值: 每个文件最多600行（绝对限制）
如果文档接近/超过限制，拆分为多个章节文件

Tag Format Convention (By Design)

标签格式约定（设计如此）

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR	Technical artifacts - references to files/documents
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical artifacts - references to elements inside documents

Key Distinction:

@adr: ADR-033

→ Points to the document

ADR-033_risk_limit_enforcement.md

```
@brd: BRD.17.01.30
```
→ Points to element 01.30 inside document
```
BRD-017.md
```

符号	格式	适用工件	用途
短横线	TYPE-NN	ADR, SPEC, CTR	技术工件 - 指向文件/文档的引用
点	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	分层工件 - 指向文档内部元素的引用

关键区别:

@adr: ADR-033

→ 指向文档

ADR-033_risk_limit_enforcement.md

```
@brd: BRD.17.01.30
```
→ 指向文档
```
BRD-017.md
```
内部的元素01.30

Cumulative Tagging Requirements

累积标签要求

Layer 5 (ADR): Must include tags from Layers 1-4 (BRD, PRD, EARS, BDD)

Tag Count: 4 tags (@brd, @prd, @ears, @bdd)

Format:

markdown

undefined

第5层（ADR）: 必须包含来自第1-4层（BRD、PRD、EARS、BDD）的标签

标签数量: 4个标签（@brd, @prd, @ears, @bdd）

格式:

markdown

undefined

Traceability

可追溯性

Required Tags (Cumulative Tagging Hierarchy - Layer 5):

@brd: BRD.01.01.30 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01


**Upstream Sources**:
- [BRD-01](../BRD/BRD-01_platform.md#BRD-01) - Architecture Decision Requirements
- [PRD-01](../PRD/PRD-01_integration.md#PRD-01) - Product requirements
- [EARS-01](../EARS/EARS-01_risk.md#EARS-01) - Formal requirements (EARS type code: 25)
- [BDD-01](../BDD/BDD-01_limits/) - Test scenarios (BDD scenario type code: 14)

必填标签（累积标签层级 - 第5层）:

@brd: BRD.01.01.30 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01


**上游来源**:
- [BRD-01](../BRD/BRD-01_platform.md#BRD-01) - 架构决策需求
- [PRD-01](../PRD/PRD-01_integration.md#PRD-01) - 产品需求
- [EARS-01](../EARS/EARS-01_risk.md#EARS-01) - 正式需求（EARS类型代码:25）
- [BDD-01](../BDD/BDD-01_limits/) - 测试场景（BDD场景类型代码:14）

Upstream/Downstream Artifacts

上游/下游工件

Upstream Sources:

BRD (Layer 1) - Architecture Decision Requirements section
PRD (Layer 2) - Architecture Decision Requirements section
EARS (Layer 3) - Formal requirements constraints
BDD (Layer 4) - Test scenarios validating decision

Downstream Artifacts:

SYS (Layer 6) - System requirements implementing decision
REQ (Layer 7) - Atomic requirements following decision
Code (Execution Layer) - Implementation per decision

Upstream-Only Traceability Policy:

The ADR traceability matrix tracks ADRs and their upstream sources (BRD, PRD, EARS, BDD) only. Downstream documents (SYS, REQ, SPEC) track their own upstream references to ADRs—the ADR matrix does NOT maintain downstream links.

Same-Type Document Relationships (conditional):

```
@related-adr: ADR-NN
```
- ADRs sharing architectural context
```
@depends-adr: ADR-NN
```
- ADR that must be decided first

上游来源:

BRD（第1层） - 架构决策需求章节
PRD（第2层） - 架构决策需求章节
EARS（第3层） - 正式需求约束
BDD（第4层） - 验证决策的测试场景

下游工件:

SYS（第6层） - 实现决策的系统需求
REQ（第7层） - 遵循决策的原子需求
代码（执行层） - 依据决策的实现

仅上游可追溯性政策:

ADR可追溯性矩阵仅追踪ADR及其上游来源（BRD、PRD、EARS、BDD）。下游文档（SYS、REQ、SPEC）自行维护其对ADR的上游引用——ADR矩阵不维护下游链接。

同类型文档关系（可选）:

```
@related-adr: ADR-NN
```
- 共享架构背景的ADR
```
@depends-adr: ADR-NN
```
- 必须先完成决策的ADR

Creation Process

创建流程

Step 1: Identify Decision Topic

步骤1: 识别决策主题

From BRD/PRD Architecture Decision Requirements sections, identify topic needing decision.

从BRD/PRD的架构决策需求章节中，识别需要决策的主题。

Step 2: Read Technology Stack

步骤2: 查阅技术栈

Check

docs/ADR/ADR-00_technology_stack.md

for approved technologies.

查看

docs/ADR/ADR-00_technology_stack.md

获取已批准的技术列表。

Step 3: Reserve ID Number

步骤3: 预留ID编号

Check

docs/ADR/

for next available ID number (e.g., ADR-01, ADR-33).

ID Numbering Convention: Start with 2 digits and expand only as needed.

✅ Correct: ADR-01, ADR-99, ADR-102
❌ Incorrect: ADR-001, ADR-033 (extra leading zero not required)

Special IDs:

ADR-000: Reserved for Technology Stack reference
ADR-01 onwards: Regular decision records

查看

docs/ADR/

获取下一个可用的ID编号（例如ADR-01、ADR-33）。

ID编号约定: 从2位数字开始，仅在需要时扩展位数。

✅ 正确格式: ADR-01, ADR-99, ADR-102
❌ 错误格式: ADR-001, ADR-033（不需要额外的前导零）

特殊ID:

ADR-000: 预留用于技术栈参考文档
ADR-01及以后: 常规决策记录

Step 4: Create ADR Folder and Files

步骤4: 创建ADR文件夹和文件

Folder structure (DEFAULT - nested folder per document):

Create folder:
```
docs/ADR/ADR-NN_{slug}/
```
(folder slug MUST match index file slug)

Create index file:

docs/ADR/ADR-NN_{slug}/ADR-NN.0_{slug}_index.md

Create section files:

docs/ADR/ADR-NN_{slug}/ADR-NN.S_{section_type}.md

Example (Section-Based Pattern - DEFAULT):

docs/ADR/ADR-033_database_selection/
├── ADR-033.0_database_selection_index.md
├── ADR-033.1_context.md
├── ADR-033.2_decision.md
└── ADR-033.3_consequences.md

OPTIONAL (for small documents <25KB):

docs/ADR/ADR-NN_{slug}.md

(monolithic)

文件夹结构（默认 - 每个文档对应一个嵌套文件夹）:

创建文件夹:
```
docs/ADR/ADR-NN_{slug}/
```
（文件夹slug必须与索引文件slug匹配）

创建索引文件:

docs/ADR/ADR-NN_{slug}/ADR-NN.0_{slug}_index.md

创建章节文件:

docs/ADR/ADR-NN_{slug}/ADR-NN.S_{section_type}.md

示例（基于章节的格式 - 默认）:

docs/ADR/ADR-033_database_selection/
├── ADR-033.0_database_selection_index.md
├── ADR-033.1_context.md
├── ADR-033.2_decision.md
└── ADR-033.3_consequences.md

可选格式（适用于小于25KB的小型文档）:

docs/ADR/ADR-NN_{slug}.md

（单文件）

Step 5: Fill Document Control Section

步骤5: 填写文档控制章节

Complete all required metadata fields and initialize Document Revision History table.

Required Fields (7 mandatory):

Project Name, Document Version, Date, Document Owner, Prepared By, Status, SYS-Ready Score

完成所有必填元数据字段，并初始化文档修订历史表。

必填字段（7项）:

项目名称、文档版本、日期、文档所有者、编制人、状态、SYS就绪评分

Step 6: Document Context (Section 4)

步骤6: 记录背景（第4章）

Context Section: Explain the problem and factors:

What issue are we addressing?
What constraints exist?
What requirements drive this decision?
Reference upstream BRD/PRD sections

Section 4.1 Problem Statement includes inherited content:

Business Driver (from BRD §7.2)
Business Constraints (from BRD §7.2)
Technical Options Evaluated (from PRD §18)
Evaluation Criteria (from PRD §18)

背景章节: 解释问题和相关因素:

我们要解决什么问题？
存在哪些约束？
哪些需求驱动了这个决策？
引用上游BRD/PRD章节

第4.1节问题陈述包含继承内容:

业务驱动因素（来自BRD第7.2节）
业务约束（来自BRD第7.2节）
评估的技术选项（来自PRD第18节）
评估标准（来自PRD第18节）

Step 7: State Decision (Section 5)

步骤7: 陈述决策（第5章）

Decision Section: Clear, concise statement:

What are we choosing to do?
How will it be implemented?
Reference technology stack (ADR-000) if applicable

决策章节: 清晰、简洁的陈述:

我们选择做什么？
如何实施？
如有必要，引用技术栈（ADR-000）

Step 8: Analyze Consequences (Section 7)

步骤8: 分析影响（第7章）

Consequences Section:

Positive: Benefits and advantages
Negative: Drawbacks and limitations
Risks: Potential issues and mitigations

影响章节:

正面: 收益和优势
负面: 缺点和限制
风险: 潜在问题和缓解措施

Step 9: Document Alternatives (Section 12)

步骤9: 记录备选方案（第12章）

Alternatives Considered: For each alternative:

Name and description
Pros and cons
Why rejected
Fit Score (Poor/Good/Better)

备选方案考量: 针对每个备选方案:

名称和描述
优缺点
被拒绝的原因
适配评分（差/好/更好）

Step 10: Define Verification (Section 11)

步骤10: 定义验证方法（第11章）

Verification Section: How to validate decision:

BDD scenarios that test it
Success metrics
Performance benchmarks

验证章节: 如何验证决策:

测试该决策的BDD场景
成功指标
性能基准

Step 11: Add Relations (Section 14)

步骤11: 添加关联关系（第14章）

Related Decisions Section:

Supersedes: Which ADR this replaces
Related to: Connected ADRs
Influences: Which SYS/REQ depend on this

相关决策章节:

取代: 本ADR取代了哪些ADR
相关: 关联的ADR
影响: 哪些SYS/REQ依赖本决策

Step 12: Add Cumulative Tags (Section 16.6)

步骤12: 添加累积标签（第16.6节）

Include @brd, @prd, @ears, @bdd tags (Layers 1-4).

包含@brd、@prd、@ears、@bdd标签（第1-4层）。

Step 13: Create/Update Traceability Matrix

步骤13: 创建/更新可追溯性矩阵

MANDATORY: Update

docs/ADR/ADR-00_TRACEABILITY_MATRIX.md

Add ADR entry with upstream sources only (BRD, PRD, EARS, BDD)
Do NOT add downstream links (SYS, REQ track their own references to ADRs)

必填: 更新

docs/ADR/ADR-00_TRACEABILITY_MATRIX.md

添加ADR条目，仅包含上游来源（BRD、PRD、EARS、BDD）
不要添加下游链接（SYS、REQ自行维护对ADR的引用）

Step 14: Commit Changes

步骤14: 提交变更

Commit ADR and traceability matrix.

提交ADR和可追溯性矩阵。

Validation

验证

Validation Checks (8 Total)

验证检查（共8项）

Check	Type	Description
CHECK 1	Error	Required Document Control Fields (7 fields)
CHECK 2	Error	ADR Structure Completeness (required sections)
CHECK 3	Error	SYS-Ready Score Validation (format, threshold)
CHECK 4	Error	Upstream Traceability Tags (@brd, @prd, @ears, @bdd)
CHECK 5	Warning	Decision Quality Assessment
CHECK 6	Warning	Architecture Documentation (Mermaid diagrams)
CHECK 7	Warning	Implementation Readiness
CHECK 8	Error	Element ID Format Compliance (unified 4-segment)

检查项	类型	描述
检查1	错误	必填文档控制字段（7个字段）
检查2	错误	ADR结构完整性（必填章节）
检查3	错误	SYS就绪评分验证（格式、阈值）
检查4	错误	上游可追溯性标签（@brd, @prd, @ears, @bdd）
检查5	警告	决策质量评估
检查6	警告	架构文档（Mermaid图表）
检查7	警告	实施就绪度
检查8	错误	元素ID格式合规性（统一4段格式）

Validation Tiers

验证层级

Tier	Type	Exit Code	Action
Tier 1	Error	1	Must fix before commit
Tier 2	Warning	0	Recommended to fix
Tier 3	Info	0	No action required

层级	类型	退出码	操作
层级1	错误	1	提交前必须修复
层级2	警告	0	建议修复
层级3	信息	0	无需操作

Automated Validation

自动化验证

bash

undefined

bash

undefined

Per-document validation (Phase 1)

单文档验证（阶段1）

python ai_dev_flow/scripts/validate_cross_document.py --document docs/ADR/ADR-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all ADR documents complete

层级验证（阶段2）- 所有ADR文档完成后运行

python ai_dev_flow/scripts/validate_cross_document.py --layer ADR --auto-fix

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact ADR-NN --expected-layers brd,prd,ears,bdd --strict

undefined

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact ADR-NN --expected-layers brd,prd,ears,bdd --strict

undefined

Manual Checklist

手动检查清单

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（必填 - 无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.

关键: 文档创建完成后立即执行此验证循环。在验证通过前，不要继续创建下一个文档。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

循环:
  1. 运行: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复: 回到循环（重新验证）
  3. 如果警告已修复: 回到循环（重新验证）
  4. 如果存在无法修复的问题: 记录问题以便手动审查，继续
  5. 如果验证通过: 标记为已验证，继续

Layer-Specific Upstream Requirements

层级专属上游需求

This Layer	Required Upstream Tags	Count
ADR (Layer 5)	@brd, @prd, @ears, @bdd	4 tags

当前层级	必填上游标签	数量
ADR（第5层）	@brd, @prd, @ears, @bdd	4个标签

Auto-Fix Actions (No Confirmation Required)

自动修复操作（无需确认）

Issue	Fix Action
Missing @brd/@prd/@ears/@bdd tag	Add with upstream document reference
Invalid tag format	Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Legacy element ID (DEC-XXX, ALT-XXX, CON-XXX)	Convert to ADR.NN.TT.SS format
Broken link	Recalculate path from current location
Missing traceability section	Insert from template

问题	修复操作
缺失@brd/@prd/@ears/@bdd标签	添加上游文档引用
标签格式无效	修正为TYPE.NN.TT.SS（4段）或TYPE-NN格式
旧元素ID（DEC-XXX, ALT-XXX, CON-XXX）	转换为ADR.NN.TT.SS格式
链接失效	根据当前位置重新计算路径
缺失可追溯性章节	从模板插入

Validation Codes Reference

验证代码参考

Code	Description	Severity
XDOC-001	Referenced requirement ID not found	ERROR
XDOC-002	Missing cumulative tag	ERROR
XDOC-003	Upstream document not found	ERROR
XDOC-006	Tag format invalid	ERROR
XDOC-007	Gap in cumulative tag chain	ERROR
XDOC-009	Missing traceability section	ERROR

代码	描述	严重程度
XDOC-001	引用的需求ID未找到	错误
XDOC-002	缺失累积标签	错误
XDOC-003	上游文档未找到	错误
XDOC-006	标签格式无效	错误
XDOC-007	累积标签链存在缺口	错误
XDOC-009	缺失可追溯性章节	错误

Quality Gate

质量门禁

Blocking: YES - Cannot proceed to SYS creation until Phase 1 validation passes with 0 errors.

阻塞: 是 - 阶段1验证通过且无错误前，无法开始创建SYS工件。

Common Pitfalls

常见陷阱

No alternatives: Must document why other options rejected
Missing technology stack check: Always check ADR-000 first
Vague consequences: Be specific about impacts
No verification: Must define how to validate decision
Missing cumulative tags: Layer 5 must include Layers 1-4 tags
Legacy element IDs: Use ADR.NN.TT.SS not DEC-XXX/ALT-XXX/CON-XXX
Wrong SYS-Ready Score format: Must include ✅ emoji and percentage

未记录备选方案: 必须说明为何拒绝其他选项
未检查技术栈: 始终先查看ADR-000
影响描述模糊: 需具体说明影响
未定义验证方法: 必须定义如何验证决策
缺失累积标签: 第5层必须包含第1-4层的标签
使用旧元素ID: 使用ADR.NN.TT.SS而非DEC-XXX/ALT-XXX/CON-XXX
SYS就绪评分格式错误: 必须包含✅表情和百分比

ADR-REF Reference Documents

ADR-REF参考文档

For supplementary documentation related to ADR artifacts:

Format:
```
ADR-REF-NNN_{slug}.md
```
Skill: Use
```
doc-ref
```
skill
Validation: Reduced (4 checks only)
Examples: Technology stack summaries, architecture overviews

针对与ADR工件相关的补充文档:

格式:
```
ADR-REF-NNN_{slug}.md
```
技能: 使用
```
doc-ref
```
技能
验证: 简化（仅4项检查）
示例: 技术栈摘要、架构概述

ADR-REF Reduced Validation

ADR-REF简化验证

Applicable Checks (4 total):

CHECK 1 (partial): Document Control Fields (required)
Document Revision History (required)
Status/Context sections only (required)
H1 ID match with filename (required)

Exempted (NO SCORES):

SYS-Ready Score: NOT APPLICABLE
Cumulative tags: NOT REQUIRED
CHECK 5-7: Decision quality, architecture, implementation (exempt)
All quality gates and downstream readiness metrics: EXEMPT

Purpose: ADR-REF documents are reference targets that other documents link to. They provide supporting information, context, or external references but do not define formal architecture decisions.

适用检查（共4项）:

检查1（部分）: 文档控制字段（必填）
文档修订历史（必填）
仅状态/背景章节（必填）
H1 ID与文件名匹配（必填）

豁免项（不适用）:

SYS就绪评分: 不适用
累积标签: 无需
检查5-7: 决策质量、架构、实施（豁免）
所有质量门禁和下游就绪指标: 豁免

目的: ADR-REF文档是其他文档链接的参考目标。它们提供支持信息、背景或外部参考，但不定义正式架构决策。

Next Skill

后续技能

After creating ADR, use:

doc-sys
- Create System Requirements (Layer 6)

The SYS will:

Implement ADR architectural decisions
Include
```
@brd
```
,
```
@prd
```
,
```
@ears
```
,
```
@bdd
```
,
```
@adr
```
tags (cumulative)
Define functional requirements and quality attributes
Translate ADR decisions into technical requirements

创建ADR后，使用:

doc-sys
- 创建系统需求（第6层）

SYS将:

实现ADR架构决策
包含
```
@brd
```
,
```
@prd
```
,
```
@ears
```
,
```
@bdd
```
,
```
@adr
```
标签（累积）
定义功能需求和质量属性
将ADR决策转换为技术需求

Related Resources

Quick Reference

快速参考

ADR Purpose: Document architectural decisions with rationale

Layer: 5

Tags Required: @brd, @prd, @ears, @bdd (4 tags)

Format: Four-Part Structure (17 sections)

SYS-Ready Score: ≥90% required for "Accepted" status

Element ID Format: ADR.NN.TT.SS (Decision=10, Alternative=12, Consequence=13)

File Size: 300-500 lines target, 600 max

Lifecycle States: Proposed → Accepted → Deprecated/Superseded

Critical: Always check ADR-000 Technology Stack first

Next: doc-sys

ADR目的: 记录架构决策及其依据

层级: 5

必填标签: @brd, @prd, @ears, @bdd（4个标签）

格式: 四部分结构（17个章节）

SYS就绪评分: "已接受"状态要求≥90%

元素ID格式: ADR.NN.TT.SS（决策=10，备选方案=12，影响=13）

文件大小: 目标300-500行，最大600行

生命周期状态: 提议中 → 已接受 → 已弃用/被取代

关键: 始终先查看ADR-000技术栈

后续: doc-sys