债务决策记录是什么
每个「有意负债」都留一份决策记录：背景是什么、有哪些选项、选了哪个、代价是什么、什么条件下偿还。将来复盘时能看清当初的约束，避免把有意选择误读为能力问题。载体可以是架构决策记录（ADR），也可以直接写进债务台账的对应条目。
基本信息
| 载体 | ADR（Architecture Decision Record）或债务台账条目 |
|---|---|
| 要素 | 背景 / 选项 / 决定 / 代价 / 偿还触发条件 |
| 复盘 | 按触发条件定期检视与清偿 |
| 存放 | 与代码同仓库，随代码一起演进 |
记录要点
- 背景写约束条件：交付窗口、人力、兼容要求，而不是「当时没时间」
- 列出被否掉的选项与否定理由，避免后人重复评估同一方案
- 代价写具体后果：复用受限、性能上限、后续迁移成本
- 偿还触发条件必须可观察：支持第二种数据库时、模块首次大变更时
- 状态可更新：已偿还、已失效、仍有效，三者含义不同
- 决定改变时追加新记录，不改写旧记录
ADR 片段示例
ADR 片段示例
## Status
Accepted（2026-03）
## Context
v1 交付窗口 6 周，团队无 ORM 经验；报表口径仍在变动。
## Decision
直接使用字符串拼接生成 SQL，边界白名单兜底。
## Consequences
- 复用受限，含注入风险（由白名单与参数校验缓解）
- 后续支持多数据库需要重写取数层
## Repay When
支持第二种数据库，或本模块首次重大变更时。ADR 结构
| 部分 | 写什么 | 常见缺失 |
|---|---|---|
| Status | 提议 / 已接受 / 已废弃 / 已偿还 | 只写一次状态，之后从不更新 |
| Context | 约束条件与背景 | 只写结论，看不出约束 |
| Decision | 选择了什么 | 描述模糊，后人无法判断范围 |
| Consequences | 代价与收益 | 只写好处，代价无人记录 |
| Repay When | 可观察的触发条件 | 写成「将来有时间时」 |
记录只写决定不写代价，后人无法评估偿还收益：看到「用了字符串拼 SQL」却不知道省下了什么，也就无法判断现在重写值不值。
触发条件不可观察等于没有条件：「将来有时间时」永远不会触发。写成「支持第二种数据库时」这类可判定的信号，复盘时才能自动筛出待偿还项。