“Architecture Decision Record Template: Columns, Example and Step-by-Step Guide”

What is an architecture decision record?

architecture decision record template is a key topic in modern project management and teamwork. An architecture decision record is a versioned text file that documents a single architectural decision: the forces at play, the option chosen, and what the team accepts as a result. It is written when the decision is made, stored next to the code, and never rewritten. If the decision changes, a new record supersedes the old one and both remain readable.

The format was popularised by Michael Nygard in 2011, and its durability comes from a constraint: one decision per file, short enough to read in five minutes, immutable once accepted. Those three rules turn architecture documentation from a wiki that rots into a log that accumulates institutional memory.

What an ADR is not: a design document, a specification, or a meeting minute. A design document explains how a system works today and is expected to be updated. An ADR explains why a fork in the road was taken on a particular date, and is expected to stay frozen. Confusing the two produces documents that are either too long to write or too vague to trust.

What does the template actually need to contain?

Five elements are non-negotiable. Everything else is a format choice.

MADR adds four sections that pay for themselves on decisions with genuine alternatives: decision drivers (the criteria you will judge against), considered options (including the one you rejected and why), pros and cons per option, and confirmation (how you will verify the decision held). If the decision was obvious, skip them. If three senior engineers disagreed for a week, they are the only sections that matter.

What does the Nygard template look like?

This is the minimal format. Copy it verbatim into `docs/adr/0017-shared-database-with-rls.md`.

# ADR-0017: Serve all tenants from a shared PostgreSQL cluster with row-level security

Date: 2026-03-04
Status: Accepted

## Context

We run 412 tenant accounts on a single-tenant deployment model. Provisioning a new
tenant takes 3 days of engineering time and costs $140/month in infrastructure.
Sales forecasts 90 new tenants in the next 12 months.

## Decision

We will consolidate tenants onto a shared PostgreSQL 16 cluster and enforce tenant
isolation with row-level security policies on every table.

## Consequences

Positive: provisioning drops to minutes, infrastructure cost per tenant falls,
schema migrations run once.

Negative: a bad migration affects every tenant, noisy neighbours need query
governance, and the isolation guarantee now depends on policy correctness.

Follow-up: load test at 3x current peak, add a policy-coverage test to CI.

The whole record is under 200 words and answers every question a new engineer will ask in eighteen months: why is this shared, when did it change, and what did we give up?

What does the MADR template look like?

Use this when the decision had real alternatives. It is the same skeleton with the reasoning exposed.

# ADR-0021: Use an append-only outbox table for order events

* Status: accepted
* Deciders: platform leads, payments lead, SRE lead
* Date: 2026-04-11

## Context and Problem Statement

Order state changes must reach the fulfilment and analytics services. Today the
application writes to the database and publishes to the broker in the same request,
which produces roughly 40 lost events per week during broker incidents.

## Decision Drivers

* No lost order events during broker outages
* P99 order write latency under 250 ms
* No new infrastructure the SRE team must operate in 2026

## Considered Options

1. Outbox table with a polling publisher
2. Change data capture from the replication log
3. Dual writes with a retry queue

## Decision Outcome

Chosen option: "Outbox table with a polling publisher", because it removes lost
events without adding infrastructure and reuses the existing worker fleet.

### Consequences

* Good, because event delivery becomes at-least-once and auditable in SQL.
* Good, because no new operational surface is introduced.
* Bad, because publishers add 50-150 ms of latency to downstream consumers.
* Bad, because the outbox table needs a retention job and monitoring.

### Confirmation

A monthly chaos test kills the broker for 10 minutes; the reconciliation job must
report zero missing order events, and the alert fires within 5 minutes.

## Pros and Cons of the Options

### Outbox table with polling

* Good: no lost events, simple to reason about, SQL-queryable.
* Bad: polling adds latency and database load.

### Change data capture

* Good: lowest application complexity, near-real-time.
* Bad: new connector to operate; schema changes need coordination.

### Dual writes with retry

* Good: smallest code change.
* Bad: does not fix the failure mode; retries lose ordering.

## Links

* Refines ADR-0012 (event schema ownership)
* Implementation epic: PLAT-884

Both templates are text files in the repository, reviewed like code. That is the entire tooling requirement; the rest is convention.

What does a filled-in example look like end to end?

Here is a complete ADR for a decision most teams face: choosing a tenant isolation model. It is written as it would be committed, not as a teaching example.

The reasoning behind it, in the record’s own words: single-tenant provisioning consumed three days of engineering per customer and $140 per month in infrastructure. At 412 tenants and a forecast of 90 more, the marginal model was not sustainable, and the team had already automated the migration of tenant schemas. Schema-per-tenant was rejected because migrations across 500 schemas would take hours and fail partially; database-per-tenant was rejected on cost.

The consequence section is what makes the record useful later. It states plainly that a bad migration now affects everyone, that noisy neighbours require query governance, and that isolation correctness moves from infrastructure to policy. Eighteen months later, when someone proposes splitting the largest tenant onto its own cluster, the record tells them the original reasoning and the accepted risk — which is exactly the conversation you want, instead of a restart.

How do the columns map to a review conversation?

The template’s value is that each column forces a specific question, and the questions are hard to dodge in writing.

Two practical constraints keep the format honest. First, write the context before the decision, even if you already know the answer — the order exposes whether the drivers actually support the choice. Second, cap the record at 600 words. Longer records are usually design documents wearing an ADR’s clothes, and they stop being read.

How do you write one in 45 minutes?

Step 1: Number and title it (2 minutes). Use a sequential number and a decision-shaped title. “ADR-0017: Serve all tenants from a shared PostgreSQL cluster” is a decision; “ADR-0017: Database strategy” is a topic and will attract essays.

Step 2: Write the context with numbers (10 minutes). Three paragraphs maximum: what the system does today, what changed, and what it costs. Include the figures you would quote to a manager.

Step 3: List the drivers (5 minutes). Four to six criteria, ordered. If everything is a driver, nothing is.

Step 4: List the options honestly (10 minutes). Include the status quo and at least one option you disliked. A record with one option is a press release.

Step 5: State the decision and its consequences (10 minutes). Active voice, present tense. Then write the bad consequences first; if you cannot name any, you have not thought about it.

Step 6: Define confirmation (5 minutes). A test, a metric, a date. This is what separates a decision record from a wish.

Step 7: Get two reviewers and merge (3 minutes plus waiting). One reviewer who will operate the system, one who will pay for it. Then commit it. Do not hold it for consensus; a decision with an owner and a date beats a decision with six signatures.

The timing is not aspirational. Teams that adopt this cadence report producing 30 to 50 records a year, which is roughly one per sprint for a platform group.

What do the numbers say about doing this well?

Three worked examples, using conservative assumptions.

Example 1: the cost of re-litigating a decision. A platform team of six spends two hours in a meeting revisiting a database choice that was settled fourteen months earlier, then a further four hours writing a comparison document. At a $70 loaded hourly rate, six people for six hours is $2,520. A 400-word ADR takes 45 minutes, or about $52. Two such meetings a year exceed the entire annual cost of writing records.

Example 2: the cost of a reversal without a record. A team adopts a message broker on a Friday, discovers six weeks later that the operations team cannot support it, and migrates back. Rework is 9 engineer-days at $600 a day: $5,400, plus two weeks of delayed roadmap. The ADR that would have surfaced “who operates this?” in the drivers section costs less than one hour of the rework.

Example 3: the review budget. A 40-record year at 45 minutes each is 30 hours of writing. Add 20 minutes of review per record across two reviewers, and the total is about 56 hours — 1.4 working weeks for a team of five. That is the whole annual cost of a decision log, and it is smaller than most teams’ meeting time on architecture in a single quarter.

The pattern: ADRs are not documentation overhead. They are a way to spend an hour now to avoid spending a day later, with the added benefit that the hour produces an artefact.

What are the trade-offs between lightweight and heavyweight records?

Three trade-offs deserve naming. Speed against memory: a five-line record written today beats a perfect template never filled. Immutability against accuracy: editing an accepted ADR keeps it tidy and destroys the audit trail; superseding keeps history and leaves a chain to follow. Breadth against depth: one decision per record is slower to write than a combined “architecture decisions” document and far faster to review, search, and supersede.

There is also a social trade-off. Written decisions make disagreement visible and attributable, which some teams find uncomfortable. That discomfort is usually the sign the record is doing its job.

What mistakes do teams make with ADRs?

• Recording decisions after the fact. A record written post-hoc rationalises rather than informs; write it before implementation starts.
• Editing accepted records. Change the status to “Superseded by ADR-00XX” and write the new one.
• Writing essays. Anything past 600 words is a design document; split it.
• Skipping consequences. A record with no downsides is a press release.
• One option only. If there was no alternative, there was no decision — write a note, not an ADR.
• Filing them outside the repository. ADRs belong in `docs/adr/`, versioned with the code they describe.
• No index. A `README` listing number, title, status, and date makes the log usable; without it, nobody finds ADR-0009.

How does Doitify support decision records?

Disclosure: Doitify is our product. The connection is practical rather than architectural. Decisions create work — a spike, a migration, a policy test — and that work needs an owner, a due date, and a link back to the record. Doitify’s project documents sit beside the board, so an ADR can be attached to the epic it authorises, and the follow-up tasks in the consequences section become real backlog items instead of a paragraph.

The part a tool cannot do is the judgement: which decisions deserve a record, who decides, and when to supersede. Keep ADRs in the repository where engineers already read them, and use the project tool to track the consequences. That split keeps the log authoritative and the work visible.

Conclusion

An architecture decision record template is a small piece of infrastructure for organisational memory. Five sections, a number, a date, a status, and a refusal to edit history. The Nygard format is enough for most days; MADR earns its extra sections when the decision was genuinely contested.

Start with the next decision you are about to make, not with a retroactive sweep of the last three years. Write it in 45 minutes, name the consequences you accepted, and commit it beside the code. In eighteen months, when someone asks why the database is shared, the answer will be one link away instead of one meeting away.

If this post on architecture decision record template was helpful, you might also enjoy Meeting Productivity Statistics (2026): What the Data Actually Shows and Project Dashboard: What Should It Include?.