Cover photo: Wesley Tingey / Unsplash. Illustrative photograph, not a record of a client engagement.

An architecture decision record, or ADR, explains one consequential technology choice: the problem, the options considered, the decision and its consequences. It gives a future reader enough context to understand why the team chose that route.

That reader may be the same team six months later.

AWS’s ADR guidance sets out that basic structure and a lifecycle in which a new accepted decision supersedes an earlier one. The editable template here adds practical fields for evidence, ownership, reversibility and review triggers. Record the reasoning while the alternatives are still fresh.

Decide which choices deserve a record

Use an ADR when changing the decision later would be costly, when several teams need to follow it, or when the reason is likely to be lost. Data storage, identity boundaries, a shared API contract and a major external dependency are reasonable candidates.

A routine implementation detail usually belongs in the code review. The distinction is consequence, not the seniority of the person proposing the change.

Keep one decision per record. “Our architecture” is too broad: it bundles choices with different owners, constraints and review dates. Link the supporting diagram, benchmark or security review rather than reproducing everything inside the ADR. The record should still explain the choice if the reader never opens the meeting minutes.

The fields that make an ADR useful

Start with an ID, a descriptive title, a status, an owner and the decision date. Then complete these fields:

  • Context: the problem and constraints at the time, including scale, team capability and any deadline that materially affects the choice.
  • Decision criteria: what matters most and why. Security, operating effort and recovery may outweigh feature breadth.
  • Options: credible alternatives, including retaining the current approach where that is feasible.
  • Decision: the selected option and its boundary. Say what it does not cover.
  • Consequences: the gains, costs, new responsibilities and failure modes the team accepts.
  • Evidence and uncertainty: links to tests or analysis, with untested assumptions marked plainly.
  • Reversibility and revisit trigger: what changing course requires and what event should reopen the question.
  • History: who accepted it, dissent or conditions, and the record it supersedes or is superseded by.

The CSV uses one row per field, with a prompt, an illustrative entry and a blank “Your record” column. Duplicate the file for each decision. Store the completed record where its intended readers can find it; do not put credentials or customer data in it.

Worked example: keep document generation inside the application

This is an illustrative decision for a fictional small product team, not an architecture recommendation for every business.

ADR-007: Generate customer PDFs using a background worker in the existing application. Status: accepted for this example.

The product needs to generate downloadable account statements. The team already operates one application and a job queue. The working assumption is 300 documents per day, with a possible burst of 60 requests in ten minutes. Those figures describe a proposed test scenario, not a measured customer workload.

Three options are considered. Synchronous generation keeps the implementation small but makes the customer wait while the document is built. A background worker uses familiar operations but requires job tracking, retries and a way to notify the customer. A separate document service isolates the workload but adds deployment, authentication and monitoring responsibilities.

The example decision is to use the existing queue and a background worker. The deciding factors are avoiding a long-running browser request and keeping the operating burden within the current team’s capability. It is not a claim that separate services are inherently wrong.

The acceptance conditions are explicit: repeat requests must not create conflicting statements; failed jobs must be visible to support; access to the finished document must be checked; and a representative burst must be tested before rollout. The ADR does not itself provide evidence that those tests passed.

The cost is additional job state, retry handling and support instructions. A queue outage can delay document delivery even while the main application remains available. That consequence belongs beside the decision, not in a later incident report.

Make “we can change it later” specific

For the worked example, the review trigger is a test showing that document jobs interfere with the main application, or a new isolation requirement the existing worker cannot meet. The trigger opens a review; it does not automatically dictate a separate service.

Moving later would require extracting the generation interface, transferring queued work safely and preserving document-access checks. Record those steps now. “Reversible” should not mean “somebody else will figure it out”.

An ADR can also expose uncertainty that needs a short experiment before acceptance. If nobody knows whether the library can render the required documents reliably, keep the decision proposed and assign the test. A meeting vote cannot replace the missing evidence.

Keep the history when the decision changes

Use a simple flow: proposed, accepted or rejected, then superseded if a later accepted record replaces it. Record changes to status with dates and owners. Rejection is worth preserving when it explains why an attractive option was ruled out.

AWS recommends preserving ADR history, retaining superseded records and keeping the collection accessible. In practice, link both directions: the old record names its replacement and the new record explains what changed.

Do not rewrite the accepted reasoning to make it look as though the team knew the future. If implementation still differs from the decision, link the outstanding work in the technical debt register. An accepted ADR is evidence of agreement, not evidence that every component complies.

A good record lets the next engineer challenge the decision without first reconstructing the meeting.

Download the editable decision record (CSV) ↓

Practical questions

Can a non-technical founder read an ADR?

Yes. Put the business consequence and decision criteria in plain language, then link the technical evidence. The founder need not review every implementation choice, but should understand a decision that changes cost, risk or a customer commitment.

Does every ADR need a review date?

Not necessarily. A specific event can be a better trigger, such as a new isolation requirement or a failed capacity test. Add a calendar review when an assumption is likely to expire or a commitment requires it.

What if the team disagrees?

Record the competing concern and the evidence needed to resolve it. Name the decision authority and any conditions of acceptance. Keeping the dissent visible is more useful than presenting a consensus that never existed.

Put this to work

Sources checked 8 November 2026. The examples and worksheet are suggested working aids, not client results, legal advice or guaranteed outcomes.