top of page

Architecture Decision Record (ADR) Template

Shift Quality Editorial
Jul 16
8 min read

Updated: Oct 18

(Composite.) An engineer spends most of a day working out why a service talks to its database through a hand-rolled connection pool instead of the framework's built-in one. The person who wrote it has left. The commit message says "add pooling". Chat search finds nothing. Eventually a load-test spreadsheet in a shared drive explains it: the framework's pool leaked connections during one specific database failover, and the custom pool was a deliberate workaround. The engineer had a pull request open to "clean it up". Merging it would have reintroduced the leak.

Michael Nygard described this situation in 2011, in the blog post that introduced architecture decision records. Someone new to a project who finds a decision with no recorded reasoning has two options: accept it blindly, or change it blindly. "It's better to avoid either blind acceptance or blind reversal." An ADR is the short document that makes the third option possible: understand it, then decide.

This post gives a template, and then deals with the part most guides skip. Teams that adopt ADRs usually write the first ten enthusiastically. A year later, some of the "Accepted" decisions are no longer true, nobody knows which, and people stop trusting the log. Two additions to the template prevent that.

What an ADR captures

An ADR records one architectural decision. One per decision: bundling the database, the cache and the queue into one document means none of them can be superseded cleanly later.

Nygard's original format has five parts, and most templates since are variations on it:

  • Title: a short noun phrase.

  • Context: the forces at play, which Nygard lists as "technological, political, social, and project local".

  • Decision: what the team will do, in full sentences and the active voice.

  • Status: proposed, accepted, deprecated or superseded.

  • Consequences: the resulting context after the decision, including the negative and neutral effects as well as the positive ones.

He also set the length: "The whole document should be one or two pages long." Implementation details belong in code and docs, and timelines and owners belong in the project tracker.

Thoughtworks put lightweight ADRs in the Adopt ring of its Technology Radar in 2017 and 2018, recommending they live in source control rather than a wiki so they stay in step with the code.

The test: list the significant technical decisions your team made last quarter (from design docs, large pull requests and incident follow-ups) and count how many have a written record of why. The gap is your exposure to blind reversal.

The template

This version adds two sections to Nygard's: Alternatives considered, which almost every modern template includes, and Revisit if and Confirmation, which are what keep an ADR true after it's accepted.

# ADR-NNN: [Short noun phrase]

Date: YYYY-MM-DD
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX

## Context
What forces made this decision necessary now? Which constraints apply,
and where does each one come from?

## Decision
We will ... (specific and declarative)

## Alternatives considered
Each option we rejected, and the one or two sentences of why.

## Consequences
Good, bad and neutral. Specific enough to plan around.

## Revisit if
Measurable conditions under which this decision should be reopened.

## Confirmation
How we check the decision is still being followed: a test, a CI rule,
a review checklist item, or a scheduled review.

Number ADRs sequentially and never reuse a number. Keep them in a docs/adr/ directory in the repository the decision mostly affects, one Markdown file each (014-jwt-access-tokens.md), so they're reviewed in pull requests and versioned with the code. Never delete one: mark it Deprecated or Superseded and link to its replacement.

Context: say what changed, and where each constraint comes from

The context explains why the decision had to be made at this point.

  • Thin: "We need a database."

  • Useful: "Write volume has grown about tenfold in six months. The current SQLite persistence layer doesn't support concurrent writes at this level. The team has one person with operations experience, so we need a store that is mature to operate, not just fast."

The useful version records the assumptions the decision rests on, and those assumptions are what a future reader needs in order to tell whether the decision still holds. When a constraint drives the decision, record its source as well: a regulation, a contract, an internal policy and a habit carry very different weight. Documenting constraints without drowning the doc shows how to tell them apart.

The test: for each constraint in the context section, can a reader tell whether it's a law, a contract, a policy or an assumption? If not, the next person will treat all of them as unchangeable, or all of them as negotiable.

Alternatives considered: the section that makes it a decision

If there are no alternatives, there wasn't a decision, just a default, and a default rarely needs an ADR. List each option that was seriously considered, with the reason it lost.

MySQL: comparable features. PostgreSQL chosen for stronger JSON support and its extension ecosystem. DynamoDB: lower operating overhead. Rejected because existing queries depend heavily on joins that don't translate to a key-value model. MongoDB: the document model fits some use cases. Rejected because the team's experience is relational and we need to ship this quarter.

This section does three jobs. It shows the decision was deliberate. It answers the question every new engineer asks ("why didn't you just use X?"). And it records which alternative to reach for first if the decision has to be reversed.

Consequences: name what you're accepting

The positive consequences are why you made the decision. The negative ones are the valuable part, because they're what the next team will run into.

Negative:
  • Higher operating overhead than a managed key-value store: we need monitoring, backups and failover configuration.

  • Vertical scaling will become a limit; sharding will be needed if write volume grows another tenfold.

  • Schema changes need migrations, and moving to a different data model later would be expensive.

Vague worries ("might not scale") don't help anyone. A specific, accepted trade-off can be planned around, and it usually becomes a revisit trigger.

Revisit if: turn assumptions into triggers

Every decision rests on assumptions that can stop being true: load, team size, cost, a vendor's pricing, a regulation. Most ADRs bury them in the context and nobody notices when they change. Pull the important ones out as measurable conditions.

## Revisit if
- Sustained write volume exceeds 5,000 writes per second at peak
- The managed database bill exceeds 15% of infrastructure spend
- A second region becomes a requirement (data residency or latency)

A trigger turns "is this still the right decision?" from a debate into a check. MADR, the widely used Markdown ADR template, has a similar idea in its optional "More Information" section, which includes when the decision should be revisited.

The test: take your three oldest Accepted ADRs and write one revisit trigger for each from what's in the context section. If any trigger has already fired, you've found a decision that may need reopening, and nobody would have noticed.

Confirmation: check that the decision is still being followed

The second way ADRs go stale is quieter. The decision is still right, but the code has drifted away from it. An ADR says only the auth service talks to the session store, and two years later three services do. MADR's template includes an optional Confirmation section for exactly this: how compliance with the decision can be verified, for example through a design or code review, or a test using a library such as ArchUnit.

The best confirmation is automated. For a Java codebase, an ArchUnit rule turns the decision into a failing test:

// ADR-014: only the auth module may use the session store client
@ArchTest
static final ArchRule onlyAuthUsesSessionStore =
    noClasses().that().resideOutsideOfPackage("..auth..")
        .should().dependOnClassesThat().resideInAPackage("redis.clients..");

Where the services live in separate repositories, the same idea works as a CI check on dependency manifests. Where no automated check is possible, the confirmation is a named review step or a scheduled review date.

The test: for each Accepted ADR, is there a confirmation? Count the ones with none. Those are the decisions most likely to have drifted already.

How an ADR goes stale and how to keep it true. Assumptions change (load, cost, team), so the template adds revisit triggers. Code drifts from the decision, so it adds a confirmation check such as an ArchUnit rule. In the composite team, a quarterly review of 40 ADRs found 9 Accepted decisions no longer true; after adding triggers and confirmations, the next review found 1.

A worked example

# ADR-014: Use JWT access tokens with 15-minute expiry

Date: 2026-03-12
Status: Accepted

## Context
Sessions are opaque IDs stored in Redis. As we split into services,
each one validates sessions against Redis, which has made Redis a
bottleneck and given every service a Redis dependency.

## Decision
We will use signed JWT access tokens with a 15-minute expiry for
service-to-service authentication. Refresh tokens stay opaque and
server-side in Redis. Only the auth service talks to Redis.

## Alternatives considered
- Keep opaque sessions: familiar, but keeps the cross-service Redis
  dependency we're removing.
- 24-hour JWTs: simpler, but a stolen token stays valid for a day.
- JWTs with no refresh tokens: revocation would need a denylist,
  which brings back the shared state.

## Consequences
- Positive: services validate tokens without external state; Redis
  leaves the hot path.
- Negative: revocation waits up to 15 minutes; tokens are larger
  than session IDs; key rotation needs a runbook.

## Revisit if
- A security requirement needs revocation faster than 15 minutes
- Token size measurably affects latency on mobile clients

## Confirmation
ArchUnit rule onlyAuthUsesSessionStore in the shared build; key
rotation drill twice a year.

Half a page, and every section can be checked.

When to write one, and when not to

Write an ADR for a decision that affects how several components or teams work, locks in something expensive to reverse, picks one of several legitimate options, or that a new engineer would reasonably question. Don't write one for routine implementation choices or decisions with one obvious answer. Nygard's test still works: if "because we did" would be an inadequate answer to "why?", write it down. For a larger, more ambiguous design that needs discussion before deciding, a design doc comes first and the ADR records the outcome; architecture decisions you'll regret covers the kinds of decision most worth that care.

Keeping the log trustworthy over time

(Composite.) A platform team adopts ADRs and writes 40 in its first year. At the first quarterly review, it walks every Accepted ADR and asks two questions: is this still true in the code, and do its assumptions still hold? Nine of the Accepted decisions fail one or the other: four have drifted in the code, three rest on load or cost assumptions that changed, and two were quietly replaced by later decisions nobody marked as superseding them. The team adds revisit triggers and a confirmation to every Accepted ADR, automating the confirmation for six of them. At the next review, one fails.

Four habits keep the log useful:

  • A scheduled review, quarterly or twice a year, walking every Accepted ADR against its triggers and confirmation.

  • An index in docs/adr/README.md, grouped by area, so people can find the decision before they relitigate it.

  • Links from code, a short comment where a non-obvious design is the result of an ADR.

  • Supersede, don't edit, when a decision changes, so the history of why survives.

The test: at your next review, count the Accepted ADRs that fail either question. Track that number over time; it's the clearest measure of whether the log can be trusted.

What to do this week

Create docs/adr/ in your main repository if it doesn't exist. Write an ADR for the last significant decision your team made, using the template above, including at least one revisit trigger and one confirmation. Then pick your oldest existing ADR and check it against the code. If it no longer holds, mark it, and write the one that replaces it.

Final takeaway

An ADR exists so the next person doesn't have to accept or reverse a decision blindly. Keep each one short and about a single decision, give the alternatives and the negative consequences the most care, and add the two sections that keep it true: revisit triggers for when the assumptions change, and a confirmation for when the code drifts. A log people can trust is worth far more than a long one they can't.

Sources

Related reading

bottom of page