文档与架构决策记录

概述

要记录的是决策,而不只是代码。最有价值的文档记下的是"为什么"——做出某个决策时的背景、约束和取舍。代码展示了"做了什么",文档解释的是"为什么这样做""考虑过哪些别的方案"。这份上下文,对后续在这个代码库里工作的人和 Agent 都不可或缺。

何时使用

• 做出一个重要的架构决策
• 在几个相互竞争的方案之间做选择
• 新增或变更一个公共 API
• 发布一个会改变用户可见行为的功能
• 帮新成员(包括 Agent)熟悉项目
• 发现自己在反复解释同一件事

何时不要使用:不要给一目了然的代码写文档。不要写只是复述代码本身的注释。不要给用完即弃的原型写文档。

架构决策记录(ADR)