Back to all posts
Architecture7 min read·October 25, 2026

Architecture Decision Record Template: A Simple Guide

TB
ThynkBlox Team
Engineering

An architecture decision record preserves why a consequential technical choice was made. Use the architecture decision record template below to capture five things: context, options, decision, consequences and revisit conditions. Write it so a founder or product owner can understand the business trade-off without needing to read code.

What belongs in an architecture decision record?

An architecture decision record, or ADR, answers a focused question: given what we knew and needed, why did we choose this approach?

Keep each record about one decision. Choosing how customers sign in is a suitable subject. Documenting every part of an application in the same record makes the reasoning harder to review.

Include enough detail to distinguish the chosen option from the alternatives. A reader should be able to see what mattered, what was uncertain and what disadvantage was accepted.

SectionQuestion it answersWhat to include
ContextWhat problem needs a decision?Business need, constraints and assumptions
OptionsWhat could we reasonably choose?Plausible alternatives and their relevant trade-offs
DecisionWhat are we choosing, and why?The selected approach and decisive reasons
ConsequencesWhat follows from this choice?Benefits, costs, risks and follow-up work
Revisit conditionsWhat would make us reconsider?Observable changes, evidence and a review owner

For broader guidance on keeping written material useful, see documentation best practices in software projects.

What architecture decision record template can you copy?

Copy the headings below. Replace the prompts with short, concrete statements. Add a descriptive title and a status such as proposed, accepted or superseded so readers know whether the choice is current.


Title: Choose [approach] for [specific purpose]

Status: [Proposed / Accepted / Superseded]

Context

We need to [business outcome]. The relevant constraints are [budget, delivery needs, capabilities or contractual requirements]. We are assuming [assumptions that could change]. This decision covers [scope] and leaves [related questions] open.

Options

  • Option A: [Approach]. Helps with [priority], but requires or risks [trade-off].
  • Option B: [Approach]. Helps with [priority], but requires or risks [trade-off].
  • Keep the current approach, if viable: [What happens if we defer the change].

Decision

Choose [option] because [reasons tied to the context]. We are accepting [main disadvantage] to meet [priority].

Consequences

  • Expected benefit: [What should improve].
  • Accepted cost or limitation: [What becomes harder or remains unresolved].
  • Follow-up: [Action, responsible role and evidence needed].

Revisit conditions

Review this decision if [observable condition]. [Responsible role] checks for that condition using [evidence]. If the condition occurs, compare the alternatives again before committing to a replacement.


Treat this as a writing aid. Leave out irrelevant prompts, but retain the reasoning and the cost of the choice.

What does a completed example look like?

The following example is hypothetical. Its requirements and outcomes are illustrative, rather than claims about a particular product.

Title: Keep booking and billing in one application

Status: Accepted

Context

A business is building a customer booking product. A confirmed booking must have a clear payment status, and support staff need to inspect both from the same customer view.

The initial development budget is limited. The product does not currently require booking and billing to be released independently. We assume the same development group will maintain both.

This decision covers the application's structure. It does not choose a payment provider or decide how refunds work.

Options

  • One application with separate booking and billing modules: Fits the current ownership and delivery needs. Changes still require checks across both modules.
  • Separate booking and billing services: Gives each area its own release boundary. Requires an explicit design for communication and for cases where one service succeeds while the other fails.
  • Defer the structural decision: Continue the prototype. This leaves the relationship between bookings and payment status undefined for the production build.

Decision

Choose one application with clearly separated booking and billing modules. The current priority is a dependable booking journey within the available budget.

We accept that booking and billing will share an application release. Independent releases are not a current requirement.

Consequences

The booking journey can be reviewed as a whole within the chosen application structure. The implementation still needs clear rules for failed payments, cancellations and retries.

The modules must have defined responsibilities. A change to billing must be checked against booking behaviour before release.

The technical lead will document how the product handles a successful payment when booking confirmation fails. The product owner will approve the customer-facing recovery experience.

Revisit conditions

Review the decision if a contractual requirement demands separation, or if release records show that shared releases repeatedly block necessary changes.

The technical lead will bring the evidence and a comparison of keeping or separating the modules. A request for separation alone does not approve the replacement.

A nontechnical owner can review this record by checking whether the priorities are correct and whether the accepted limitation is reasonable. For context on the alternatives, see microservices vs monolithic architecture.

How should a founder or product owner review it?

Review the business reasoning before debating the technology.

  • Is the problem clear? Identify the customer need or business constraint driving the choice.
  • Are the alternatives credible? Ask why each option was worth considering.
  • Does the decision follow from the priorities? A preference needs a reason tied to the product.
  • Is the downside visible? Look for a cost, limitation or risk that someone has explicitly accepted.
  • Can the revisit condition be observed? Replace “when we grow” with a specific requirement or recorded problem.
  • Is responsibility clear? Name the role that will gather evidence and raise the review.

Challenge unsupported certainty. If a record promises lower costs or faster delivery, ask whether that is measured, estimated or still an assumption. Label it accordingly.

What common mistakes should you avoid?

Writing only the conclusion. “We chose this because it is flexible” does not explain the choice. Describe the flexibility needed and what the alternative would prevent.

Listing unrealistic alternatives. Include options that could actually satisfy the requirement. Do not make the preferred option look stronger by comparing it with an unsuitable approach.

Hiding the cost. Include ongoing effort, limitations and unresolved questions. Approval should cover the trade-off, not just the expected benefit.

Using vague revisit conditions. “Reconsider later” gives no reason to act. Tie review to changed requirements or evidence that an assumption no longer holds.

Rewriting the original reasoning after a change. Preserve the accepted record. When a later decision replaces it, mark the earlier one as superseded and connect the two. This keeps the original explanation available.

When is an ADR unnecessary?

Reserve this template for choices whose reasoning will matter later: decisions with meaningful cost, difficult reversal or effects across several parts of the product.

A routine wording correction or an easily reversed visual adjustment usually needs less explanation. A decision record also does not replace a detailed design, a contract or a test plan. Use those where the work requires them, and refer to the relevant supporting material.

What questions come up about ADRs?

How long should an ADR be?

Aim for the shortest record that makes the choice reviewable. Keep detailed comparisons elsewhere when necessary, while preserving the decisive reasoning in the record itself.

Who should write and approve it?

Have the person closest to the technical choice draft it. Ask the owner of the affected business priority to review the costs and constraints. Set approval responsibility according to the decision's scope.

Can an ADR contain uncertainty?

Yes. State the assumption, explain why it is reasonable to proceed and define what evidence would challenge it. Do not present an untested expectation as an observed result.

What if nobody agrees?

Keep the status proposed. Identify the unresolved question and the evidence needed to answer it. If a decision must proceed before that evidence exists, record who accepts the uncertainty and under what conditions it will be reviewed.

Ready to build?

Let's turn these ideas into your next product.

Start your project