架构决策记录（ADR）

为什么需要 ADR

团队换框架、选数据库、定 API 形态时，口头结论和 PR 描述往往撑不过半年：新人不知道「当时为什么不用 B」，评审时也无法对照约束是否仍然成立。架构决策记录（ADR）把「上下文—决策—后果」写成可检索的文档，让权衡与依据可追溯，而不是藏在某个人的记忆里。

技能如何引导你写 ADR

本技能按 ADR 生命周期组织流程，核心步骤与 SKILL 一致：

1. 捕捉上下文：约束、驱动因素、问题边界。
2. 列出备选方案：每个选项的利弊，避免只写「我们选了 X」。
3. 记录决策与后果：明确决定是什么，落地后带来的正面与负面影响。
4. 关联与状态：链接相关 ADR，被新决策取代时标记弃用而非改历史正文。

技能内提供多种模板（如 MADR、轻量 ADR、Y-Statement、弃用型、RFC 风格），并覆盖目录结构、索引 README.md、评审流程，以及用 adr-tools 等工具做自动化管理的实践要点。

适用边界

| 适合写 ADR | 可跳过 |
|------------|--------|
| 新框架/数据库/API 模式、安全与集成架构 | 小版本升级、Bug 修复、实现细节、例行配置 |

最佳实践：实现前尽早写、控制在 1–2 页、诚实写缺点；已接受的 ADR 不要改原文，用新 ADR 取代。没有对应行动的 ADR 价值有限。