ADR（Architecture Decision Records）深度精读：格式、反模式、证据链与团队/个人项目实践 → 写成模板 未开始

题记与说明

日期：2026-11-03 ｜ 前缀：knowledge-illuj6xc-0 ｜ 类型：主题研究（多来源深读，非单篇论文）
方法：网络检索 + 逐来源深读（9 个来源直接抓取原文，1 个来源为检索级证据），全部引用均给出处链接。

来源清单（按证据强度排序）

一、核心问题

adr.github.io 的定义性表述：

"An architectural decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant."
"An Architectural Decision Record (ADR) captures a single AD and its rationale."

ADR 要解决的问题不是"要不要写文档"，而是四个子问题：

1. 失忆问题：几周后没人记得"当初为什么这么建"。Azrak 称之为 "architectural amnesia"（架构失忆）：*"How many times have you stared at working code and wondered 'Why did we build it this way?'"*。Nygard 的版本：没有记录时，后人只能 *"Blindly accept the decision"* 或 *"Blindly change it"*，而目标正是 *"avoid either blind acceptance or blind reversal"*。
2. 格式问题：写到什么粒度、哪些字段，才能既留住理由又不沦为没人维护的重文档？Nygard：大文档 *"never gets maintained and it may not even be read"*，而 *"Bite sized pieces are easier for for all stakeholders to consume"*（原文如此，for 重复为原文笔误）。
3. 证据链问题：决策记录若只有结论没有论据（备选方案、权衡、需求映射、验证方式），就退化成"存档性废话"——MADR 维护者明确说 *"We think that the considered options with their pros and cons are crucial to understand the reasons for choosing a particular design."*
4. 存活问题（实践/反模式）：实证研究显示约一半尝试 ADR 的仓库只有 1–5 条记录就放弃了——制度如何设计才能让 ADR 活过三个月？

二、主要主张

按来源归纳为六条主张：

M1｜ADR 是"一决策一文件"的轻量记录，不是重文档。 Nygard：*"One ADR describes one significant decision for a specific project"*；*"The whole document should be one or two pages long"*；用 *"a lightweight text formatting language like Markdown or Textile"*。

M2｜ADR 应不可变（immutable）、只增不删，变更走 supersede。 Nygard：*"ADRs will be numbered sequentially and monotonically. Numbers will not be reused."*；被取代的记录保留并标注 *"(It's still relevant to know that it was the decision, but is no longer the decision.)"*。AWS Blog/InfoQ 均强调批准后的 ADR 应视为不可变，AWS 指南原文：更新时 *"they should change the status of the old ADR to Superseded, note their changes in the change history of the new ADR, and keep the old ADR in the decision log."*

M3｜记录"为什么"是 ADR 的核心价值；写下来本身会改进决策质量。 Azrak：*"when you know you'll have to write down your reasoning, you naturally think through decisions more carefully"*；*"Writing forces you to be clear about your thinking."*——写作暴露推理缺口（失败案例怎么处理？回滚计划呢？），这是"决策前置评审"效应。

M4｜证据链 = 需求/约束（输入）+ 备选方案与 pros/cons（论证）+ 确认方式与设计文档/基准（验证）+ supersede 链与需求关联（追溯）。 adr.github.io 定义中的 "justified" 一词即要求决策必须带论证；ozimmer：决策应 *"informed and based on Architecturally Significant Concerns (ASCs), including requirements and constraints — desired non-functional qualities in particular"*；AWS Blog：*"Use a separate design document mechanism to explore alternative options thoroughly. Reference these design documents within the ADR"*；MADR 模板内置 Confirmation（如何确认落地合规，如 code review / ArchUnit 测试）和 More Information（链接相关决策与证据）。

M5｜只记录"架构级显著"决策，不要把 ADR 变成流水账闸门。 Nygard 的显著性范围：*"those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques"*。AWS FAQ 同样划界：*"for every aspect of the software that affects structure… non-functional requirements… dependencies… interfaces… and construction techniques"*。反方向的反模式（详见四、六）是"每件小事都要 ADR"，使文档成为瓶颈。

M6｜所有权与节奏决定存活率：人人可写、作者负责、定期评审、放代码旁边。 AWS：*"Each project team member should be empowered to create and own an ADR"*；*"Store ADRs in a central location"*，首选 Git 仓库（*"which makes it easier to version ADRs"*）；AWS Blog 补充会议节奏：readout 时与会者 *"10–15 minutes reading the ADR document"*，会议 *"30–45 minutes maximum"*，参与者 *"below 10"* 但跨职能，并把 ADR 当 *"team law"*。

三、方法

• 理论/规范侧：从 Nygard 原文提取格式定义与约束；从 MADR 官方模板逐字段提取结构；从 adr.github.io 提取模板家族与 Y-statement 精确句式；从 Mozilla ADR-0000 抓取真实项目对比四种格式后选型的完整论证原文。
• 实证侧：以 IEEE Access 2023 的 MSR 研究为数据锚点（921 个公开 GitHub 仓库的 ADR 挖掘，数据集开源在 software-competence-center-hagenberg/ADR-Study-Dataset），辅以 ozimmer 的五级采纳模型解释"为什么半数团队放弃"。
• 实践侧：AWS 官方指南 + AWS Blog（评审节奏、会议设计）+ Azrak 一手团队叙述（接入日常工作流的四个做法），交叉验证"怎么做才活得下去"。
• 综合侧：将上述格式、反模式、证据链与实践结论合成为一个可直接落盘的中文 ADR 模板（见第五节），模板每个字段都标注了来源依据。

四、数据与证据

1. 采纳率低但逐年上升（MSR, IEEE Access 2023），原文摘要：

"the adoption of ADRs is still low, although the number of repositories using ADRs is increasing every year."
"About 50% of all repositories with ADRs contain just one to five ADRs suggesting that the concept has been tried but not yet definitively adopted."

数据集 README 确认规模：*"This repository contains the crawled metadata of 921 public GitHub repositories"*。→ 这不是"要不要用 ADR"的论据，而是"多数团队死于浅尝"的论据；直接支撑"模板必须轻、流程必须有节奏"的设计。

1. Nygard 模板仍是事实标准（同一研究）：

"In most repositories the template proposed by Michael Nygrad is used."（页面原文将 Nygard 误拼为 Nygrad）
"recording decisions is a team activity conducted by two or more users over a longer period of time."

→ 有趣的反直觉点：社区讨论最热闹的是 MADR/Y-statement，但仓库里最多的是最简 Nygard 格式——简单格式胜出。同时"多人长期参与"说明 ADR 存活依赖团队活动而非个人英雄。

1. 格式家族与 Y-statement 精确句式（adr.github.io/adr-templates）：

"In the context of <use case/user story>, facing <concern> we decided for <option> to achieve <quality>, accepting <downside>."

该页列出 MADR（"includes tradeoff analysis of options with pros/cons"）、Nygard（"title, status, context, decision, and consequences"）、Y-Statement 及 Joel Parker Henderson 仓库中的大量变体；ISO/IEC/IEEE 42010:2011 附录 A 建议九个信息项。WICSA 2015 有一篇七模板对比论文。

1. 真实选型案例（Mozilla ADR-0000，全文抓取）——对比 MADR 2.1.2、Nygard 模板、Y-Statements、"Formless"（无约定）后选 MADR，理由原文：

"Implicit assumptions should be made explicit. Design documentation is important to enable people understanding the decisions later on. See also *A rational design process: How and why to fake it*."
"The MADR format is lean and fits our development style."
"The MADR structure is comprehensible and facilitates usage & maintenance."
"The MADR project is vivid."

→ 注意方法论细节：Mozilla 在自己的 ADR 里用 ADR 记录"我们为什么用 ADR + 为什么选这个格式"（元决策），这本身就是最佳实践示范。

1. MADR 当前模板结构（官方 develop 分支逐字段确认）：YAML front matter（status: {proposed | rejected | accepted | deprecated | superseded by ADR-0123}、date、decision-makers、consulted、informed）+ ## Context and Problem Statement + ## Decision Drivers + ## Considered Options + ## Decision Outcome（固定句式 *"Chosen option: '{title}', because {justification}"*）+ ### Consequences（"Good, because…"/"Bad, because…"）+ ### Confirmation（如何确认实现合规，如 code review / ArchUnit）+ ## Pros and Cons of the Options + ## More Information。

1. AWS 的操作细节（best-practices + FAQ + Blog）：最低字段要求 *"At a minimum, each ADR has to define the context of the decision, the decision itself, and the consequences"*，外加 status 与 changelog；决策句必须用祈使语气：*"Avoid using words such as 'should,' and phrase each decision to say 'We use…'"*；评审节奏：*"the ADR process can be quite intense in the beginning… establish a cadence of regular ADR discussion and review meetings before or after the daily standup. With this approach, the defined ADRs will stabilize in two or three sprints"*。

1. 行业采纳度（ThoughtWorks Radar，检索级）：ADR 以 "Lightweight Architecture Decision Records" 名义进入 Vol.15（2016-11）Trial 环，后升至 Adopt 环并被评为 enduring technique：*"Lightweight Architecture Decision Records provide a useful paper-trail on major decisions without becoming yet another piece of…"*（引文片段，未抓全文 PDF）。

1. 失败/放弃的量化侧写：检索级证据（Reddit r/softwarearchitecture 对该 MSR 研究的讨论）与研究结论一致——约半数仓库 1–5 条记录后停更；Catio 2026 指南点名 "we have 200 ADRs, and nobody reads them" 反模式（检索级）。⚠️ 这两条为二手转述，以第 1 条 IEEE Access 摘要原文为准。

五、结论与产出：直接可用的 ADR 模板（本笔记的核心交付物）

5.0 选用决策树（先决定"要不要写、写哪版"）

这个决策是否影响以下之一？
  结构/模式 ｜ 非功能属性 ｜ 依赖 ｜ 接口 ｜ 构造技术        ← Nygard 五类显著性
        │ 否 → 不写 ADR（随手记进代码注释/issue 即可）
        │ 是
        ▼
决策是否难以逆转？（两把刀：推倒成本、迁移成本）
        │ 易逆 → 可只写 Y-statement（一句话）或进 design note
        │ 难逆
        ▼
个人项目 or 团队 ≤5 人小改？ ── 是 → 轻量版（5.2）
        │ 否（团队协作/需评审）
        ▼
标准版（5.1，MADR 骨架 + AWS 必填项）

5.1 标准版模板（团队项目；MADR 骨架 + AWS/证据链补强）

存放到 docs/adr/，命名 NNNN-短名词短语.md（Nygard：*"short noun phrases"*；序号不复用）。

---
# 元数据（来源：MADR 官方模板 front matter；AWS 要求 status + changelog）
adr: 0013
title: 用 SQLite WAL 模式替代 Postgres 作为本地优先存储   # 短名词短语，体现问题→方案
status: proposed        # proposed | accepted | rejected | deprecated | superseded by ADR-0021
date: 2026-11-03        # 最后更新日期 YYYY-MM-DD
deciders: [alice, bob]  # 参与决策的人
consulted: [carol]      # 双向征求意见的人（RACI 之 C）
informed: [dave]        # 单向知会的人（RACI 之 I）
changelog:
  - 2026-11-03: 初稿（author: alice）
---

# 0013: 用 SQLite WAL 模式替代 Postgres 作为本地优先存储

## Context and Problem Statement
<!-- 价值中性地描述力量对峙（Nygard: technological, political, social, project local）。
     为什么现在必须决策？范围是什么？可用 2-4 句或一段小故事。 -->
桌面端要求离线可用、单机零部署；当前 Postgres 依赖使安装包 >100MB，
且断网首启动体验差。范围：本地数据层；服务端同步不在本 ADR 范围。

## Decision Drivers（决策驱动因素 = 证据链的"输入"端）
<!-- 来源：MADR。每条应能追溯到需求/约束/ASC（ozimmer: decisions must be
     "informed and based on Architecturally Significant Concerns"）。 -->
- D1: 离线优先（需求 REQ-114：无网启动 <3s）
- D2: 安装包 <80MB（市场约束，PM 2026-10 确认）
- D3: 单文件备份与迁移能力
- D4: 并发写 <50 TPS 即可（实测日志见 evidence-7）

## Considered Options
- O1: SQLite（WAL 模式）
- O2: Postgres 嵌入式（PGlite / pglite-fx）
- O3: 保持 Postgres + 本地缓存层

## Decision Outcome
Chosen option: "O1: SQLite（WAL 模式）", because
<!-- MADR 固定句式：Chosen option: "…", because …
     AWS 语气要求：祈使句，"We use…"，禁止模糊的 "should"。 -->
只有 O1 同时满足 D1、D2、D3 三个 k.o. 条件；O2 生态不成熟，O3 无法满足 D1。

### Consequences（后果：好的坏的都要写 —— Nygard 原文要求 "not just the 'positive' ones"）
- Good, because 安装包降至 ~45MB（见下方基准测试）。
- Good, because 单文件即可备份（D3）。
- Bad, because 失去 PG 的行级权限；需在应用层补权限模型。
- Bad, because 团队无 SQLite 调优经验，前两周排期需预留学习成本。
- Neutral, because 同步层后续由 ADR-0021 单独决策。

### Confirmation（如何确认"真的按决策落地了" —— 证据链的"验证"端；来源：MADR）
- PR 审查项：禁止引入新的 Postgres 本地依赖（CODEOWNERS 指定 @alice）。
- ArchUnit/测试：`tests/arch/test_no_local_pg.py` 随 CI 强制。
- 验收指标：冷启动 <3s（D1）于 v0.9.0-beta 实测复核。

### Evidence（证据链登记处 —— AWS Blog: "Reference these design documents within the ADR"）
- 基准测试: `bench/2026-10-sqlite-vs-pg.md`（安装包 45MB vs 112MB；冷启动 1.8s vs 4.6s）
- 设计探索文档: `design/2026-10-local-first-explore.md`（三方案详细推演）
- 关联需求: REQ-114（JIRA-1234）  ← Azrak 实践："Now I attach ADRs to business requirements"
- 关联决策: 被 ADR-0021（同步协议）依赖；取代 ADR-0007（原"统一用 PG"决策）
- 相关讨论: PR #318（原型验证）

## Pros and Cons of the Options
### O1: SQLite（WAL 模式）
- Good, because 零依赖、单文件、WAL 下读写并发尚可。
- Bad, because 类型系统宽松，需严格 schema 约束层。
### O2: 嵌入式 Postgres
- Good, because 与服务端同构，团队已有经验。
- Bad, because 安装包体积与启动时间不达标（D1、D2）。
### O3: Postgres + 缓存层
- Good, because 改动最小。
- Bad, because 双写一致性复杂度高，长期维护成本最大。

## More Information（可选：团队共识、落地时间表、复查触发条件）
- 复查触发：并发写需求 >50 TPS 或出现多写端场景时重开本决策。

5.2 轻量版模板（个人项目 / 小改动）

个人项目不需要 front matter 和评审角色——但必须保留理由与备选，否则三个月后的你等于"离职的前同事"（Azrak 开篇三问）。Nygard 五段即可：

# ADR-0004: 选择 Ruff 替代 flake8+black+isort

日期: 2026-11-03 ｜ 状态: accepted ｜ 取代: 无

## Context
lint+format 三件套配置漂移，pre-commit 总时长 40s+，CI 经常因 black 意见不合空转。

## Decision
我们统一用 Ruff（lint + format 一体），配置收进 pyproject.toml。

## Alternatives（为什么不是它们）
- flake8+black：现状即失败原因。
- pylama：生态弱于 ruff，无 Speed 优势。

## Consequences
- (+) pre-commit 6s；配置单点。
- (-) ruff 规则集与 flake8 插件生态不完全对齐，个别规则需 ignore。
- 证据: `bench/2026-11-ruff.md`；需求: 无（工程卫生类）

5.3 Y-statement 极简版（快速沟通/会议白板用；adr.github.io 原文）

"In the context of \<use case/user story\>, facing \<concern\> we decided for \<option\> to achieve \<quality\>, accepting \<downside\>."

中文对应："在 \<场景\> 下，面对 \<问题\>，我们决定选 \<方案\>，以达成 \<质量目标\>，并接受 \<代价\>。"
长版可追加备选（\<other options\>）与收尾理由（because \<additional rationale\>）。适用：桌面便签、PR 描述、日报——之后若决策显著，再升格为完整 ADR。

5.4 证据链五问（写完 ADR 后自检）

1. 输入证据：每个 decision driver 能否指到一条需求/约束/实测数据？（ozimmer 的 ASC 要求）
2. 论证证据：是否有 ≥2 个被认真考虑过的备选，且各有 pros/cons？（MADR："considered options with their pros and cons are crucial"；反例是单选项的 Echo Chamber）
3. 验证证据：Confirmation 一节是否写明了"谁在何时用什么手段确认合规"？（MADR Confirmation 字段）
4. 追溯证据：是否链接了被取代/被依赖的 ADR、需求单、PR、基准报告？（AWS supersede 链；Azrak 需求关联）
5. 语气证据：决策句是祈使句 "We use…"，还是含糊的 "should"？（AWS FAQ 明令禁止后者）

5.5 反模式自查清单（六个"死亡信号"）

5.6 节奏建议（把 ADR 焊进工作流，而非另立流程）

AWS 指南 + Blog + Azrak 三方交叉一致的四个习惯：

1. 实现前写（Azrak："We write ADRs before implementing major decisions"）；
2. 挂进评审（在 code review 与规划会上引用；AWS：readout 会前 10–15 分钟默读 + 书面评论，会 30–45 分钟封顶，人数 <10）；
3. 早起期高频短会（AWS："before or after the daily standup"，两三个 sprint 后稳定）；
4. 变更只走 supersede（旧 ADR 改状态、新 ADR 记 changelog、日志里保留旧的）。

六、结论

1. ADR 的本质是最小化的"决策证据链容器"：需求/约束 → 备选与权衡 → 决策（祈使句）→ 后果（含负面）→ 验证方式 → 追溯链接。格式之争（Nygard/MADR/Y-statement）只是同一骨架的不同压缩率。
2. 实证数据反驳了"格式越全越好"：GitHub 上多数仓库用的恰是最简 Nygard 格式；一半仓库在 1–5 条后放弃——存活关键是轻模板 + 人人可写 + 固定节奏 + 代码同址，而非字段齐全。
3. 不可变 + supersede 链是证据链的时间轴：它让 ADR 库成为可审计的决策史而非随时被改写的说明书。
4. 写成模板：第五节给出三层模板（标准版/轻量版/Y-statement）+ 显著性决策树 + 证据链五问 + 反模式清单，可直接落进任何项目的 docs/adr/。

七、局限

1. IEEE Access 全文未直接读到（PDF 被 418 拦截），所有量化结论基于官方摘要页 + 开源数据集 README；MADR 与 Nygard 模板的精确占比、状态分布等细节未核实。
2. ThoughtWorks Radar、Catio、archpilot、naveenlokesh 为检索级证据（未抓全文），其中 A2/A4/A5 反模式的表述依赖二手转述，但与 Nygard/AWS/ozimmer 一手文献交叉一致。
3. AWS Blog 与 Azrak 文章带推广/立场色彩（Azrak 文末推广 Notion 模板；AWS 倾向自家工具链），其"收益"叙述为单方经验，无对照数据。
4. ozimmer 采纳模型是规范式框架而非实证测量，六分级为作者构造。
5. 生态时效：MADR 模板取自 develop 分支（73 行、约 3.4KB），字段仍在演进；本次未考察 AI 辅助生成 ADR 的工具链（Equal Experts 等来源仅检索到，未深读）。
6. 负向证据不足：各来源以成功案例叙事为主，"认真写了 ADR 但团队仍然失败"的系统研究本次未找到。

八、对我的启发

1. 直接可用：第五节三套模板可以立刻落进我自己的项目（个人项目用 5.2 轻量版；团队/开源仓库用 5.1）。个人的经验教训：个人项目最容易死于"觉得没必要"——但"三个月后的我 = 离职的前同事"这个框架（Azrak 三问）说明个人项目反而更需要最小记录。
2. 本知识库工作流的迁移：这套"元数据 front matter + 证据链登记 + supersede 链"结构与 literature-matrix 笔记体系同构——status/date/changelog 可直接映射到笔记的日期前缀体系；"被取代笔记保留原文、只在头部标注"与 ADR 不可变原则完全一致，值得反向借鉴。
3. 写下来的决策暴露推理缺口（Azrak Benefit 2）对研究/写作同样成立：任何"选型类"笔记都应强制写 Alternatives 一节——这正是 literature-matrix 要求七维的原因，可与 ADR 的 pros/cons 结构互相印证。
4. 显著性判据防过度记录：Nygard 五类（结构/非功能/依赖/接口/构造技术）+ 可逆性两把刀，可作为我判断"这条笔记/这个决策值不值得单独立档"的过滤器。
5. 评审节奏比模板更重要：AWS 的"站会后 10–15 分钟默读"设计说明存活率来自把记录嵌入既有仪式（standup/code review），而不是新增会议——对任何流程落地都适用。

关键原文引述备查（防失联）

• Nygard（2011）："We will keep a collection of records for 'architecturally significant' decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques." / "better to avoid either blind acceptance or blind reversal" / "ADRs will be numbered sequentially and monotonically. Numbers will not be reused." / "The whole document should be one or two pages long."
• adr.github.io："An Architectural Decision Record (ADR) captures a single AD and its rationale."
• Y-statement："In the context of <use case/user story>, facing <concern> we decided for <option> to achieve <quality>, accepting <downside>."
• IEEE Access 2023："About 50% of all repositories with ADRs contain just one to five ADRs suggesting that the concept has been tried but not yet definitively adopted." / "In most repositories the template proposed by Michael Nygrad is used."
• Mozilla ADR-0000："The MADR format is lean and fits our development style."
• AWS FAQ："Avoid using words such as 'should,' and phrase each decision to say 'We use…' or 'The team has to use…'"
• AWS Blog："Use a separate design document mechanism to explore alternative options thoroughly. Reference these design documents within the ADR."
• ozimmer："not all teams and organizations have to go up to Level 5…sometimes, less is more."
• Azrak（2025）："Writing forces you to be clear about your thinking."