Architecture Decision Record: The Complete Guide (2026)

An architecture decision record is a short document that captures one significant technical choice, the context that forced it, and the consequences of going that way. Teams keep them in source control next to the code, write them in plain Markdown, and treat each one as immutable once accepted. ADRs answer the question every new engineer asks six months in: "why did we build it like this?" If your documentation strategy has a gap where decision history should be, an ADR archive fills it.

This guide covers what an ADR is, the canonical template, when to write one, a full worked example, how ADRs differ from design docs and RFCs, and the mistakes that turn ADR archives into write-only graveyards. By the end you should be able to write your team's first ADR before lunch.

What is an architecture decision record?

An architecture decision record is a one to two page document that records a single architecturally significant decision. Each ADR includes the title, status, context, decision, and consequences. The format was popularized by Michael Nygard in a 2011 blog post and has since been adopted across AWS, Microsoft Azure, Google Cloud, and most serious engineering organizations.

The shape matters more than the prose. An ADR is not a design doc, not an RFC, not a wiki page. It is a record. Once a team accepts an ADR, no one edits it. If the decision changes, you write a new ADR that supersedes the old one and link them. The trail of supersessions is the architectural history of your system.

ThoughtWorks Tech Radar has listed lightweight ADRs in the Adopt ring since 2018, and as of the Volume 31 Tech Radar (April 2025) ADRs remain in Adopt, with the firm noting that teams who write them avoid "rehashing" old decisions during onboarding and audits (ThoughtWorks Technology Radar, 2025).

Why do architecture decision records matter?

Software decisions evaporate. A senior engineer makes a call in a Slack thread, the thread scrolls away, six months later a new hire questions the same choice, and the team relitigates it with worse context. An ADR archive is the durable answer to "why."

A few specific things ADRs do well:

• Onboard new engineers faster. A new hire can read 20 ADRs in an afternoon and understand the bones of your system better than they would from a week of reading code.
• Prevent re-litigating settled decisions. When someone proposes "let's switch to GraphQL," the team can point to ADR-0017: "Use REST + OpenAPI for public API" and decide whether the original context still holds.
• Force clear thinking up front. Writing the context and trade-offs surfaces disagreements while the cost of changing course is still cheap.
• Make audits and compliance reviews painless. SOC 2 and ISO 27001 auditors love decision logs. Pointing them at /docs/adr ends conversations that would otherwise take hours.

The cost is small. A good ADR takes 30 to 60 minutes to write. The benefit compounds for years.

The standard ADR template (Markdown)

Most teams start with the Michael Nygard template because it's the simplest thing that works. Copy this into docs/adr/0001-record-architecture-decisions.md and you're done with the meta-decision before you've started.

# ADR-NNNN: Short title of the decision

- Status: Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXXX
- Date: YYYY-MM-DD
- Deciders: Names of people who made the call
- Tags: optional, e.g. `database`, `auth`, `infra`

## Context

What is the issue we're seeing that motivates this decision? What forces are at play (technical, business, social)? Describe the constraints, the goal, and the alternatives that exist. Two to four short paragraphs is enough.

## Decision

What we are doing, in plain language. One paragraph. State it as a directive: "We will use Postgres as the primary datastore."

## Consequences

What becomes easier? What becomes harder? What new risks does this introduce? List positive, negative, and neutral consequences honestly. If you only list positives, the ADR is broken.

## Alternatives considered

What else did we look at? Why did we reject each one? One sentence per alternative is fine.

## Links

- Related ADRs
- Spike branches, prototypes, benchmarks
- External references (vendor docs, RFCs, blog posts)

A few teams add an "Implementation notes" section, but resist scope creep. The whole point of the ADR is that it's short. If you need 4,000 words, you need a technical documentation template like a design doc, not an ADR.

For a more structured variant with explicit fields for non-functional requirements and decision drivers, see the MADR template at adr.github.io/madr. MADR is great for teams that already write detailed RFCs and want a tighter structure. For most startups, plain Nygard is enough.

A worked ADR example

Theory is easy. Here's an ADR a real team would actually write. The scenario: a SaaS startup at 10k users decides whether to keep using a single Postgres database or split into a read replica plus a separate analytics warehouse.

# ADR-0023: Use Postgres logical replication for analytics, defer warehouse split

- Status: Accepted
- Date: 2026-04-12
- Deciders: Alice (CTO), Bob (Backend Lead), Carmen (Data)
- Tags: database, analytics, infra

## Context

Our analytics queries (cohort retention, MRR breakdowns) hit the primary
Postgres on a 5 minute cron. They're slow but not slow enough to break the
app. We've grown from 2k to 10k users in 6 months, and queries now occasionally
spike CPU on the primary above 80%.

The team is considering three options: stay on a single primary, add a Postgres
read replica for analytics, or pipe events to a dedicated warehouse like
BigQuery or ClickHouse. We have one full-time backend engineer and no data
engineer. The product roadmap has us shipping a billing rewrite in the next
quarter and a separate compliance project after that.

## Decision

We will provision a Postgres logical replica on Neon, point all analytics
jobs at the replica, and defer the warehouse decision until our analytics
queries hit a use case logical replication cannot serve (most likely:
multi-source joins, time-series aggregates over 100M rows, or BI tools that
require a wide-column engine).

## Consequences

Positive: zero application changes, no new tech to operate, the primary stops
spiking under analytics load, and we can revisit the warehouse decision with
real data on which queries are actually slow.

Negative: the replica adds roughly $40 per month to our infra bill. Logical
replication has a known lag of 1 to 5 seconds, which is fine for analytics
but would not be fine for read-heavy product queries. We are betting that
our analytics needs do not outgrow Postgres in the next 6 months.

Neutral: this decision will need to be revisited when MRR analytics queries
take more than 30 seconds on the replica. Carmen will own the review.

## Alternatives considered

- Stay on a single primary: rejected because the CPU spikes are already
  user-visible during peak hours.
- BigQuery + Fivetran ETL pipeline: rejected because the all-in cost is
  $400+ per month and we have no one to operate the pipeline.
- ClickHouse self-hosted: rejected because we have one backend engineer.

## Links

- ADR-0008: Use Postgres as the primary datastore
- Spike branch: https://github.com/example/app/pull/847
- Neon logical replication docs: https://neon.tech/docs/...

Notice the shape. The context names real numbers (2k to 10k users, 80% CPU, 6 months). The decision is one paragraph. The consequences include a real cost. The alternatives are short and honest about why each was rejected. There's a clear trigger for revisiting the decision.

That's a real ADR. It took maybe 40 minutes to write, including the discussion that surfaced "Carmen will own the review."

When should you write an ADR?

Not every decision warrants one. The rule of thumb: write an ADR for any decision that will be hard to reverse, has consequences across more than one team, or that you would want a new engineer to find when they ask "why did we do this?"

Concrete triggers:

1. Adopting a new technology (new database, new language, new framework, new cloud provider).
2. A structural choice (microservices vs monolith, sync vs async messaging, REST vs GraphQL, see the API versioning discussion for an example of a structural API decision).
3. A non-functional commitment (a hard SLA, a security control, a multi-region requirement).
4. A trade-off you might forget you made ("we accept eventual consistency in the user table for now").
5. A decision that overrides an existing ADR (the new ADR supersedes the old).

The opposite test is just as useful. If a junior engineer can change their mind tomorrow with no consequence, it's not an ADR. If they would need a Slack thread, a meeting, and three approvals, it probably should be.

When NOT to write an ADR

ADR archives die from over-recording, not under-recording. Skip the ADR for:

• Code style choices (4 vs 2 spaces, eslint rules). Put these in a documentation style guide or a config file.
• Library version bumps. Bumping React from 18 to 19 is not an ADR unless you're also choosing a new render strategy.
• Decisions that affect only one engineer for one week. Personal tooling choices don't need a record.
• Decisions you can A/B test cheaply. If you can ship both behind a flag and pick the winner in a week, just do that. Write the ADR after, if at all.

A useful frame: an ADR records a decision you commit to. If you don't commit, don't record it.

ADR vs design doc vs RFC: what's the difference?

These three formats overlap and teams confuse them constantly. The shortest distinction:

In practice, a healthy engineering org uses all three:

• An RFC starts the conversation about a major change.
• A design doc plans the implementation once the RFC is accepted.
• ADRs record the specific architectural commitments made during the project.

A design doc might generate three or four ADRs as decisions get nailed down. The design doc is the planning artifact; the ADRs are the lasting record. When the design doc gets stale six months later, the ADRs are still accurate because no one edits them.

If you're starting from zero and only have time for one of these, pick ADRs. They're the smallest unit of useful documentation.

How to start an ADR archive in an existing codebase

You don't have to write 50 ADRs covering every decision your team has ever made. That project never finishes. The standard playbook:

1. Create docs/adr/ in your repo. One ADR per file, numbered sequentially.
2. Write ADR-0001 about adopting ADRs. Yes, the first ADR is about ADRs themselves. It states why the team is adopting them, the template you're using, and where they live.
3. Write ADRs for decisions going forward. Don't backfill historical decisions unless someone is actively confused by one.
4. Add an "ADR" item to your design review checklist. Every significant change should ask: does this need an ADR? Most won't. Some will.
5. Review the archive quarterly. Are any ADRs now superseded by reality? Mark them. This is the only kind of ADR maintenance that's worth doing, and it follows the same principles as broader documentation maintenance.

A 12-person team typically lands on 20 to 40 ADRs in the first year, then maybe one or two new ones per month after that. If you're writing five a week, you're either in a major rewrite or you're using ADRs for things that should be Slack threads.

Where should ADRs live?

The dominant convention is docs/adr/ inside the source repository. Pros: the ADRs version with the code, you can review them in pull requests, and they survive when team members leave.

The downside is that non-engineers (PMs, security reviewers, auditors) often can't easily browse a folder of Markdown files in a private repo. The fix is to publish the ADR archive as a static site.

Tools like Log4Brains, adr-tools, and adr-viewer generate static sites from docs/adr/. For teams that already maintain a documentation site, the simpler move is to surface the ADRs there. AI-powered platforms like Docsio can ingest the docs/adr/ folder and render it alongside your product documentation, with search and navigation included. That keeps the ADRs in source control where engineers want them, and makes them readable on a public or auth-gated site for everyone else.

For teams without a docs site at all, even a Notion or Confluence page that mirrors the repo folder is better than nothing. Pick the path of least resistance. Adoption matters more than the perfect tool.

How do you keep ADRs from going stale?

ADRs themselves don't go stale. That's the whole point of immutability. What goes stale is the implication of an old ADR. The decision was right in 2024 and is wrong in 2026 because the team is bigger or the product has shifted.

Three lightweight habits keep the archive useful:

• Quarterly review meeting. 30 minutes. Skim the index, flag any ADRs the team thinks are no longer valid, write superseding ADRs for any that survive the discussion.
• Tag ADRs with a "review by" date for high-stakes decisions. Anything with a security or scaling commitment gets a 12-month review trigger.
• Link ADRs from code where it matters. A comment in payments/processor.ts that says // ADR-0034: PCI scope kept to Stripe Elements is the cheapest possible way to keep the decision visible in the place it actually applies.

This is the same approach a healthy documentation governance program takes with policies and runbooks. Decisions, like docs, decay if no one ever looks at them.

Common ADR mistakes

After watching enough teams adopt ADRs, the same patterns of failure show up:

The novel. A 4,000-word ADR with five appendices. Nobody reads it. The point of the format is brevity, not exhaustiveness. If you need more space, the artifact is a design doc, not an ADR.

The empty consequences section. "Consequences: This will improve performance." That's not consequences, that's a decision restated. Real consequences include the negative ones: cost, complexity, risk, lock-in. If your consequences read like marketing copy, the ADR is broken.

Editing accepted ADRs. Once accepted, ADRs are immutable. If a team starts editing old ADRs to "keep them current," the decision log loses its archaeological value. The whole point is that future readers can see what the team knew at the time.

Writing ADRs nobody can find. A docs/adr/ folder no one knows about is decoration. The fix is integration: link from PRs, mention in onboarding, surface in your docs site, point new hires at the index on day one.

Skipping alternatives. "We chose Postgres" is a decision; "we chose Postgres because we evaluated MongoDB and DynamoDB and the consistency story for Postgres was the best fit for our billing data" is an ADR. The alternatives section is what makes the document useful three years later when someone asks "did we ever consider Mongo?"

Treating ADRs as approvals. ADRs record decisions the team has made. They're not the place to argue about a decision. That's what RFCs are for. If your ADRs have 40 review comments debating the decision itself, you're using the wrong format.

Can AI help write architecture decision records?

Yes, with caveats. The hard part of an ADR is not the writing. It's the thinking: identifying which decisions are architecturally significant, capturing the real context, and being honest about the consequences. AI can speed up the writing once that thinking is done.

A reasonable workflow: the engineer who made the call writes a five-bullet summary in Slack ("Decided X, because Y, instead of Z, trade-off is W"), and an AI agent expands it into the template. The engineer reviews, edits the consequences section to add the things the AI missed, and commits.

Docsio's AI agent can do this directly from a prompt, then publish the resulting ADR to a hosted documentation site alongside the rest of your product docs. The agent can also scan an existing docs/adr/ folder and surface ADRs in search results, so the archive becomes useful to people who never open the repo.

What AI cannot do is decide which decisions are architecturally significant for your team. That judgment requires context AI doesn't have, and writing an ADR for every minor choice is exactly the failure mode that kills ADR adoption. Use AI to lower the cost of writing a good ADR, not to inflate the volume of mediocre ones.

ADRs in the broader documentation system

ADRs are one genre in a documentation stack that includes internal documentation, runbooks, SOPs, API references, and product docs. They each answer a different question:

• ADRs answer "why did we choose this?"
• Design docs answer "how will we build this?"
• Runbooks answer "what do I do when this breaks?"
• SOPs answer "how do we handle this recurring task?"
• API docs answer "how do I call this endpoint?"

A team that writes all five well operates faster than a team that writes none of them and faster than a team that writes only the wrong ones. ADRs are usually the highest-impact starting point because they're the cheapest to write and the slowest to depreciate.

The healthy pattern is a docs-driven development culture where every significant decision spawns at least a brief ADR, every significant feature gets a design doc, and the docs site indexes both. That's what mature engineering orgs look like, and it's a smaller jump from where most startups are than people assume.

Frequently asked questions

What is an architecture decision record?

An architecture decision record is a short document, usually one to two pages, that captures one architecturally significant decision. Each ADR has a title, status, context, decision, and consequences. ADRs are stored in source control as Markdown files, written once, and never edited after acceptance. If the decision changes, a new ADR supersedes the old one.

What goes in an ADR template?

A standard ADR template has five sections: title with a sequential number, status (Proposed, Accepted, Rejected, Deprecated, or Superseded), context describing the forces at play, the decision itself stated as a directive, and consequences listing positive, negative, and neutral outcomes. Some templates add an alternatives section and a links section for related material.

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

An ADR records a single decision in one to two pages and becomes immutable once accepted. A design doc plans an entire feature or system in five to fifteen pages and stays editable during the project. A design doc often produces several ADRs as specific architectural commitments get pinned down. ADRs persist as historical record; design docs typically go stale.

How many ADRs should a team write?

A 12-person engineering team usually accumulates 20 to 40 ADRs in the first year of adoption, then adds one or two new ones per month. Writing five ADRs a week usually means the team is recording decisions that should have been Slack threads. Writing zero usually means significant decisions are evaporating into chat history.

Where should architecture decision records be stored?

The dominant convention is a docs/adr/ folder in the source repository, with one Markdown file per ADR numbered sequentially. This keeps ADRs versioned alongside the code and reviewable in pull requests. Teams that need ADRs visible to non-engineers also publish the folder as a documentation site, often using their existing docs platform.

Start your ADR archive today

The fastest path to an ADR archive: create docs/adr/, write ADR-0001 declaring you're adopting ADRs, copy the Nygard template above, and write your next architectural decision against it. That's it. The first ADR can be done in 30 minutes, and the second is faster.

If you want the archive to be readable to PMs, auditors, and new hires without giving them repo access, Docsio generates a hosted documentation site from your existing files and keeps the ADR folder synced. The AI agent can also draft new ADRs from a prompt and publish them to the same site, so the writing cost stays low and the archive stays useful as the team grows.