架构决策日志（ADR）

是什么

ADR（Architecture Decision Record）= 把每一次「我选了 X」写成一条结构化记录。为什么要记？因为做决定时的语境活不过两周：当时对比过哪几个方案、放弃了什么，两周后就只剩一句「当时随便选的」，等想推翻它时连理由都想不起来。

这个库回答的核心问题就是「怎么选、为什么这么决定」——所以这个库本质上就是一份个人 ADR 合集，本篇是它的总入口。

硬门槛

五要素缺一不可。「怎么选」只有配上「放弃了什么」才算笔记，否则是广告——只写优点不写代价的选型文，三个月后一文不值。

五要素模板

每条决策五个字段，一个都不能少：

markdown

### ADR-XXX：一句话说清决定

- **日期**：YYYY-MM-DD
- **背景**：当时面对什么问题、什么约束
- **备选项**：当时认真考虑过哪几个（只有一条路的不配写 ADR）
- **决定**：最后选了什么
- **代价**：放弃了什么、接受了什么坏处
- **后果**：事后看对不对（可回填；没验证就写「待回填」）

决策日志

编号	日期	决策	状态
ADR-001	2026-10-24	知识库选 VitePress	✅ 后果已回填：对
ADR-002	2026-10-24	状态管理默认不上 Pinia	⏳ 待回填

ADR-001：知识库选 VitePress

日期：2026-10-24
背景：要建个人前端知识库，核心诉求是「页面一定要美观、交互一定要优秀」，同时写作成本必须低——写作本身已经够难了。
备选项：① VitePress；② Nuxt Content；③ Hexo；④ Vite + Vue 3 手写
决定：VitePress
代价：深度定制受默认主题约束，整页自由度不如 Nuxt Content；想要非文档形态的页面（比如魔法阵首页）得往主题里塞 Vue 组件，走的是「官方没承诺稳定」的路子
后果：对。内容站的本质是排版 + 搜索 + 静态托管，VitePress 全中；而「美观」的战场（首页、落地页、配色）本来就是写 Vue 组件，没被文档框架限制住。手写方案被证伪：会死在 markdown 渲染和搜索这种无聊但必须的基建上

ADR-002：状态管理默认不上 Pinia

日期：2026-10-24
背景：每个新项目开工都想先把 Pinia 装好——「反正早晚要用」。但装完的实际结局是：90% 的状态躺在 store 里没人第二个组件用。
备选项：① 开工先配 Pinia，状态都放全局；② 默认组件内 ref，满足条件再升级
决定：②。升级条件见状态管理方案对比：两个以上不相干的组件要读写同一份数据
代价：状态后期升级成全局时，要挪代码、改 import，一次大约十几分钟
后果：待回填（目前的规模下还没付过这笔钱；哪天挪得肉疼了回来填）

维护纪律

决策变了，不改旧条：新开一条写「取代 ADR-XXX」，旧的标记状态即可。决策的演变史比决策本身更值钱——它是下次选型的先例库
后果必须回填：写「待回填」的条目，被现实验证（或打脸）的那天回来补。打脸的记录尤其珍贵
小决策直接记在本篇日志表里（一行即可）；大决策值得展开的，独立成篇并在本篇挂链接

一句话

ADR 记的不是「选了什么」，是「当时为什么、付出了什么」。三个月后能被推翻得有理有据的决策，才是好决策记录。

参考链接

martinfowler.com——「架构是关于重要决策的」这一思想源头
adr.github.io——ADR 形式的惯例大全（五要素模板的民间标准版）

架构决策日志（ADR） ​

是什么 ​

五要素模板 ​

决策日志 ​

ADR-001：知识库选 VitePress ​

ADR-002：状态管理默认不上 Pinia ​

维护纪律 ​

参考链接 ​