River
Y CombinatorBacked by Y Combinator
Log InStart Free

Free template

Architecture Decision Record Template

A template for recording significant technical decisions, plus a ready-made first record, a finished example, team conventions and a register of which decisions still hold.

Edit with AIDownload (.docx + .csv)

Free download · No account needed

What you get

Pack of 7 files: 5 documents, 2 spreadsheets

Architecture Decision Record Template
  • Recording ConventionsDocument
  • Reading a Status RegionDocument
  • Record TemplateDocument
  • ADR 0001 Record Architecture DecisionsDocument
  • ADR 0002 Read Replicas for the Reporting QueriesDocument
  • Decision RegisterSpreadsheet
  • Link MapSpreadsheet
RiverArchitecture Decision Record Template

Record Template

NNNN. A title in the imperative, naming the decision

Date: YYYY-MM-DD  ·  Sequential, monotonic, never reused

Status

One state word from your own vocabulary, on its own line. Nothing else on that line: no parenthetical, no date, no qualifier. This is the field the register reconciles, because tooling can write a link here or delete the word.

Context

The forces in play, in the present tense, without arguing for the outcome. The numbers somebody measured. What was not known.

Considered Options

Every option genuinely proposed, including the one chosen and including doing nothing. Not in the original format; added because a record naming only the winner cannot stop the argument recurring.

Decision

One paragraph, starting We will. Then why the winner won, then why each other option lost. Where nobody gave a reason, it says nobody gave one.

Consequences

Both directions. What gets easier, and what gets harder.

Review

Review due: date plus your cadence. What would change our mind: the observation that would make this decision wrong.

Page 1 of 1170 words

How to write an architecture decision record

An architecture decision record (ADR) is a short document that explains one significant technical decision: why it was needed, what the team chose and what follows from it. A good one also names the options the team turned down, fits on a page or two, and carries a number, a date and a status. It follows the same template as the team's other records. Once accepted, it is never rewritten; if the decision changes, a new record supersedes it.

The reader who matters most is the engineer who arrives in two years and wonders why the system works this way. The code shows what you built. Only the record shows what you turned down, and why.

A man arranges sticky notes on a whiteboard covered in diagrams while a colleague by the window watches
Write the record while the options are still on the board. Photo: Tool., Inc on Unsplash

Decide which decisions need a record

Michael Nygard coined the term in a 2011 blog post. He kept records for "architecturally significant" decisions: those that affect "the structure, non-functional characteristics, dependencies, interfaces, or construction techniques"1. Microsoft's Azure guidance gives a shorter test: record choices that affect a system's structure or key quality attributes, or are difficult to reverse2.

In practice, that means writing one when a decision:

  • picks a database, framework, language or cloud service
  • changes how parts of the system talk to each other, such as an API or a message format
  • sets a rule for the whole system, such as how users sign in or how long data is kept
  • settles an argument between two or more serious options
  • is one a new engineer will ask about

Skip choices that are cheap to change or already set by a team standard. After an outage, the incident postmortem records what happened; any design change it leads to gets its own record.

Pick one template and agree on the rules

Nygard's original has five parts: title, context, decision, status and consequences. MADR (Markdown Architectural Decision Records), an open template now at version 4, makes the list of options considered a core section3. Its optional sections cover decision drivers, pros and cons, and how you will confirm the decision is followed.

The parts of a decision record

PartWhat goes in itWatch for
TitleThe decision itself, such as "Serve reports from a read replica"A topic, such as "Database"
StatusOne word from your team's list, such as proposed, accepted or supersededDates or notes on the same line
ContextThe forces and facts, with numbers, in neutral languageArguing for the answer
OptionsEvery serious option, including doing nothingListing only the winner
Decision"We will…", why it won and why each other option lostReasons nobody actually gave
ConsequencesWhat gets easier and what gets harderBenefits only
ReviewYour confidence, and what would make you revisit itA date nobody plans to check

Agree on the house rules while the folder is still small. Martin Fowler suggests one file per record, numbered in sequence, with a name that captures the decision4. Keep the files in the repository of the code they govern; doc/adr is a common folder. Never reuse a number, and write down the status words your team allows.

Write the context, options and decision

Start with the context, and keep it neutral. In Nygard's format, the context describes the forces at play (technological, political and social) in "value-neutral" language that simply states facts. Give the numbers you measured: "month-end reports hold table locks for 40 seconds" tells a later reader far more than "performance was a concern."

Then list every serious option, including doing nothing when that was a real choice, with the pros and cons of each. Give every losing option a one-sentence reason. If nobody gave one, say so: a reason invented later reads exactly like a real one.

State the decision in active voice, starting "We will", as Nygard's format asks. List the consequences in both directions; he wanted all of them, "not just the 'positive' ones." Fowler also suggests recording your confidence in the decision and the changes that should prompt a rethink.

ExamplePart of a sample decision recordAn illustrative example adapted from ADR 0002 in this template. The team and numbers are made up.

ADR 0002: Serve the reporting queries from a read replica

Status: Accepted

Context: At month-end close, four finance dashboards aggregate 240 million invoice rows on the primary database. The slowest query ran for up to 51 seconds, and p99 checkout latency rose from 90 ms to 2.4 seconds.

Options: a read replica, a nightly copy, a data warehouse, materialized views, a covering index, or running the queries overnight.

Decision: We will point the dashboards at one read replica. It changes none of the analysts' queries and can be undone in an afternoon. Nobody argued against materialized views on refresh cost, and we did not measure it.

Consequences: Checkout stops slowing at month end. Reports may lag the primary, usually by under a second, and the replica costs about $310 a month.

  • A title that is the decision. Someone scanning the list learns the outcome without opening the file.
  • Numbers in the context. Measured figures let a later reader check whether the problem still exists.
  • An honest gap. It admits which argument nobody made, rather than inventing a reason.

Review it before you accept it

A record starts as proposed and becomes accepted once the team agrees. Amazon Web Services' guidance suggests opening the review meeting with 10 to 15 minutes5 in which everyone reads the record and adds comments. If the team rejects the proposal, record the reason, so the same debate doesn't start again.

Settle who signs off before you write. The UK Government Digital Service's framework for public-sector teams ties approval to a decision's reach6. A team lead signs off one that stays within a team; a program architecture forum takes one that affects several teams. The framework also asks each record to list the stakeholders consulted and link to supporting documents.

Check what your tooling writes

The command-line tool adr-tools fills in Accepted as the status when it creates a record7 and has no option to start one at proposed. If your team reviews first, change the status by hand or give the tool a template that says Proposed.

Before you ask for review

  • The title states the decision, not the topic
  • The context gives facts and numbers, and argues for nothing
  • Every serious option is listed, including doing nothing
  • Each rejected option has a reason, or says none was given
  • The consequences include at least one cost
  • The status is one word from your team's list
  • Any record this one replaces or amends is linked both ways

Supersede a record instead of editing it

Once a record is accepted, leave its text alone. Fowler writes that an accepted record "should never be reopened or changed"4 and should be superseded instead, and Microsoft calls the collection an append-only log. The record is evidence of what the team believed at the time.

To replace a decision, write a new record, mark the old one superseded and link the pair in both directions. An amendment is different. If the new record only extends the old one, the old one stays accepted and gains a link. Marking it superseded would retire a decision that still applies.

Then check what the old record now says. When adr-tools supersedes a record, it adds a "Superceded by" link and removes the line reading Accepted7, leaving a misspelled link and no status word. When you audit a folder, search for both spellings, and treat a link-only status as unconfirmed until someone checks.

Keep a register

One row per record, with its status copied exactly as the file shows it, next to the status your rules give it. Where the two differ, someone has to confirm whether the decision still holds. The template on this page includes one.

When a decision grows out of a long proposal, keep the argument in an RFC or design doc and the outcome in the record. A solution architecture document can then point to each record instead of repeating it.

How to use this template

Use the files on their own: fill in Recording Conventions as a team, copy Record Template for each decision, and log every record in the Decision Register. ADR 0002 shows a finished record to aim for.

Or open them in River with Edit with AI. Send the records you already have, in any shape: a repository folder, a wiki export or the thread where a decision was made. River copies each record's status exactly as written, checks it against your team's status words and fills the register. It never edits a record or guesses a status.

  1. Download it or open it in River

    Get the five Word documents and two CSV sheets free, or open the template in River to work with AI.

  2. Settle your conventions

    Agree on your status words, whether records start as proposed, and how a replaced record is marked. River suggests a default for each.

  3. Write or add your records

    Copy Record Template for each new decision, or send River your existing records to fill the Decision Register and Link Map.

  4. See which decisions still hold

    Review the flagged statuses and broken links, ask River which decisions are still in force, and supersede rather than edit.

What's in the template

The decisions still in force, and the ones the records cannot answerThe Decision Register, the Link Map, and the three lists they produce.
Architecture Decision Record Template
RiverDecision Register

Decision Register

Illustrative rows for a fictional team, Larkfield.

RecTitleStatus region, verbatimStatusReconciliation
0003Postgres for the primary storeAcceptedacceptedagrees
0005Sync writes to the search indexAccepted  /  Amended by [0011]acceptedagrees
0007Queue per tenantSuperceded by [0012]unknownno state word
0008gRPC between servicesAccepted  /  Superceded by [0013]ambiguoustwo states
0009Feature flags in Redisunknownno state word
0010Terraform for all environmentsCurrentunknownoutside the vocabulary

Two columns, not one. A register reporting only the normalized value has thrown away every distinction in the last column, and the distinction is the finding. Both spellings live in the sheet, in their own cells, so a search for either one lands on the row.

0008 says both. The tool deletes only a line reading exactly Accepted, and only when it retires the record, so a hand-typed link, or a word in lower case or with a trailing period, leaves both in place.

Four of these six records cannot tell you whether the decision still holds.

RiverLink Map

Link Map

One row per edge, not per record, because a relation is a string somebody typed.

FromToRelation, as writtenReciprocalIn graph
00050011Amended byAmendsNo
00110005AmendsAmended byYes
00070012Superceded bySupercedesNo
00080013Superceded bymissingNo

The last row exists on one side only. 0008 says it was retired and 0013 never claims to have retired it, so which of the two is wrong is the interesting question, and nothing repairs it on the record's behalf.

Every reverse edge is absent from the diagram by design. The graph generator drops any relation whose string ends in the word by before drawing, so a pair that survives only on the reverse side appears nowhere and raises nothing.

Relation as written and relation normalized are separate columns, for the same reason status is.

RiverStill In Force

What is still in force

Three lists. The third one is the point.

In forceNot in forceRecords cannot say
0003 Postgresnone0007, 0008, 0009, 0010
0005 Sync writes

0005 is in force, and it has been amended. An amendment extends a decision rather than retiring it, so the original keeps its status and gains a link. Filing one as a supersession retires a decision that still governs, and no tooling catches it.

No record here has a retired status. Two records point at replacements, yet neither has a state word saying it was retired, so the Not in force list stays empty.

0007 almost certainly is retired. It says so with a link and it lost the word to the tooling. Until the conventions document says a link on its own is sufficient evidence, it stays unknown rather than becoming a guess with a green cell.

A published contents page generated from this folder would show all six, identically.

  • Record TemplateTitle, status, context, considered options, decision, consequences and a review line, with guidance for each part.
  • ADR 0001 Record Architecture DecisionsThe first record, which makes the case for keeping records, with five options weighed and the costs accepted.
  • ADR 0002 Read Replicas for the Reporting QueriesA finished record for a made-up team: measured context, six options, costs named and a review date.
  • Recording ConventionsThe 10 questions to answer once as a team, from status words and file paths to spelling and review cadence.
  • Reading a Status RegionWhy a record's status line can mislead, how common tools cause it, and what to record in the register instead.
  • Decision Register sheetOne row per record: its status exactly as written, the status your rules give it, and any mismatch.
  • Link Map sheetOne row per link between records, showing whether the other record links back and the target exists.

Common questions

What should an architecture decision record template include?

At minimum, the five parts of Michael Nygard's original format: a title, the context, the decision, a status and the consequences. MADR adds the options you considered, and the UK government's framework adds a date, the stakeholders consulted and links to supporting documents. This template keeps Nygard's five and adds a date, the options and a review line naming what would change your mind.

How long should an architecture decision record be?

One page is usually enough, and two is the most. Nygard said the whole document should be one or two pages long, and Fowler suggests a single page with the most important material first. Link to benchmarks, diagrams and longer design documents instead of pasting them in, so the decision still reads clearly on its own.

Who writes an architecture decision record?

Anyone on the team can write one, but each record needs a named owner. In the process AWS describes, the owner brings the proposal to a team review, then marks it accepted or rejected. In the UK government's framework, decisions that reach beyond one team go to an architecture forum or board for sign-off.

Can you change an ADR after it is accepted?

Not its substance. An accepted record stays as written; if the decision changes, write a new record that supersedes it and link the two. Whether typos and broken links may be fixed in place is a rule to settle once, in writing, and this template's Recording Conventions document asks it directly.

What is the difference between an ADR and a design document?

A design document describes how a system or feature should work and covers many decisions at once. An ADR records a single decision at a point in time, with its reasons and consequences, and stays as written once accepted. Use the design document or RFC to argue the case, then file a record for each decision it settles, linking back to it.

Is this architecture decision record template free?

Yes. The five Word documents and two CSV sheets download free, and no account is needed. Each sheet starts with illustrative rows that show the problems a register catches; delete them when you add your own. Choose Edit with AI to work on the same files in a free River workspace.

What does Edit with AI do?

Edit with AI opens this template in your own free River workspace, then asks for the decision records you already have, in any format. River asks up to four questions about your conventions, copies each record's status exactly as written and fills the Decision Register and Link Map. It reports what it can't confirm and never edits your records.

Sources

  1. Cognitect. “Documenting Architecture Decisions.” cognitect.com (opens in a new tab)

  2. Microsoft Learn. “Maintain an architecture decision record (ADR).” learn.microsoft.com (opens in a new tab)

  3. MADR. “About MADR.” adr.github.io (opens in a new tab)

  4. Martin Fowler. “Architecture Decision Record.” martinfowler.com (opens in a new tab)

  5. AWS Prescriptive Guidance. “Architectural decision record process.” docs.aws.amazon.com (opens in a new tab)

  6. GOV.UK. “Architectural Decision Record Framework.” gov.uk (opens in a new tab)

  7. GitHub. “adr-tools/src/adr-new at master.” github.com (opens in a new tab)

Written by

Chandler Supple

Co-founder & CEO, River

Chandler has spent the last six years working in AI, building tools for millions of users and Fortune 100 companies. In 2025, he co-founded River to build a new kind of operating system for AI agents.

LinkedInGitHubX

Reviewed by

Brian Joseff, Co-founder, River

LinkedInX

Related tools and templates

More free templates