adr-writing

ADR 编写

概述

按照 MADR 模板生成架构决策记录（ADR），并系统地检查内容是否完整。

快速参考

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  SEQUENCE   │ ──▶ │   EXPLORE    │ ──▶ │    FILL     │
│  (get next  │     │  (context,   │     │  (template  │
│   number)   │     │   ADRs)      │     │   sections) │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │   VERIFY    │
       │                                 │  (DoD       │
       └─────────────────────────────────│   checklist)│
                                         └─────────────┘

使用场景

• 记录从提取的需求中得出的架构决策
• 将会议记录或讨论内容整理为正式的 ADR
• 记录 PR 讨论中的技术选择
• 根据设计文档创建决策记录

工作流

门槛（客观通过条件）

只有在满足通过条件后，才能进入下一步。这些条件以可检查的产物取代“我已探索”或“我已验证”这类表述。

之后	通过条件
第 2 步	**通过：**你有一份书面列表（可以是草稿前言、临时笔记或 ADR 正文中的项目符号），列出你为查找相关或已被取代的 ADR 而查阅的 docs/adrs/ 下的 ≥0 个路径，或者你在检查后明确记录 docs/adrs/ 不存在或为空。并且你列出 ≥1 个相关代码的仓库路径，或者标注 N/A 并说明理由（一句话）。
第 5 步	**通过：**对于 references/definition-of-done.md 中的 E、C、A、D、R，草稿均满足对应字母的检查清单，或者包含针对该项差距的 [INVESTIGATE: …] 标记。
第 7 步	**通过：**ADR 文件存在于 docs/adrs/NNNN-slugified-title.md，且读取文件后可确认第 1 行是 ---，并且 frontmatter 可解析为 YAML。

第 1 步：获取序号

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

• 直接使用预先分配的序号
• 不要调用脚本——这可以避免并行执行时产生重复序号

如果没有预先分配序号（独立使用）：

python scripts/next_adr_number.py

此命令会输出下一个可用的 ADR 序号（例如，0003）。

用于并行分配（由父命令调用）：

python scripts/next_adr_number.py --count 3
# Outputs: 0003, 0004, 0005 (one per line)

第 2 步：探索上下文

编写前，收集更多上下文：

1. 相关代码——查找受此决策影响的实现
2. 现有 ADR——检查 docs/adrs/ 中是否有相关或已被取代的决策
3. 讨论来源——决策中引用的 PR、问题或文档

**门槛：在进入第 3 步前，满足门槛（客观通过条件）**中的第 2 步要求。

第 3 步：加载模板

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

第 4 步：填写各部分

根据决策数据填写各部分：

部分	来源
标题	决策摘要（使用祈使语气）
状态	初始状态始终为 draft
背景	问题陈述、约束条件
决策驱动因素	按优先级排序的需求
考虑过的选项	所有可行的替代方案
决策结果	所选方案及其理由
后果	正面、负面和中性影响

第 5 步：应用完成定义

加载 references/definition-of-done.md，并验证 E.C.A.D.R. 标准：

• Explicit：明确的问题陈述
• Comprehensive：全面的选项分析
• Actionable：可执行的决策
• Documented：已记录的后果
• Reviewable：利益相关者可审阅

**门槛：在进入第 6 步前，满足门槛（客观通过条件）**中的第 5 步要求（缺少数据时使用 [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

组成部分	规则
NNNN	脚本生成的零填充序列号
-	分隔符
slugified-title	小写字母、连字符，不含特殊字符
.md	Markdown 扩展名

参考文件

• 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