adr-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADR Writing

ADR编写

Overview

概述

Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.

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

Quick Reference

快速参考

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

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

When To Use

使用场景

Documenting architectural decisions from extracted requirements
Converting meeting notes or discussions to formal ADRs
Recording technical choices from PR discussions
Creating decision records from design documents

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

Workflow

工作流程

Step 1: Get Sequence Number

步骤1：获取序列号

If a number was pre-assigned (e.g., when called from

/beagle:write-adr

with parallel writes):

Use the pre-assigned number directly
Do NOT call the script - this prevents duplicate numbers in parallel execution

If no number was pre-assigned (standalone use):

bash

python scripts/next_adr_number.py

This outputs the next available ADR number (e.g.,

For parallel allocation (used by parent commands):

bash

python scripts/next_adr_number.py --count 3

如果已预先分配编号（例如，从

/beagle:write-adr

调用并进行并行编写时）：

直接使用预先分配的编号
不要调用脚本——这可以防止并行执行时出现重复编号

如果未预先分配编号（独立使用时）：

bash

python scripts/next_adr_number.py

这会输出下一个可用的ADR编号（例如

）。

对于并行分配（供父命令使用）：

bash

python scripts/next_adr_number.py --count 3

Outputs: 0003, 0004, 0005 (one per line)

undefined

undefined

Step 2: Explore Context

步骤2：梳理上下文

Before writing, gather additional context:

Related code - Find implementations affected by this decision
Existing ADRs - Check
```
docs/adrs/
```
for related or superseded decisions
Discussion sources - PRs, issues, or documents referenced in decision

在编写之前，收集额外的上下文信息：

相关代码 - 找出受该决策影响的实现
现有ADR - 查看
```
docs/adrs/
```
目录下的相关或已被取代的决策记录
讨论来源 - 决策中引用的PR、问题或文档

Step 3: Load Template

步骤3：加载模板

Load

references/madr-template.md

for the official MADR structure.

加载

references/madr-template.md

以获取官方MADR模板结构。

Step 4: Fill Sections

步骤4：填充内容板块

Populate each section from your decision data:

Section	Source
Title	Decision summary (imperative mood)
Status	Always `draft` initially
Context	Problem statement, constraints
Decision Drivers	Prioritized requirements
Considered Options	All viable alternatives
Decision Outcome	Chosen option with rationale
Consequences	Good, bad, neutral impacts

从你的决策数据中填充每个板块：

板块	内容来源
标题	决策摘要（使用祈使语气）
状态	初始状态始终为 `draft`
上下文	问题陈述、约束条件
决策驱动因素	优先级排序的需求
备选方案	所有可行的替代选项
决策结果	选定的选项及理由
影响	积极、消极、中性的影响

Step 5: Apply Definition of Done

步骤5：应用完成定义标准

Load

references/definition-of-done.md

and verify E.C.A.D.R. criteria:

Explicit problem statement
Comprehensive options analysis
Actionable decision
Documented consequences
Reviewable by stakeholders

加载

references/definition-of-done.md

并验证E.C.A.D.R.标准：

E：明确的问题陈述
C：全面的选项分析
A：可执行的决策
D：已记录的影响
R：可供利益相关者评审

Step 6: Mark Gaps

步骤6：标记空白内容

For sections that cannot be filled from available data, insert investigation prompts:

markdown

* [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]

These prompts signal incomplete sections for later follow-up.

对于无法从现有数据填充的板块，插入调查提示：

markdown

* [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]

这些提示表示该板块尚未完成，待后续补充。

Step 7: Write File

步骤7：写入文件

IMPORTANT: Every ADR MUST start with YAML frontmatter.

The frontmatter block is REQUIRED and must include at minimum:

yaml

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

Full frontmatter template:

yaml

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

Validation: Before writing the file, verify the content starts with

---

followed by valid YAML frontmatter. If frontmatter is missing, add it before writing.

Save to

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

重要提示：每个ADR必须以YAML前置元数据开头。

前置元数据块是必填项，至少必须包含：

yaml

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

完整的前置元数据模板：

yaml

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

验证： 在写入文件之前，验证内容是否以

---

开头，后跟有效的YAML前置元数据。如果缺少前置元数据，在写入前添加。

保存到

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

Step 8: Verify Frontmatter

步骤8：验证前置元数据

After writing, confirm the file:

Starts with
```
---
```
on the first line
Contains
```
status: draft
```
(or other valid status)
Contains
```
date: YYYY-MM-DD
```
with actual date
Ends frontmatter with
```
---
```
before the title

写入后，确认文件：

第一行以
```
---
```
开头
包含
```
status: draft
```
（或其他有效状态）
包含
```
date: YYYY-MM-DD
```
格式的实际日期
在标题之前以
```
---
```
结束前置元数据部分

File Naming Convention

文件命名规范

Format:

NNNN-slugified-title.md

Component	Rule
`NNNN`	Zero-padded sequence number from script
`-`	Separator
`slugified-title`	Lowercase, hyphens, no special characters
`.md`	Markdown extension

格式：

NNNN-slugified-title.md

组成部分	规则
`NNNN`	脚本生成的带前导零的序列号
`-`	分隔符
`slugified-title`	小写、用连字符连接、无特殊字符
`.md`	Markdown文件扩展名

Reference Files

参考文件

```
references/madr-template.md
```
- Official MADR template structure
```
references/definition-of-done.md
```
- E.C.A.D.R. quality criteria

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

Output Example

输出示例

markdown

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

markdown

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

Use PostgreSQL for User Data Storage

使用PostgreSQL存储用户数据

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

PostgreSQL
MongoDB
CockroachDB

Decision Outcome

决策结果

Chosen option: PostgreSQL, because...

选定方案：PostgreSQL，因为...

Consequences

影响

Good

积极

ACID compliance ensures data integrity

ACID合规性确保数据完整性

Bad

消极

Requires more upfront schema design

需要更多前期的 schema 设计

Neutral

中性

Team has moderate PostgreSQL experience

undefined

团队具备中等水平的PostgreSQL使用经验

undefined