Architecture Decision Records: A Practical Guide for Teams

Architecture decision records give teams a simple way to capture major technical choices, the reasons behind them, and the trade-offs they accept. A clear ADR process helps reduce repeat debates, support better handoffs, and preserve system knowledge as projects grow and people change.

Hubert Olkiewicz[email protected]
LinkedIn
7 min read

An architecture decision record (ADR) is a short document that captures one significant technical decision, the context behind it and its consequences. Teams that keep ADRs in version control, review them like code and supersede them instead of editing them stop re-arguing old choices, and new engineers can see why the system looks the way it does. This guide covers what belongs in an ADR, a template, a worked example, the process, and how to keep the log useful for years. It is written for business and technical leaders who sponsor or build custom systems, where the reasons behind a choice matter as much as the choice.

Bitecode
Build Systems With Decisions in Mind
Bitecode builds tailored business software with modular components, helping teams make architectural choices that fit complex workflows.
Visit

TL;DR

  • An ADR records one architecturally significant decision: context, options, the choice, status and consequences. Keep it to a page or two.
  • Write it as a proposal, review it with the people affected, and mark it accepted. Never edit an accepted ADR; supersede it with a new one.
  • Store ADRs in the same repository as the code, numbered in sequence, so they travel with the system.
  • Record only decisions that are costly to reverse. Implementation details and undiscussed ideas turn the log into noise.
  • ADRs matter most in custom and modular systems, where a vendor, an integrator and your own team all build on the same foundation.

What an architecture decision record is

The format was popularized in a 2011 post on documenting architecture decisions, which describes an ADR as a short text file about a single decision made in response to forces on the project. AWS Prescriptive Guidance frames it the same way: a choice about a significant aspect of the architecture, with its context and consequences. The collection of records forms a decision log that people skim for an overview and read closely when they need the reasoning behind a design.

The point is memory. Architecture is the accumulation of its decisions, and Microsoft’s guidance on maintaining an ADR says the record is effectively an account of how and why the system came to be as it is. Without it, the rationale lives in chat threads and in the heads of people who eventually leave.

Which decisions deserve a record

Not every choice needs one. The Microsoft guidance limits ADRs to choices that affect system structure, key quality attributes (performance, security, availability), or that are hard to reverse. The arc42 documentation template says to document decisions that are important, expensive, large-scale or risky, and to use judgment about whether a decision belongs in a central place or next to the component it affects.

Good candidates in a business system:

Google Cloud’s ADR overview gives similar examples: a specific product choice such as Pub/Sub versus Cloud Tasks, or a configuration choice such as regional clusters for high availability.

What not to record

The Agile Alliance experience report on distributing design authority with ADRs describes a common failure: a team recorded an implementation detail (that a value is configurable) as an ADR and logged ideas before anyone discussed them. Review churn followed. Their fixes were template guidance on what makes a decision architectural and a rule to explore alternatives at a whiteboard first, recording only once a decision is actually made.

What goes inside an ADR

The core fields are consistent across sources. Michael Nygard’s format, quoted by arc42, uses a short noun-phrase title and four parts: context written as value-neutral forces, the decision stated as “We will…”, a status, and consequences that include all effects, not only positive ones. The GOV.UK ADR framework, published in November 2025, adds the date, the stakeholders consulted and links to supporting documents.

Field What it holds Common mistake
Title Numbered, states what was decided A vague topic label
Status Proposed, Accepted, Rejected, Deprecated or Superseded Leaving accepted records “proposed” forever
Context Forces, requirements, constraints Arguing for the answer inside the context
Options Serious alternatives with pros and cons Listing only the winner
Decision “We will…” in one clear statement Several decisions in one record
Consequences Good, bad and neutral effects, follow-ups Only the benefits
Review trigger What change should reopen the question Omitted entirely

Martin Fowler’s note on ADRs adds two habits worth copying: record the confidence level of the decision, and name the context changes that should trigger reevaluation. Microsoft’s guidance also recommends keeping records pithy and factual and splitting multi-phase decisions into separate records, rather than turning an ADR into a design guide.

A template you can copy

This is a compact template combining the fields above. Save it as a Markdown file such as 0001-short-title.md.

# 0001. Title that states the decision

Status: Proposed | Accepted | Rejected | Deprecated | Superseded by 00XX
Date: YYYY-MM-DD
Decision owner: name or team
Stakeholders consulted: names or roles

## Context
The forces at play: requirements, constraints, load, compliance,
team skills. Neutral wording.

## Options considered
1. Option A: pros, cons
2. Option B: pros, cons

## Decision
We will ...

## Consequences
What becomes easier, what becomes harder, follow-up work,
related ADRs.

## Confidence and review trigger
High / medium / low. Revisit if ...

Other templates exist, including Tyree and Akerman’s and MADR, and the community collection in the ADR repository on GitHub lists several. Start with the smallest version and add fields only when a real gap appears, as the Agile Alliance team did when they added guidance on what counts as architectural.

A worked example

The submillisecond ADR examples show a pair of records that illustrates the whole lifecycle. ADR 0001, dated 4 March 2026, chooses Postgres 16 for an order store at roughly 2,000 orders per second. Its consequences name 5,000 orders per second as the point to revisit. The decision matrix behind it weights five criteria: team familiarity and peak write throughput at 0.25 each, query flexibility at 0.20, operating cost and replay or audit at 0.15 each. Postgres scored 3.90, an event log 3.65 and DynamoDB 2.90.

Decision matrix scores for three order-store options

The close second place is the useful part: the record states when to look again. On 21 October 2026, ADR 0002 supersedes the first after peak load reached 4,600 orders per second, moving order events to a Kafka topic while Postgres remains the query store. ADR 0001 is not edited. It is marked as replaced, so anyone reading it later sees what was true, for how long, and why it changed.

For a financial or fintech team, the same pattern fits a ledger design choice, an audit-log strategy or a settlement-rail decision: state the load or regulatory assumption, name the threshold that invalidates it, and link the successor when it arrives.

The ADR process, step by step

  1. Identify the trigger and the owner. AWS guidance has the team recognize a decision that needs recording and assign an owner. Anyone can draft, but the team establishes ownership, and the owner approves content changes before acceptance.
  2. Discuss before you write. Explore alternatives on a whiteboard or in a call first. A record of an undiscussed idea invites argument instead of review.
  3. Draft in Proposed status. Document the problem, options, criteria and consequences from the template, in the product repository.
  4. Review. In the AWS process, reviewers read and comment briefly, and the record either stays Proposed with assigned actions, is Rejected with the reason recorded, or is Accepted once the owner adds a timestamp, version and stakeholder list. The Red Hat developer hub ADR repository uses a pull request with a minimum one-week review window, where an open request is Proposed, a merged one is Accepted and a closed one is Rejected.
  5. Match the approval body to the scope. The GOV.UK framework sends team decisions to the team lead, cross-team decisions to an architecture forum, department-wide ones to an architecture board and cross-government ones to a central design council. A company can mirror this: team lead, architecture group, then executive sponsor for decisions with budget or compliance exposure.
  6. Communicate. The continuous-architecture practice guide warns that this last step is the one most often forgotten, and asks whether a decision nobody knows about will be respected.
  7. Review after a while. A common habit, noted in the community ADR repository, is to revisit each record about a month later and compare it with actual practice.

Where to store and maintain ADRs

Keep ADRs in version control next to the code. The Microsoft engineering playbook suggests a doc/adr or doc/arch folder, with each ADR added as a pull request in Proposed status and merged when accepted. When several developers start records in parallel, it recommends using the related work item ID as the number to avoid collisions.

Cross-cutting decisions need a different home. The Agile Alliance team found that code-adjacent storage worked for component-local decisions, but a choice such as adopting gRPC over REST across all microservices called for a separate repository covering decision records, design guidelines and architecture briefings.

A decision log is only useful if the delivery pipeline surfaces it. Teams that already connect code hosting to quality gates, as in GitLab and SonarQube integrations, can add an ADR check to the same review flow so architecture changes without a record get noticed.

Where to store and maintain ADRs

Supersede, never rewrite

Accepted ADRs are immutable. When new insight demands a different choice, write a new ADR, link it from the old one, and mark the old one Superseded. Fowler describes the benefit: a clear log of how long each decision governed the work. AWS adds that the new record carries the change history and the old record stays in the log.

Common failure modes

  • “We’ll add it later.” The Agents Playbook ADR pattern notes that later never comes, and recommends blocking pull requests that change architecture without a record.
  • Mega-records. One record covering many decisions cannot be superseded cleanly. Split them.
  • Silent edits. Changing an accepted decision destroys the history that makes the log valuable.
  • Missing alternatives. A record with no rejected options reads as justification after the fact.
  • Paperwork mindset. The community repository frames ADRs as a chance to lead teammates by discussing the why, rather than mandating the what.

A reasonable length is a page or two. The Agents Playbook suggests 50 to 200 lines, which is enough to hold context and alternatives without becoming a design document.

Why ADRs matter more in modular and custom builds

When a system is assembled from pre-built components, the important decisions are about boundaries: what you accept as given, what you customize, what you host yourself and how modules talk to each other. Those choices outlive the project team. Without records, they migrate into the vendor relationship, where nobody on your side can explain them. With records, your team owns the reasoning even when someone else wrote the code.

Our view: decisions are part of the deliverable

We build custom business systems from modular, ready-made components, and our positioning is that up to 60% of the baseline system can be pre-built. That speed is only an advantage if the remaining 40% is steered by explicit choices. Which modules are adopted as they are, which are customized, which run self-hosted, how financial records stay audit-ready: each is an architectural decision, and each should be written down.

We think a client should finish an engagement able to read why the system is shaped the way it is, without calling us. A short, numbered decision log in the repository does that. It keeps customization client-controlled and long-term maintenance predictable, and it lets the next team accelerate work without accelerating chaos.

Bitecode

Building a system where decisions are traceable

If you are planning a custom platform, a financial module, an automation layer or a blockchain settlement flow, the most useful early artifact is the first dozen ADRs: hosting, data ownership, integration style, audit approach. We start projects from modular components so those decisions can be made against a working baseline rather than a blank page. Our custom business software and cloud application services are the places to begin, and a small MVP is a practical way to test the first decisions before committing to a larger program.

Bitecode

For teams weighing a first build, the guide to planning and judging a proof of concept pairs well with an initial ADR set, and our software diagram guide helps illustrate decisions that need a visual.

FAQ

How long should an ADR be?

A page or two is typical. Fowler describes ADRs as short, holding the decision, its context and significant ramifications. The Agents Playbook suggests 50 to 200 lines. If a record grows beyond that, it probably contains more than one decision or a design guide.

Who is allowed to write and approve an ADR?

In the AWS process any team member can draft one, but the team assigns an owner who approves content changes before acceptance. Approval scales with scope, from a team lead for local choices to an architecture board for organization-wide ones.

Can we change an ADR after it is accepted?

No. Accepted records are immutable. If circumstances change, write a new ADR that supersedes the old one and link the two. The old record remains in the log and shows how long that decision governed the work.

Should we write ADRs for an existing system?

Yes, where the reasoning is still recoverable. Microsoft’s guidance says to start an ADR at the onset of a workload and, for existing (brownfield) systems, to begin retroactively and then maintain it as an append-only log.

Sources

Articles

Dive deeper into the practical steps behind adopting innovation.

Software delivery6 min

From idea to tailor-made software for your business

A step-by-step look at the process of building custom software.

AI5 min

Hosting your own AI model inside the company

Running private AI models on your own infrastructure brings tighter data & cost control.

Hi!
Let's talk about your project.

this helps us tailor the scope of the offer

Przemyslaw Szerszeniewski's photo

Przemyslaw Szerszeniewski

Bitecode co-founder

LinkedIn