用途
架构决策记录（ADR）用于记录一项重要的技术决策及其背景和后果。ADR 捕捉架构选择背后的“为什么”，让未来的团队成员理解决策理由——当有人质疑为什么某件事要这样做时，这一点尤其重要。该技能遵循 Michael Nygard 的轻量级 ADR 格式。
适用场景
- 做出影响系统架构的重大技术决策
- 在技术选项之间进行选择（框架、数据库、服务）
- 确立未来开发应遵循的模式
- 记录约束或非显而易见方案的理由
- 保存关于过往决策的组织知识
不适用场景
- 决策属于产品或 UX 设计选择，而非架构或技术：应使用 develop-design-rationale
- 仍在探索某个方案是否可行：先对探索设定时间盒，并用 develop-spike-summary 记录
- 需要向利益相关者推销解决方案：应使用 develop-solution-brief；ADR 记录决策，不推销决策
- 实际上没有做出任何决策（维持现状不变）：没有决策的 ADR 只是噪音，等到有决策时再写
使用方式
被要求创建 ADR 时，按以下步骤执行：
- 分配编号和标题
ADR 按顺序编号（ADR-001、ADR-002 等）以便引用。标题应为描述决策的简短名词短语，例如“Use PostgreSQL for order data”或“Adopt React for frontend”。
- 设置状态
新 ADR 以“Proposed”开始。团队评审后，变为“Accepted”“Deprecated”或“Superseded by ADR-XXX”。状态变更应被跟踪。
- 描述背景
解释导致该决策的情况。要解决什么问题？有哪些作用力（技术约束、团队专长、时间线、成本）？本节应帮助未参与其中的读者理解为什么需要这个决策。
- 陈述决策
清晰表达决定了什么。使用主动语态：“We will use...”而不是“It was decided...”。具体说明决策包含什么、不包含什么。
- 记录后果
列出该决策的结果——正面、负面和中性的。好的 ADR 会诚实对待权衡。什么变得更容易？什么变得更困难？这产生了哪些新约束或新选项？
- 记录模型选择后果（仅当决策选择某个模型或使系统绑定到某个模型时）
否则完全跳过此步骤；它是“后果”下的一个子节，不是第七个标题。模型选择与普通依赖选择有一点对 ADR 很重要：你评估的东西会被替换，而且往往就在该决策的生命周期内。因此要记录这个选择的撤销成本，而不只是哪个选项胜出。说明你是在构建、购买还是提示一个通用模型，以及是什么排除了另外两种；现在有什么与该选择耦合（提示词、评估集、输出模式、延迟预算）；接受的操作成本以及它在什么量级下变得不可接受；考虑到这种耦合后的真实逆转成本；以及会重新开启此 ADR 的观察信号——它是触发条件，而不是评审日期。
输出格式
使用 references/TEMPLATE.md 中的模板来组织输出。完整的 ADR 会填写模板的每个部分：Status；Context；Decision；Consequences；Alternatives Considered；以及 References。
质量检查清单
定稿前，验证：
- 标题是简短、描述性的名词短语
- 状态清晰标明（Proposed/Accepted/Deprecated/Superseded）
- 背景解释了为什么需要这个决策
- 决策用主动语态清晰陈述
- 后果包含正面和负面结果
- ADR 可独立存在，无需其他文档
- 如果决策选择或绑定到某个模型：耦合、操作成本、逆转成本，以及会重新开启该决策的观察信号都已记录
示例
完整示例见 references/EXAMPLE.md。