An architecture decision record should preserve the reason one viable option was chosen under specific constraints. Record the context, alternatives, decision, consequences, and conditions that would justify revisiting it. A future reader should be able to distinguish a bad decision from a reasonable decision whose assumptions have changed.
“We use a queue for reliability” is too broad to do that work. Which failure needed isolation? What delay was acceptable? What new responsibility did the queue introduce? The useful record explains the exchange.
Record a consequential choice, not every implementation detail
Michael Nygard's original ADR proposal focuses on decisions that affect system structure, important qualities, dependencies, interfaces, or construction techniques. Its short record includes context, status, decision, and consequences, and preserves old decisions when they are superseded.
Use that scope to avoid creating a parallel specification for every code edit. Choosing how a service acknowledges a durable job is worth preserving because clients and recovery procedures depend on it. Renaming a private variable usually belongs in the code review. A migration runbook belongs near the operation it controls, even when an ADR explains why that migration approach was chosen.
Write a draft while the alternatives are still credible. If the decision has already happened, identify the record as retrospective and distinguish recollection from evidence. Do not invent a unanimous discussion or benchmark to make the document look complete.
A worked example with a real tradeoff inside it
The following ADR is fictional. It illustrates the reasoning structure; no team adopted it and no workload measurements were collected.
ADR 007: Run customer exports as durable background jobs
Status: Proposed; owner: reporting team; review date: November 15, 2026.
Context: The proposed product must allow a user to request an export and return later to download it. Product stakeholders accept delayed completion but require the request to survive replacement of an application instance. The application already has a relational database. Expected volume and the longest export duration remain unmeasured. Export requests may be repeated after an uncertain client response.
Alternatives: Synchronous generation keeps one request-response path, but ties completion to the lifetime of that request. An in-memory background task returns quickly, but loses its only work record when the process disappears. A durable database job record adds state and worker coordination while using an existing operational dependency. A separate message broker offers different delivery and scaling capabilities, but adds a service the team would need to operate.
Decision proposed: Store the export request and its operation identity durably before returning an accepted response. A worker claims pending jobs and publishes a durable result reference. Start with database-backed job coordination, subject to a representative contention and recovery test before release.
Consequences accepted: Users need a status and download flow. The team must implement claim expiry or recovery, idempotent processing where required, result retention, and visibility into stuck jobs. Database maintenance now affects both request storage and dispatch. We avoid introducing a broker initially, while accepting that polling and worker coordination must be evaluated.
Revisit when: Contention interferes with ordinary application transactions; delivery requirements change; delayed completion is no longer acceptable; or operating evidence shows the existing database cannot support both responsibilities. Record measured thresholds during qualification rather than inventing them here.
The important sentence is not “use the database.” It is the relationship between an existing dependency, an accepted user delay, a durability requirement, and the operational work taken on in exchange.
Make the alternatives capable of winning
Compare options against the same problem. A weak ADR describes the chosen design in detail and dismisses alternatives with labels such as “complex” or “not scalable.” A stronger one identifies circumstances in which another option would be preferable.
For the export example, synchronous generation could be reasonable if outputs are predictably small and the user needs an immediate response. A broker could be preferable if the organization already operates one with a suitable delivery contract, or if database dispatch creates unacceptable coupling. These conditions make the record useful when the system changes.
Avoid assigning scores that hide unsupported assumptions. A table saying “database: 9/10, broker: 6/10” does not explain whose operational costs were considered or how volume was estimated. If a benchmark informed the choice, link the workload, versions, commands, results, and limits. If no benchmark ran, say the decision is provisional on the relevant test.
Martin Fowler's ADR discussion emphasizes serious alternatives and the value of writing for clarifying a group's reasoning. A record should expose disagreement that matters to the decision instead of presenting a tidy result that nobody can challenge.
Separate acceptance from implementation and qualification
An accepted ADR records an authorized architectural choice. It does not prove that the implementation exists or that the system passed its tests. The export decision could be accepted while worker recovery remains unfinished.
Use links to the implementation and qualification evidence without collapsing their states. For example, “accepted subject to the stated release checks” can coexist with “recovery test not run.” If the qualification fails, record the finding and revisit the decision rather than treating the document's accepted status as an exemption.
This is especially important when an agent prepares the record. It can summarize sources, draft alternatives, and point out missing evidence. It cannot infer human agreement from a successful document validator. The reviewer and decision owner need to be identifiable, and the recorded approval must correspond to something that actually happened.
Preserve the old reasoning when a decision changes
Suppose later tests show that dispatch queries materially delay customer requests. The next ADR could adopt a broker and link back to ADR 007. ADR 007 becomes superseded; its original constraints and reasoning remain available.
Do not rewrite the old context to make the new choice look inevitable. Preserve when the earlier decision governed the system and what changed. Small factual corrections can be documented according to the team's policy, but a changed architectural choice deserves a new record with its own rationale.
Connect the current operating guidance to the active decision. An agent reading an old ADR should see that it has been superseded before treating it as an instruction. Our AGENTS.md guide distinguishes durable repository instructions from supporting documents: keep the operational rule concise and link to the explanation when that explanation is needed.
For the export service, AGENTS.md might direct contributors to preserve the accepted job-status contract and read the current ADR before changing dispatch. It should not duplicate the entire alternatives discussion. Duplication creates two places that can disagree about which decision is active.
Review the record by asking what would change your mind
Read the ADR as someone responsible for a future change. Can you identify the binding constraint, the rejected option's advantage, the new obligations, and the evidence that would trigger reconsideration? If those answers are missing, adding more background paragraphs may not help.
For the fictional export decision, the remaining uncertainty is specific: workload and recovery behavior need qualification. That is a useful outcome for a proposed ADR. It preserves a reasoned direction while keeping the untested assumption visible.
Primary essays were consulted October 28, 2026. The ADR is an original illustrative proposal, not a real organizational decision or an executed architecture evaluation.
