adr

ADR

记录重要架构决策背后的原因。生成精简且持久的记录；或者判定现有产物、其他文档类型或不记录是更合适的归属。

路由请求

• **明确要求创建：**确认决策符合条件，检查证据和仓库惯例，然后编写并验证 ADR。请求已授权创建有依据的记录；不要再增加创建门槛。
• **发现缺漏：**仅考虑已确定、但其理由原本会随时间消失的决策。在安全的前提下完成当前工作，提出创建 ADR 的建议并指出具体缺失的理由，然后等待用户确认后再创建。
• **编辑现有 ADR：**检查记录及其历史。直接应用编辑性修改；语义变更则按下文的生命周期处理。
• **审查现有 ADR：**只读地检查其资格、内容、历史和验证情况，然后报告发现。

1. 确认理由是否值得长期记录

在询问可查证的信息之前，先检查决策、相关代码和测试、维护中的文档、临时设计材料、现有 ADR 及历史记录。只有满足以下所有条件，才有创建 ADR 的必要：

• 决策会对架构、运维、兼容性或安全产生重大影响，且逆转成本较高；
• 如果缺少相关背景，合理的未来贡献者会对这一选择感到疑惑；
• 理由体现了真实的权衡或重要的外部约束；
• 临时设计产物退役后，代码和维护中的文档将无法保留关键的决策缘由。

临时架构概要是证据，而非持久的归属位置。反之，不要重复记录已由维护中的设计、政策、规范或其他持久产物负责的理由。将实施计划、领域定义、操作说明和当前行为描述保留在各自适用的产物中。

区分观察到的事实、有依据的推断、假设和未知信息。切勿仅凭代码重构意图，也不要把不确定的内容说成定论。

完成标准：将缺漏归类为 ADR、其他持久归属位置或无需记录，并明确说明决定性证据和不确定性。

2. 遵循并协调仓库惯例

检查现有 ADR 的存放位置、命名、模板、语言、状态用词和历史记录。遵循合理的本地惯例，不要迁移或扩展它。若没有既定惯例，则使用 docs/adr/、以决策为主题的标题和单调递增的四位编号、项目的文档语言，以及 Proposed、Accepted、Rejected 和 Superseded 这些状态。新记录应标为 Accepted：人类通过合并包含该记录的变更来接受决策。

除非用户另行要求，否则不要创建索引、引导记录、目录层级或工具。绝不重复使用编号。

完成标准：开始撰写前，确定目标位置、编号、状态、语言和文档结构。

3. 编写精简且足够的记录

如果项目没有更适用的模板，请从 templates/adr.md 开始。保留以下部分：

• 背景： 促使决策成为必要的各种因素、约束、不确定性和冲突。
• 决策： 清楚说明选择了什么以及原因。
• 后果： 此选择带来的重大收益、成本、风险、责任和灵活性损失。

仅当确实存在其他备选方案，且未来读者可能会重新考虑为何不选它们时，才添加 考虑过的备选方案。仅将 参考资料 用作持久的补充证据；核心理由应保留在 ADR 中。

排除类、模式、命令、逐个文件的更改、任务分解、验证计划及其他实现细节。这些内容应归入临时设计和实现工件。精简所有无助于未来贡献者理解决策、理由或后果的段落。

完成标准：记录保留一项决策及其原因，同时不沦为实现约定。

4. 保留历史并进行验证

直接应用不改变含义的修正。更改决策、理由或重大后果时，通常应新建 ADR；将旧记录标记为 Superseded，并关联两份记录。保留被否决和已被取代的记录。如果直接修改语义有充分理由，应先说明对历史记录的影响，并取得明确的人为选择。

验证身份、日期、状态、位置、不确定性、持久引用、相互对应的取代链接以及最终 diff。报告新建、更改或审查的路径、记录的决策、尚存的不确定性以及相关状态变更。

完成标准：持久记录简洁易懂，历史保持真实，且所有更改过的工件均有交代。