writing-adrs

编写 ADR

ADR 位于 docs/adr/，并采用连续编号：0001-slug.md、0002-slug.md 等。

仅在需要创建第一个 ADR 时，才创建 docs/adr/ 目录。

模板

# {Short title of the decision}

{1-3 sentences: what's the context, what did we decide, and why.}

就这样。ADR 可以只有一个段落。它的价值在于记录做出了 什么 决策以及 为什么，而不是填满各个章节。

如果可用，请使用 writing-prose 技能进行撰写和检查，表面形式为 markdown。硬性要求：不得以牺牲准确性和易懂性为代价。

可选章节

只有在确实能增加价值时才添加。大多数 ADR 用不上这些章节。

• 状态 前置元数据（proposed | accepted | deprecated | superseded by ADR-NNNN）——适用于需要重新审视决策的情况
• 考虑过的选项——仅在值得记下被否决的替代方案时添加
• 后果——仅在需要指出非显而易见的下游影响时添加

编号

扫描 docs/adr/，找到现有的最大编号并加一。

质询门槛

ADR 记录影响重大的决策。若决策是在对话中做出的，且从未经过质询（docs/glossary/grilling-session.md），则询问用户：“该决策未经质询——要按原样记录吗？”只有得到明确确认后才能继续。若是转录用户已明确陈述的决策，则不适用此门槛。

何时编写 ADR

以下三项必须全部满足：

1. 难以逆转——之后改变决定的成本很高
2. 缺少背景就令人费解——未来的读者看到代码时会疑惑：“为什么偏偏要这么做？”
3. 源于真正的权衡——确实存在替代方案，而你是基于特定原因选择其中一个

如果某项决策很容易逆转，就跳过它——你之后直接改掉就行。如果它并不令人费解，就没人会疑惑为什么。如果没有真正的替代方案，就没什么需要记录的，除了“我们做了显而易见的选择”。

哪些内容符合条件

• 架构形态。“我们使用单体仓库。”“写入模型采用事件溯源，读取模型则投影到 Postgres。”
• 上下文之间的集成模式。“Ordering 和 Billing 通过领域事件通信，而不是使用同步 HTTP。”
• **会造成锁定的技术选择。**数据库、消息总线、身份验证提供商、部署目标。不必记录每个库，只记录那些需要一个季度才能替换的选择。
• 边界和范围决策。“Customer 数据由 Customer 上下文所有；其他上下文只能通过 ID 引用。”明确说明不做什么，与说明要做什么同样有价值。
• 有意偏离显而易见的路径。“我们使用手写 SQL 而不是 ORM，因为 X。”凡是合理的读者可能会预期相反做法的情况都适用。这能避免下一位工程师“修复”原本就是有意为之的设计。
• 代码中看不出来的约束。“由于合规要求，我们不能使用 AWS。”“根据合作伙伴 API 合约，响应时间必须低于 200ms。”
• **否决理由不显而易见的替代方案。**如果你考虑过 GraphQL，最后却因不那么明显的原因选择了 REST，就把它记下来——否则半年后又会有人建议使用 GraphQL。