An ADR is not a design document. It is a record of the decision that survived the meeting. If it cannot be read seven years later by an engineer who was not there, it has failed its purpose.
The template.
Every ADR we write has six sections. The order is fixed. The labels are fixed. The brevity is enforced.
- Context. The state of the system at the moment the decision was forced. One paragraph. No background.
- Decision. One sentence, in the present tense, declarative. "We will…": never "we propose."
- Consequences. The trade-offs accepted. The new constraints introduced. The classes of bug now possible that were not before.
- Alternatives. The options not taken, with one sentence each on why. Future-you needs to know what was already considered.
- Status. Proposed / Accepted / Superseded by ADR-NNNN / Deprecated. A status of "Accepted" is a commitment.
- Signed-off by. Names. Date. Two engineers minimum. The decision is durable because two people are on the record.
No "Solution," no "Approach," no "Background." Those sections accrete prose and bury the decision. The decision is the document.
Case one: ADR-0042 · Split read/write paths on the ledger.
Context. Settlement run took 47 minutes at month-end. Read traffic from the operations dashboard contended with the write path. Decision. We will route read-only ledger queries through a read replica with eventual consistency, accepting a five-second staleness window on operations dashboards. Consequences. Settlement run drops to 12 minutes. Operations dashboards must display a "data as of" timestamp. Two new failure modes: replica lag exceeding the window, and replica failover during settlement. Status. Accepted, 2021-04. Still in force.
Case two: ADR-0118 · Multi-gateway payment routing.
Context. Payment routing had to survive the loss of any one provider, because the whole revenue path ran through it. Decision. We will route payments across gateways by issuing-bank BIN, with deterministic failover on 5xx and timeout. Consequences. Reconciliation now spans two settlement files in two formats. A new class of bug: same authorisation reported by two gateways during failover. Mitigation: idempotency key tied to internal payment ID, not to gateway-issued ID. Status. Accepted. Superseded by a later ADR when another gateway was added.
Case three: ADR-0207 · .NET 4.8 → .NET 10, service by service.
Context. The platform runs on .NET Framework 4.8. Vendor support continues, but the language and tooling deltas widen with each release of .NET. Decision. We will migrate one service at a time, starting with stateless edge services, ending with the settlement engine. Each migration is a separate ADR. The platform-wide ADR is the contract that the migration is sequenced and never skipped. Consequences. The platform runs two runtimes simultaneously for the duration of the migration. Cross-runtime calls cross a clearly-named boundary, never an accidental one. Status. Accepted, 2025-02. In progress; Migration in progress at the time of writing.
How an ADR fails.
It fails when the decision cannot be reconstructed without re-running the meeting. It fails when "Status: Accepted" is the only signal that someone actually meant it. It fails when the alternatives section is missing, because future-you will spend a week rediscovering them. We have read 700+ ADRs across our engagements; the ones that age well are the short ones with a clear status field and two signatures.
Decisions must survive the people who made them. Otherwise they are opinions.