决策记录

写决策记录（ADR）与交付文档：记录"为什么这么选"、取舍与后果，让后来的人（和 Agent）不用重新推演。

决策记录与交付文档

结论先行

代码说明做了什么，文档说明为什么这样做、当时放弃了什么。

最值钱的文档不是教程，是决策记录——它防止下一个人（或下一个 Agent）把已经否掉的方案再试一遍。

什么时候写

| 该写 | 不该写 |

| --- | --- |

| 选框架、选数据库、选鉴权方式 | 显而易见的一行代码 |

| 不可逆或高成本的架构决定 | 一次性脚本、试验原型 |

| 交付给客户的安装/运维说明 | 重复代码注释的"翻译" |

| 反复被问到的同一件事 | 还没验证的猜想（要标"未验证"） |

ADR 模板

存放：docs/decisions/0001-标题.md（编号连续，不要重开）


# ADR-0001: 用 SQLite 而不是 MySQL 存 Gitea 数据

## 状态
已接受（2026-10-31）

## 背景
单机部署、数据量 < 1GB、团队无 DBA、需要每日备份简单可靠。

## 备选方案
1. MySQL：功能全，但多一个服务、备份与升级成本高
2. PostgreSQL：同上，且内存占用更大
3. SQLite：单文件、零运维，备份即拷文件

## 决定
选 SQLite，配合每日 dump。

## 后果
- 好处：备份/恢复简单，迁移只需拷文件
- 代价：并发写入能力有限，未来多实例需迁移
- 触发重评的条件：日活写入 > 50 QPS 或需要多机部署

交付文档清单（To B 项目）

1. 安装说明：环境要求、安装步骤、首次启动、常见报错

2. 运维说明：服务启停、日志位置、备份与恢复命令

3. 权限与数据流：数据存在哪、经不经过服务器、谁能看到

4. 更新日志：版本、变更、已知问题

5. 故障排查：症状 → 原因 → 处理

步骤

1. 先写"背景与约束"——没有约束的决策无法评估；

2. 列 2-4 个备选方案，写清各自代价；

3. 写决定与后果，特别是"什么条件下要重评"；

4. 交付文档要能被执行：命令可直接复制、路径是真实路径；

5. 文档与代码同仓库，改代码时顺手改文档。

坑

验收清单

别做的事