Organizations record many outcomes and surprisingly little reasoning. A ticket shows what was requested. A pull request shows what changed. A meeting note may show who attended. None necessarily explains why one option was chosen and another rejected.
A decision is more than its result
The statement “use service A” is not enough for a future reader. They need the problem, relevant constraints, alternatives considered, evidence available at the time, and the conditions under which the choice should be revisited. Without that material, later teams either follow an obsolete rule or repeat the original investigation.
Good records do not pretend certainty. They preserve what was known, what remained uncertain, and who accepted the tradeoff.
Record at the point of commitment
The cheapest time to capture rationale is when the decision is made. Reconstructing it months later produces confident folklore. A lightweight template can be completed asynchronously and linked from the issue, architecture document, pull request, and operational change it governs.
The record should have a stable address and an explicit state such as proposed, accepted, superseded, or retired.
Make scope and authority visible
Every decision has a scope. Some apply to one feature, others to a service, platform, or organization. The record should identify the accountable owner and the people consulted. This prevents a local preference from silently becoming policy.
It should also state what the decision does not cover. Boundaries are often more useful than broad declarations.
Connect decisions to evidence
A decision record becomes operational when it links to implementation, tests, incidents, metrics, or customer evidence. Those links let a reviewer trace from intent to outcome and let an agent retrieve the rationale relevant to a task.
When later evidence changes the choice, create a superseding record instead of rewriting history. The organization should be able to see how its judgment evolved.
ADR-17: preserve the decision that could have gone another way
This abbreviated record belongs to the fictional Northstar case.
| Field | Record |
|---|---|
| State and scope | Accepted for the sandbox Orders endpoint; not a company-wide retry policy. |
| Decision owner | Mara, with Checkout and reliability reviewers consulted. |
| Problem | A lost response can lead to a repeated order request. |
| Decision | Account-scoped key, matching-payload replay, conflict on changed payload, transactional order/result persistence. |
| Retention | 24 hours for this example; retries beyond expiry are not covered. |
| Rejected alternative | Disable retries: simpler, but leaves customers reconstructing whether an order succeeded. |
| Evidence required | Sequential, concurrent, crash, account-boundary, and expiry cases. |
| Revisit trigger | A new external side effect, changed retention need, or storage model incompatible with the atomic boundary. |
The record names the tradeoff without claiming that this is the only valid design. It also names the boundary that makes the design tractable. External payment processing would require another decision rather than a casual extension of this one.
Supersession is an event
Suppose a later requirement needs a longer retry window. Create ADR-23 as a proposal that references ADR-17, records the new evidence, and considers storage and privacy costs. Until the authorized owner accepts ADR-23, ADR-17 remains governing within its scope.
After acceptance, mark ADR-17 superseded and route the change to its consumers. Keep both records. A run already bound to ADR-17 needs an explicit decision to finish under the old contract or restart. Editing the old paragraph in place would hide that choice.
Disagreement is part of the record
Record a material objection and its disposition. “Checkout consulted” is not enough if Checkout warned that clients generate fresh keys on retry. The decision owner must show whether that objection changed the design, blocked adoption, or was accepted as residual risk by someone authorized to do so.
Two records can be individually reasonable and collectively contradictory. When scopes overlap, suspend the affected action and send the conflict to the owners. Do not ask retrieval ranking to settle authority.
For your first record, select a decision someone is likely to question in six months. Ask a colleague to reconstruct the rejected alternative and the revisit condition from the record alone. Repair whichever answer depends on your memory.