用途:为重要技术决策建立可追溯的文档,记录决定了什么、为什么这样决定,避免日后重复争论。
主要能力:提供标准 ADR 格式,包含标题、状态、日期、Context(背景与需求)、Decision(决策)、Alternatives Considered(备选方案及利弊与拒绝原因)、Consequences(后果与影响)。支持在 docs/adr/ 目录下按编号存放,如 000-template.md、001-use-postgresql.md,并用 README.md 作为索引。资料给出生成索引的 bash 命令:echo "# Architecture Decision Records" > docs/adr/README.md 等循环脚本,可自动汇总标题与状态。
使用方式:适合在选定框架、语言或数据库,变更认证授权方式,采用新部署策略,重大重构,选择第三方服务,以及 API 设计(REST 与 GraphQL、版本策略)时编写。不适合例行 bug 修复、小版本升级、代码风格调整等不影响他人的改动。更新时不要编辑旧 ADR,而应新建一条并标注 Superseded by 指向新记录。
限制与注意:ADR 是不可变历史,应保持简短,一页为宜;存放在代码仓库而非 wiki,随代码一起流转;备选方案部分最有价值。资料未提供安装命令、收费、平台支持等具体信息。