ADR Format

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

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

Template

# {Short title of the decision}

{1-3 sentences: what's the context, what did we decide, and why.}

就这样。ADR 可以只是一段。价值在于记录 做出了 决策及为何 — 不是填 section。

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

Status frontmatter（proposed | accepted | deprecated | superseded by ADR-NNNN）— 决策被 revisit 时有用
Considered Options — 仅当 rejected alternative 值得记住
Consequences — 仅当非显而易见的下游效应需 call out

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

以下三者必须皆真：

Hard to reverse — 之后改主意的 cost meaningful
Surprising without context — future reader 看代码会 wonder「why on earth did they do it this way?」
The result of a real trade-off — 有 genuine alternative，因 specific reason 选了一个

若决策易 reverse，skip — 你会直接 reverse。若不 surprising，没人会 wonder why。若无 real alternative，除了「我们做了显而易见的事」没什么可记。

Architectural shape. "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
Integration patterns between contexts. "Ordering and Billing communicate via domain events, not synchronous HTTP."
Technology choices that carry lock-in. Database、message bus、auth provider、deployment target。不是每个 library — 只是换起来要一个 quarter 的那些。
Boundary and scope decisions. "Customer data is owned by the Customer context; other contexts reference it by ID only." 明确的 no 与 yes 一样有价值。
Deliberate deviations from the obvious path. "We're using manual SQL instead of an ORM because X." 合理读者会 assume 相反的任何事。阻止下一个工程师「修」掉 deliberate 的东西。
Constraints not visible in the code. "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
Rejected alternatives when the rejection is non-obvious. 若考虑过 GraphQL 因 subtle reason 选 REST，记下来 — 否则六个月后有人会再 suggest GraphQL。