Est's Blog
·
我的 Vibe Coding 最佳实践——ADR文档
内容提要
ADR文档（架构决策记录）用于记录技术决策的原因，而非系统设计。每个ADR对应一个决策，具有固定编号和重要状态。文档应简洁，强调“为什么”而非“什么”，并与设计文档分开。通过引用其他ADR，形成决策网络，确保决策历史清晰，降低上下文成本。
关键要点
-
ADR文档（架构决策记录）的核心目标是记录技术决策的原因，而不是系统设计。
-
每个ADR对应一个决策，编号应保持永久，且状态非常重要。
-
ADR文档应简洁，强调'为什么'而非'什么'，并与设计文档分开。
-
允许ADR之间引用，形成决策网络，确保决策历史清晰。
-
文档的组织应按领域而非时间，便于查找和管理。
延伸解读
ADR文档的重要性
ADR文档不仅记录技术决策的原因，还能帮助团队理解决策的演变过程。通过明确的编号和状态管理，团队成员可以快速追溯到每个决策的背景，降低沟通成本，避免重复讨论相同的问题。
如何有效组织ADR文档
在组织ADR文档时，建议按领域而非时间进行分类，这样可以提高查找效率。通过清晰的文件命名和编号，团队可以更方便地管理和引用相关决策，形成一个有机的决策网络。
避免常见错误
许多团队在撰写ADR时容易混淆设计文档与决策记录。ADR应专注于'为什么'而非'什么'，避免详细描述系统设计，以确保文档的简洁性和针对性。
延伸问答
ADR文档的主要目的是什么？
ADR文档的主要目的是记录技术决策的原因，而不是系统设计。
如何组织ADR文档以便于查找？
ADR文档应按领域组织，而不是按时间，文件名应体现领域，便于查找和管理。
每个ADR文档应包含哪些重要信息？
每个ADR文档应包含决策的编号、状态、上下文、决策及其后果等信息。
为什么ADR文档强调记录'为什么'而不是'什么'？
ADR文档强调记录'为什么'是为了确保决策的依据清晰，避免混淆设计文档的内容。
ADR文档的状态有哪些类型？
ADR文档的状态包括 Proposed、Accepted、Deprecated、Superseded 和 Rejected。
如何通过ADR文档形成决策网络？
通过在ADR文档中引用其他ADR，可以形成决策网络，确保决策历史的清晰。
