architecture-decision-record

架构决策记录（ADR）技能

此技能按照 Nygard 格式（目前采用最广泛的标准）生成完整的架构决策记录（ADR）。ADR 用于记录重要技术决策背后的理由，让未来的团队成员不仅了解 决定了什么，还了解 为什么这样决定。

必需输入

根据已有信息撰写。如果缺少以下任一项，仍需生成完整内容：对每处缺失信息填入合理假设，并标记为 (假设，需确认)，最后列出这些假设。仅当核心主题本身缺失（无内容可写）时，才先提问。

• ADR 编号（ADR 登记表中的连续编号，例如 012；如果未知，则填“下一个可用编号”）
• 决策标题（简短，例如“使用 PostgreSQL 作为主数据存储”）
• 背景（什么情况促使团队需要做出此决策？）
• 考虑过的选项（至少 2 个；如果只给出 1 个，请询问还考虑过或排除过哪些替代方案）
• 已做出的决定（选择了哪个选项）
• 选择理由
• 状态（Proposed / Accepted / Deprecated / Superseded）
• 作者和日期
• 团队背景（可选——团队规模、相关经验、组织限制；有助于调整背景部分的正式程度和深度）

输出格式

---

ADR-[NNN]：[决策标题]

日期： [YYYY-MM-DD] 状态： [Proposed / Accepted / Deprecated / Superseded by ADR-NNN] 作者： [姓名] 决策者： [最终决定者——个人或团队]

---

背景

[3–6 句话。描述导致必须做出此决策的情况、限制和影响因素。包括：要解决的问题、相关系统状态、团队限制、时间压力或不可妥协的要求。请以这样的方式撰写：向 18 个月后加入团队且不了解先前背景的人解释。]

主要限制：

• [限制 1：例如“必须支持在企业客户的本地部署”]
• [限制 2：例如“团队没有 Go 语言经验”]
• [添加所有相关限制]

---

考虑过的选项

针对每个选项，生成：

选项 [N]：[名称]

描述： [此选项的内容——1–3 句话]

优点：

• [优点 1]
• [优点 2]

缺点：

• [缺点 1]
• [缺点 2]

排除原因（如果未选）： [如实说明原因]

---

决策

我们将[选择的选项]。

[用通俗语言以 2–4 句话解释此决策。即使单独阅读这一段，也应能理解决策内容，无需阅读整篇文档。]

---

后果

正面后果

• [此决策带来的能力或改进]
• [此决策降低的风险]

负面后果／接受的权衡

• [因此放弃或承担的事项]
• [引入的技术债务或限制]
• [此决策要继续有效，必须满足的条件]

风险

• [哪些情况可能会让我们事后发现此决策是错误的]
• [出现什么情况时应重新审视此决策]

---

实施说明

[如果此决策存在不明显的实施注意事项，或者实施者需要了解相关工单／RFC，请在此列出。仅当决策纯粹是工具选型且不存在实施歧义时，才可省略此节。]

---

复审日期

[除非此决策是永久性的，或显然已是最终决定，否则请填写。说明具体的触发条件，例如“如果团队规模超过 20 名工程师，或流量超过每天 10M 次请求，则进行复审”，而非只写“应定期复审”。]

---

深入资料

此技能附带支持文件——有需要时请使用：

• references/decision-scoping.md — 哪些内容值得写入 ADR（以及“背景”必须包含什么）。生成输出时请参考此文件；其中包含校准标准和判断要点，以上方法摘要未能详尽涵盖。
• templates/adr.md — 可填写的交付文档模板，内含质量检查项。用户希望自行撰写文档，而不是由你生成时，请提供此模板。

评分标准（0–40）

交付前请为此技能的任何输出评分；32 分及以上即可交付。

维度	0	5	10
背景重建	假设读者已经了解问题和各方压力	说明了问题，但缺少制约因素（团队限制、规模、截止时间、触发事件）	两年后的读者仅凭背景部分就能推断出这一决策
选项的诚实性	只列出选定的选项，或将被否决的选项写成稻草人	≥2 个选项，但否决理由循环论证（“不符合要求”）	每个被否决的选项都有实际优势，且指出其不适用之处与背景压力之间的具体关联
后果的平衡性	所有后果都是正面的	只提及表面上的负面影响，没有具体的运营细节	负面影响指出了实际债务、新增的运营负担，以及维持决策有效所需的条件
重新审视的触发条件	未说明风险或审查条件	“定期审查”——没有可衡量的条件	指出具体、可衡量且会使决策失效的触发条件，并明确责任人

质量检查

• 背景说明了 原因，而不只是 内容
• 至少记录 2 个选项（包括被否决的选项）
• 被否决的选项包含坦诚的否决理由
• 后果包含 负面 影响——任何决策都不是没有后果的
• 在“决策”部分用通俗语言说明决策
• “风险”部分指出哪些情况会使此决策失效
• “背景”部分在前 1–2 句话中明确说明问题（不得假设读者知道团队要解决什么问题）
• 每个被否决选项的“否决理由”都指出具体限制或权衡（不能使用“不符合我们的要求”这类循环论证）

反模式

• 决策已完全实施且团队已继续推进后，不要再撰写 ADR——事后撰写的 ADR 往往会遗漏真实原因和替代方案
• 不要只列出选定的选项——坦诚说明被否决选项的理由，才是 ADR 对未来读者最有价值的部分
• 不要只写正面后果——每项架构决策都涉及权衡；没有负面后果的 ADR，说明审视得不够坦诚
• 不要让状态无限期地停留在“Proposed”——无人批准的 ADR 无法指导任何人的决策
• 不要撰写假设读者已经了解所解决问题的背景——背景部分的存在，正是为了帮助缺乏相关背景的读者

使用示例

• “撰写一份关于使用 [technology] 的 ADR”
• “记录我们选择 [architectural choice] 的决策”
• “为 [topic] 创建一份架构决策记录”
• “帮我写下我们选择 [option] 而不是 [alternative] 的原因”

示例触发语

• “记录一项技术决策。”
• “撰写 ADR。”
• “记录一项架构选择。”
• “说明选择某项技术的原因。”