模板
ADR 模板
记录一个决策：背景、决定、后果、为什么没选别的
亲历产品组织阶段 · 通用更新于 2026-10-16
ADR（Architecture Decision Record，架构决策记录）记一个决定：当时的背景、决定了什么、为什么没选别的、会带来什么后果。不是每个决定都值得写，只记那些半年后会有人问“当初为什么这样做”的。单仓产品放 docs/adr/，跨仓库、组织或商业层面的决定放 ops 仓的 decisions/，命名 ADR-NNN_<topic>.md。
什么时候写
Matt Pocock 的 domain-modeling skill 给了一个好用的判断：三条同时成立才写。
- 难以逆转：以后改主意的代价不小
- 没有上下文会让人困惑：后来的人看到代码会想“为什么要这样做”
- 是一次真实的取舍：确实有别的选项，你出于具体原因选了这一个
三条缺一条就不用写：容易逆转的，改回来就是了；不让人意外的，没人会问；没有真实替代方案的，没什么可记。典型值得写的：技术选型里会被锁定的那部分（数据库、认证服务、部署平台），模块之间的边界，以及故意偏离常规做法的地方，比如“我们不用 ORM，因为……”。
模板
# ADR-NNN：<一句话写清决定>
- 状态：提议 / 已采纳 / 已废弃 / 被 ADR-NNN 取代
- 日期：YYYY-MM-DD
- 决策人：
- 相关：（spec、Issue、PR 的链接）
## 背景
（当时面对什么问题，有哪些约束，哪些是代码里看不出来的）
## 决定
（决定了什么，用肯定句写）
## 为什么没选别的
| 方案 | 没选的原因 |
|---|---|
## 后果
- 好处：
- 代价：
- 什么情况下要重新考虑：示例
# ADR-007：标签存成独立的表，不用数组字段
- 状态：已采纳
- 日期：2026-10-16
- 决策人：技术负责人
- 相关：docs/specs/2026-10-16_todo-tags.md
## 背景
待办要支持标签和按标签筛选，后续可能做标签统计。每条待办最多 10 个标签，标签名不区分大小写。
## 决定
新建 tags 表和 todo_tags 关联表，标签名存小写形式并加唯一约束。
## 为什么没选别的
| 方案 | 没选的原因 |
|---|---|
| 在 todos 表加文本数组字段 | 改名要逐行更新；不区分大小写的去重和统计都麻烦 |
| 存成 JSON 字段 | 这个项目要靠数据库约束保证标签名不重复，放进 JSON 就只能靠应用代码；标签改名要逐条改写待办里的 JSON；去重和校验逻辑散在应用里，长期维护成本高 |
## 后果
- 好处：去重靠数据库约束保证；按标签筛选可以走索引
- 代价：多一次关联查询；迁移多两张表
- 什么情况下要重新考虑：如果标签要支持层级（父子标签），重新评估数据结构每一节怎么填
| 节 | 怎么填 | 最容易犯的错 |
|---|---|---|
| 标题 | 一句话写清决定本身 | 写成问题，比如“关于标签存储的讨论” |
| 状态 | 提议、已采纳、已废弃、被取代 | 改主意时直接改旧 ADR 的内容。应该新写一篇，在旧的那篇标“被 ADR-NNN 取代” |
| 背景 | 写当时的约束，尤其是代码里看不出来的（合规、合同、团队能力） | 只写决定不写背景，半年后没人知道当时为什么受限 |
| 决定 | 用肯定句，一两句话 | 写成“倾向于”“可能会”，读完不知道到底定没定 |
| 为什么没选别的 | 列出真正考虑过的方案和否掉的原因 | 不写被否的方案，过几个月又有人把它当新主意提出来 |
| 后果 | 好处、代价都写，再写重新考虑的条件 | 只写好处；不写重新考虑的条件，决定就永远没人敢动 |
写短一点也没关系
Matt 的写法更简：一个标题加一到三句话，说清背景、决定、原因就够了，状态、备选方案、后果只在有价值时才加。用 /mattpocock-skills:grill-with-docs 拷问时，它会在出现值得记录的决定时提议写 ADR，默认文件名是 docs/adr/0001-<slug>.md 这种四位编号。两种命名选一种，在同一个仓库里保持一致即可。