ADR 格式

ADR 位于 docs/adr/，使用顺序编号：0001-slug.md、0002-slug.md 等。

懒创建 docs/adr/ 目录——仅在第一个 ADR 需要时创建。

模板

# {决策的简短标题}

{1-3 句：背景是什么、我们决定了什么、为什么。}

仅此而已。ADR 可以只是一段。价值在于记录 做出了 决策以及 为什么——而非填章节。

可选章节

仅在有 genuine 价值时包含。多数 ADR 不需要。

• Status frontmatter（proposed | accepted | deprecated | superseded by ADR-NNNN）——决策被 revisiting 时有用
• Considered Options——仅当被拒替代方案值得记住
• Consequences——仅当非 obvious 的下游效应需要指出

编号

扫描 docs/adr/ 找最高现有编号并加一。

何时提供 ADR

以下三者必须 全部 为真：

1. 难以逆转 — 日后改主意成本 meaningful
2. 无上下文时令人惊讶 — 未来读者看代码会 wonder「他们到底为何这样做？」
3. 真实 trade-off 的结果 — 有 genuine 替代方案，你因具体理由选了其一

若决策易逆转，跳过——你会直接逆转。若不 surprising，没人会 wonder why。若无真实替代，除「我们做了 obvious 的事」外无需记录。

什么算 qualify

• 架构形态。「我们用 monorepo。」「Write model 是 event-sourced，read model project 到 Postgres。」
• Context 之间的集成模式。「Ordering 与 Billing 通过 domain event 通信，而非同步 HTTP。」
• 带 lock-in 的技术选择。 数据库、message bus、auth provider、部署目标。不是每个 library——只是换起来要一个 quarter 的那些。
• 边界与 scope 决策。「Customer 数据由 Customer context 拥有；其他 context 仅通过 ID 引用。」明确的 no 与 yes 同样 valuable。
• 对 obvious 路径的有意偏离。「我们用 manual SQL 而非 ORM 因为 X。」任何 reasonable 读者会 assume 相反的。阻止下一位工程师「修复」 deliberate 的东西。
• 代码中不可见的约束。「因 compliance 不能用 AWS。」「响应必须 <200ms 因 partner API 合同。」
• 拒绝非 obvious 的替代方案。 若考虑过 GraphQL 因 subtle 理由选 REST，记录——否则六个月后有人再提 GraphQL。