adr-writer

ADR Writer

以轻量、结构化的格式记录架构决策，保留背景、理由、备选方案和后果。生成带编号的 ADR 文档，并妥善管理状态生命周期，避免数月后回顾决策时遇到“我们当时为什么要这么做？”的问题。

参考文件

文件	内容	加载时机
references/adr-template.md	标准 ADR 模板，附字段说明和示例	始终
references/status-lifecycle.md	状态转换、取代规则、弃用流程	ADR 引用了现有决策时
references/context-capture.md	引导并记录决策背景的技巧	复杂决策或涉及多方利益相关者的决策时
references/alternatives-analysis.md	评估并记录被拒绝备选方案的框架	正在考虑多个选项时

前提条件

• 一个存放决策的目录（通常为 docs/adr/ 或 docs/decisions/）
• 了解正在做出的决策（可能需要提出澄清问题）

工作流

阶段 1：确定决策

1. 做出了什么选择？ — 提炼核心架构决策。如果用户描述的是一个问题，帮助他们阐明解决该问题的决策。
2. 这个决策是否值得记录？ — ADR 适用于以下决策：
   • 会影响系统结构（组件边界、数据流、API 设计）
   • 难以撤销（技术选型、数据库架构、协议）
   • 存在不明显的权衡（有多个可行的备选方案）
   • 日后会受到质疑（“为什么”会被遗忘）
3. 是什么促使做出这个决策？ — 新需求、性能问题、扩展性问题、安全审计发现、技术债务、团队扩张。

阶段 2：记录背景

记录影响这一决策的因素：

1. 需求 — 有哪些功能或非功能需求促成了这一决策？
2. 约束 — 有哪些因素限制了解决方案的范围？（预算、时间安排、团队专长、现有基础设施、监管要求）
3. 当前状态 — 目前已有些什么？痛点是什么？
4. 利益相关者 — 谁会受到这一决策的影响？需要谁同意？

阶段 3：列出备选方案

对于考虑过的每个备选方案：

1. 明确命名 — 写“PostgreSQL”，而不是“选项 A”
2. 列出具体优点 — 明确、可衡量的收益
3. 列出具体缺点 — 明确、可衡量的不足
4. 说明拒绝理由 — 为什么没有选择这个方案。要具体：“无法满足我们每秒处理 10K 次操作的吞吐量要求”，而不是“太慢”。

阶段 4：记录决策

说明选定的方案，以及结合背景和约束选择它的原因。决策应能从背景和备选方案分析中合乎逻辑地得出。

阶段 5：预测后果

记录这一决策会让哪些事情变得更容易或更困难：

1. 积极后果 — 有哪些方面得到改善？
2. 消极后果 — 接受了哪些权衡？产生了哪些技术债务？
3. 中性后果 — 既不好也不坏的副作用。

阶段 6：分配元数据

1. 编号 — 按顺序编号：ADR-001、ADR-002 等。检查现有 ADR，确定下一个编号。
2. 状态 — 初始状态通常为“Proposed”或“Accepted”
3. 日期 — 编写 ADR 的日期
4. 作者 — 编写此 ADR 的人
5. 取代/被取代 — 如果此决策取代了较早的决策，则链接相关 ADR

输出格式

# ADR-{NNN}: {Descriptive Title}

**Status:** {Proposed | Accepted | Deprecated | Superseded by ADR-XXX}
**Date:** {YYYY-MM-DD}
**Author:** {name}
**Supersedes:** {ADR-XXX (if applicable)}

## Context

{What situation requires a decision? What constraints exist? What forces are at play?
Write in present tense — describe the situation as it exists at decision time.}

## Decision

{State the decision clearly and concisely. "We will use X for Y because Z."
One to three sentences. The reader should understand the decision without reading
the rest of the document.}

## Alternatives Considered

### {Alternative 1 Name}
- **Pros:** {specific benefits}
- **Cons:** {specific drawbacks}
- **Rejected because:** {concrete, specific reason tied to context}

### {Alternative 2 Name}
- **Pros:** {specific benefits}
- **Cons:** {specific drawbacks}
- **Rejected because:** {concrete, specific reason tied to context}

## Consequences

### Positive
- {Concrete benefit 1}
- {Concrete benefit 2}

### Negative
- {Concrete tradeoff 1 — acknowledged and accepted}
- {Technical debt incurred — with plan to address if applicable}

### Neutral
- {Side effect that is neither positive nor negative}

## References

- {Link to related issue, discussion, document, or prior ADR}

校准规则

1. 上下文为王。 上下文部分最重要。没有上下文的决策只是一种断言。未来的读者需要了解原因，而不只是结果。
2. 明确具体的拒绝理由。“不合适”不是拒绝理由。“不支持跨分区事务，而订单处理需要这一能力”才是。
3. **如实说明后果。**每项决策都有缺点。如果负面影响部分为空，说明分析还不完整。引导用户说明权衡取舍。
4. **上下文使用现在时。**上下文部分使用现在时——它记录的是做出决策时的实际情况。
5. **每份 ADR 只记录一项决策。**如果多项决策相互关联，请分别撰写 ADR 并相互引用。不要把无关的决策打包在一起。
6. **通过后不可修改。**已通过的 ADR 不应编辑。如果决策发生变化，请撰写一份取代旧 ADR 的新 ADR。这样可以保留历史记录。

错误处理

问题	解决方法
用户说不出其他备选方案	通过提问帮助他们集思广益：“你还可以怎么做？考虑过哪些方案，又拒绝了哪些？”
决策无关紧要（没有真正的备选方案）	建议不必为此编写 ADR。ADR 用于记录并非显而易见且存在权衡取舍的决策。
决策已经做出，但不记得当时的上下文	根据代码、PR 和提交历史重建上下文。将重建出的上下文标注为“当前可获得的最佳信息”。
不清楚现有 ADR 的编号方案	检查 docs/adr/ 或 docs/decisions/。如果目录不存在，建议创建一个并从 001 开始。
决策范围过于宽泛	拆分为多个重点明确的 ADR。例如，数据库选型写一份，缓存策略写一份。

何时不应编写 ADR

遇到以下情况时，请提出异议：

• 决策很容易撤销（库版本、代码格式规则）——改用注释或配置
• 决策属于没有其他选择的标准做法（使用 HTTPS、验证输入）——不值得记录为决策
• 用户想记录实现细节——ADR 记录的是决策的原因，而非实现方式
• 决策已被取代——撰写新的 ADR，而不是旧的 ADR