ADR 模板
一个可复制粘贴的起始文件，让作者把时间花在内容而非格式上。
为什么
摩擦力会杀死文档。如果工程师要记住 ADR 需要哪些字段、什么顺序，大多数人干脆不写。一个签入仓库的模板消除了这个认知负担：复制文件、填空、完成。有模板的团队写的 ADR 数量是没有模板的 3-5 倍，因为真正的瓶颈是空白页问题，而非写作本身。
何时使用
每个仓库设置一次，之后每个新决策复制即可。模板本身耗时 20 分钟，之后无需重做。
如何做
1. 创建 docs/adr/0000-template.md，把标准字段作为标题 - 加行内注释（<!-- ... -->）说明每个字段要什么 2. 加 justfile/Makefile 目标：'make adr TITLE="use-redis"'，它会： - 找到下一个空闲编号 - 把模板复制到 docs/adr/NNNN-use-redis.md - 在 $EDITOR 里打开 3. 在 CONTRIBUTING.md 加一行："架构决策需要 ADR——运行 make adr" 4. 可选：加 adr-tools（npm）来 lint 每个 ADR 是否含全部必填字段
示例
# NNNN. <标题> - Status: Proposed - Date: YYYY-MM-DD - Deciders: @alice, @bob - Context: <!-- 有哪些作用力、约束、备选？≥3 段 --> - Decision: <!-- 一句加粗的话。 --> - Consequences: + <!-- 正面 --> - <!-- 负面 --> ~ <!-- 中性 --> $ make adr TITLE="use-redis-for-cache" → 已创建 docs/adr/0012-use-redis-for-cache.md
常见问题
- ⚠模板搞得太复杂有 12 个字段——作者觉得是苦差就跳过；保持 5 个核心字段。
- ⚠团队需求变化后忘了更新模板，导致它要求已经没人关心的字段。
最佳实践
- ✓模板控制在 30 行内，一屏放得下——更长说明过度设计。
- ✓加 'Deciders' 字段，明确谁有权把 Status 改成 Accepted。
- ✓模板用 git 版本管理，在架构同步会上提模板变更，保持全员对齐。