ADR 编写

概述

依据 MADR 模板生成架构决策记录（ADR），并进行系统性完整性检查。

快速参考

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  序列号生成  │ ──▶ │    探索上下文   │ ──▶ │    填充内容    │
│  （获取下一个  │     │  （上下文、     │     │  （模板各章节） │
│   序号）      │     │   相关 ADR）    │     │              │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │    验证     │
       │                                 │  （DoD 检查清单）│
       └─────────────────────────────────│              │
                                         └─────────────┘

适用场景

• 根据提取的需求文档化架构决策
• 将会议纪要或讨论内容转化为正式 ADR
• 从 PR 讨论中记录技术选型决策
• 从设计文档中生成决策记录

工作流

准入门控（客观通过条件）

仅当满足 通过条件 时，方可进入下一步。这些条件以可验证的产出物替代了“我已探索”/“我已验证”等主观陈述。

步骤 1：获取序列号

若已预先分配编号（例如，由 /beagle:write-adr 在并行写入时调用）：

• 直接使用预分配的编号
• 请勿调用脚本——此举可避免并行执行时产生重复编号

若未预先分配编号（独立使用）：

python scripts/next_adr_number.py

该命令输出下一个可用的 ADR 编号（例如：0003）。

如需并行分配（由父级命令调用）：

python scripts/next_adr_number.py --count 3
# 输出：0003、0004、0005（每行一个）

步骤 2：探索上下文

动笔前，需收集额外上下文信息：

1. 关联代码 —— 定位受该决策影响的实现部分
2. 现有 ADR —— 查阅 docs/adrs/ 目录，寻找相关或已被取代的决策记录
3. 讨论来源 —— PR、Issue 或决策中引用的文档

准入门控：必须先满足 准入门控（客观通过条件） 表中“步骤 2”行所列条件，方可进入步骤 3。

步骤 3：加载模板

加载 references/madr-template.md 文件，获取官方 MADR 结构。

步骤 4：填充各章节

根据你的决策数据，逐项填充模板各章节：

步骤 5：应用完成定义（Definition of Done）

加载 references/definition-of-done.md，并逐项校验 E.C.A.D.R. 准则：

• Explicit problem statement（明确的问题陈述）
• Comprehensive options analysis（全面的方案分析）
• Actionable decision（可执行的决策）
• Documented consequences（已记录的影响）
• Reviewable by stakeholders（利益相关方可审阅）

准入门控：必须先满足 准入门控（客观通过条件） 表中“步骤 5”行所列条件，方可进入步骤 6（对缺失数据处使用 [INVESTIGATE: …] 标记）。

步骤 6：标记待调查项

对于当前数据不足以填充的章节，插入待调查提示：

* [INVESTIGATE: Review PR #42 discussion for additional drivers]
* [INVESTIGATE: Confirm with security team on compliance requirements]
* [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]

此类提示用于标识尚未完成的章节，便于后续跟进。

步骤 7：写入文件

重要：每个 ADR 文件必须以 YAML frontmatter 开头。

frontmatter 区块为强制要求，至少须包含以下字段：

---
status: draft
date: YYYY-MM-DD
---

完整 frontmatter 示例：

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
consulted: []
informed: []
---

校验要求：写入文件前，请确认内容以 --- 开头，且其后为合法 YAML 格式的 frontmatter。若缺失 frontmatter，请在写入前补全。

准入门控：文件写入后，须满足 准入门控（客观通过条件） 表中“步骤 7”行所列条件（文件已落盘，且含合法 YAML frontmatter）。

保存至 docs/adrs/NNNN-slugified-title.md：

docs/adrs/0003-use-postgresql-for-user-data.md
docs/adrs/0004-adopt-event-sourcing-pattern.md
docs/adrs/0005-migrate-to-kubernetes.md

步骤 8：验证 frontmatter

写入完成后，请确认文件满足以下全部条件：

1. 首行为 ---
2. 包含 status: draft（或其他有效状态值）
3. 包含 date: YYYY-MM-DD，且日期为实际日期
4. frontmatter 以 --- 结束，其后紧接标题

文件命名规范

格式：NNNN-slugified-title.md

参考文件

• references/madr-template.md —— 官方 MADR 模板结构
• references/definition-of-done.md —— E.C.A.D.R. 质量准则

输出示例

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
---

# Use PostgreSQL for User Data Storage

## Context and Problem Statement

We need a database for user account data...

## Decision Drivers

* Data integrity requirements
* Query flexibility needs
* [INVESTIGATE: Confirm scaling projections with infrastructure team]

## Considered Options

* PostgreSQL
* MongoDB
* CockroachDB

## Decision Outcome

Chosen option: PostgreSQL, because...

## Consequences

### Good

* ACID compliance ensures data integrity

### Bad

* Requires more upfront schema design

### Neutral

* Team has moderate PostgreSQL experience