develop-adr

架构决策记录（ADR）

架构决策记录用于记录重要技术决策，以及决策的背景和后果。ADR 记录架构选择背后的“原因”，以便未来的团队成员理解这些选择的理由——尤其是在他们质疑为何要采用某种做法时。本技能采用 Michael Nygard 的轻量级 ADR 格式。

适用场景

• 做出影响系统架构的重要技术决策
• 在多种技术方案（框架、数据库、服务）之间做出选择
• 确立未来开发应遵循的模式
• 记录约束或非显而易见方案的理由
• 保存有关过往决策的组织知识

不适用场景

• 决策属于产品或 UX 设计，而非架构或技术 → 使用 develop-design-rationale
• 仍在探索某种方案是否可行 → 为探索设定时间限制，并先使用 develop-spike-summary 记录结果
• 需要向利益相关者推介解决方案 → 使用 develop-solution-brief；ADR 记录决策，而不是推销方案
• 实际上没有要做出的决策（现状将保持不变）：没有决策的 ADR 只会造成干扰；等有决策后再记录

说明

收到创建 ADR 的请求时，请按以下步骤操作：

1. 分配编号和标题 ADR 按顺序编号（ADR-001、ADR-002 等），以便于引用。标题应为描述该决策的简短名词短语，例如“为订单数据使用 PostgreSQL”或“前端采用 React”。

2. 设置状态 新 ADR 的状态为“Proposed”。团队评审后，状态变为“Accepted”“Deprecated”或“Superseded by ADR-XXX”。应跟踪状态变更。

3. 描述背景 说明促成该决策的情况。要解决什么问题？有哪些影响因素（技术约束、团队专业知识、时间安排、成本）？本节应帮助未参与决策的读者理解为何需要做出此决策。

4. 陈述决策 清楚地说明你们做出了什么决定。使用主动语态：“我们将使用……”，而不是“决定使用……”。明确说明该决策包含和不包含哪些内容。

5. 记录后果 列出该决策的结果，包括正面、负面和中性的影响。好的 ADR 会如实说明权衡。哪些事情会变得更容易？哪些会变得更困难？这会带来哪些新的约束或选项？

6. 记录模型选择的后果 （仅当决策选择了某个模型或使系统依赖于某个模型时） 否则完全跳过此步骤；它是“后果”中的一个子章节，不是第七个标题。模型选择与普通依赖项选择不同，对 ADR 而言有一点很重要：评估过的对象会被替换，而且往往会在该决策有效期内被替换。因此，应记录撤销该选择的代价，而不只是胜出的选项。说明你们选择了自建模型、购买模型还是提示通用模型，以及排除另外两种方案的原因；说明现在有哪些内容与该选择耦合（提示词、评估集、输出架构、延迟预算）；说明接受的运营成本，以及达到何种使用量时成本将变得不可接受；说明考虑到这些耦合因素，实际推翻该决策的成本；并说明什么情况会促使重新审议此 ADR——这是一个触发条件，而非评审日期。

输出格式

使用 references/TEMPLATE.md 中的模板组织输出。完整的 ADR 应填写模板的每个部分：状态、背景、决策、后果、考虑过的替代方案和参考资料。

质量检查清单

定稿前，请确认：

• 标题是简短且描述性明确的名词短语
• 明确标注状态（Proposed/Accepted/Deprecated/Superseded）
• 背景说明了为何需要做出此决定
• 以主动语态清楚陈述决定
• 后果同时包含正面和负面结果
• ADR 无需依赖其他文档即可独立阅读
• 如果该决定选择或采用了某个模型：须记录耦合程度、运营成本、撤销成本，以及会促使重新审议该决定的观察结果

示例

请参阅 references/EXAMPLE.md 中的完整示例。