architecture-decision-record

## Purpose Produce a single ADR that permanently captures a significant architectural decision. ADRs are append-only: once `Accepted`, they are never edited. If a decision is reversed, a new ADR is written with `Supersedes: ADR-NNN`. ## Input **Works best with:** A clear description of the decision being recorded. **Also valuable:** The context that led to the decision, the alternatives that were considered, any benchmarks or evidence, and the known trade-offs. **Example invocation:** `Document our decision to use HMAC-SHA256 request signing for webhook delivery instead of bearer tokens. We chose this because webhooks are server-to-server calls where rotating tokens is operationally complex, while HMAC signing uses a per-merchant secret and validates the payload integrity simultaneously.` ## Key Concepts ### ADR Lifecycle ``` Proposed → Accepted → (Deprecated) → (Superseded by ADR-NNN) ``` - **Proposed:** Under discussion. May still change. - **Accepted:** Binding. Implementation should follow this decision. - **Deprecated:** The decision is outdated but not actively reversed. - **Superseded:** A newer ADR (referenced) replaces this one. ### What Qualifies as an ADR Write an ADR for any decision that: - Is significant enough that you would regret not having documented it in 2 years - Affects multiple components, teams, or services - Will be difficult or expensive to reverse - Requires understanding the "why" to maintain the system correctly **Do NOT write an ADR for:...