Topic: architecture decision record template

Architecture Decision Record Template

Q: Do I need a tool to use ADRs?

Not really. mkdir doc/decisions, a text editor, and the template of your choice is enough to start. The adr-tools CLI by npryce automates numbering and status updates; most teams don't use it and don't miss it. Tooling becomes useful when you cross ~50 decisions and want search, link-checking, and supersede-graph visualization.

Three ADR templates dominate the field: Nygard's original, MADR, and the arc42 section-9 shape. Here they are side-by-side, with a decision tree for picking the right one before you copy-paste.

TL;DR

If you're starting today, start with Nygard — five sections, Markdown, no frontmatter, smallest onboarding cost. Adopt MADR when tooling needs to parse the ADRs (dashboards, exporters, audit scripts). Use arc42 section 9 when the ADR lives inside an arc42 architecture document and needs cross-references to the other sections. The decision tree at the bottom makes the call in under 30 seconds.

The three templates, side-by-side

Same decision ("Use Postgres over MongoDB") in each template, trimmed to fit. Full copy-paste versions are linked per-template below.

1. Nygard (the classic)

# ADR 1: Use Postgres over MongoDB

## Status
Accepted

## Context
Transactional workloads with strict consistency. Team has operational
experience with relational DBs. Compliance needs point-in-time recovery.

## Decision
Adopt PostgreSQL 16 as the system of record.

## Consequences
Good: strong schemas, mature tooling, team familiarity.
Bad: vertical scale ceiling; migration tooling is on us.
Neutral: JSONB covers document-store use cases for now.

Full Nygard template, with the two extensions →

2. MADR (structured)

---
status: "accepted"
date: 2026-04-24
decision-makers: ["@alice", "@bob"]
consulted: ["@security-lead"]
informed: ["#eng-platform"]
---

# Use Postgres over MongoDB

## Context and Problem Statement
Transactional workloads, strict consistency, compliance recovery window.

## Decision Drivers
* team operational experience
* point-in-time recovery requirement
* schema enforceability

## Considered Options
* Postgres
* MongoDB
* DynamoDB

## Decision Outcome
Chosen: Postgres, because it scores highest on drivers above.

### Consequences
* Good, because strong schemas + SQL.
* Bad, because vertical scale ceiling is real.

Full MADR 4.0 spec with frontmatter reference →

3. arc42 section 9 (embedded)

### 9.1 Use Postgres over MongoDB

**Status:** Accepted · **Date:** 2026-04-24 · **Deciders:** @alice, @bob

#### Context
From §3.1 (Business Context) — transactional workloads, consistency-first.
§10.2 requires 35-day point-in-time recovery.

#### Decision
Adopt PostgreSQL 16 as the system of record.

#### Consequences
Positive: schemas enforced, SRE playbooks apply, PITR well-understood.
Negative: migration tooling is a line item in §4.3.

#### Cross-References
- Context: §3.1
- Solution strategy: §4.1
- Building blocks: §5.2
- Runtime: §6.3
- Quality goals: §10.2, §10.4
- Risks: §11.2

Full arc42 template with cross-reference guide →

How they differ

Concern	Nygard	MADR	arc42 §9
Format	Free-form Markdown, 5 sections	YAML frontmatter + structured body	Nygard body + cross-reference block
Onboarding cost	Almost zero	Mild (readers learn field names)	Mild if you already know arc42; high if not
Machine-parseable	Limited (regex on headings)	Yes (YAML is unambiguous)	Partial (depends on body format chosen)
Fits existing doc	Standalone file per ADR	Standalone file per ADR	Embedded inside arc42 document
Best scale	Small-to-mid teams, ≤100 ADRs	Mid-to-large orgs, tooling-enabled	Enterprise with arc42 mandate
Storage convention	`doc/decisions/NNNN-*.md`	`docs/decisions/NNNN-*.md`	Section 9 of `docs/architecture.(md\|adoc)`, optionally transcluded
Adopted by	Thoughtworks, most OSS projects	Structured-docs teams, adr/madr ecosystem	European enterprise, regulated industries

Decision tree — which template?

Are you already using arc42 for your architecture documentation?
- Yes → use arc42 section 9. The cross-references are the value; don't throw them away.
- No → continue.
Does any tool (dashboard, exporter, audit script, LLM) need to parse your ADRs?
- Yes → use MADR. The YAML frontmatter is the reason it exists.
- Plausibly in 6 months → use MADR; migrating later is worse than starting structured.
- No → continue.
Are you the first person on your team to adopt ADRs?
- Yes → use Nygard. Lowest onboarding friction, highest chance the practice sticks.
- No → match the existing format; consistency beats theoretical fit every time.

Short version: default Nygard, upgrade to MADR when something downstream actually depends on structure, use arc42 only if arc42 is already in the room.

Common mistakes across all three

Writing before the decision is made. ADRs are retrospective. If you're still exploring, you're writing an RFC or a design doc, not an ADR.
Skipping "Alternatives Considered." Half the audit-trail value is in what you didn't pick. Nygard's base template doesn't require this; add it anyway.
Going past 250 words. Long ADRs don't get read. If the decision needs more context, link out to a design doc — don't stuff it into the ADR.
Leaving Status as a free-text field. Enforce an enum: Proposed | Accepted | Deprecated | Superseded by X. Anything else makes the log unsearchable.
Storing ADRs in a separate repo from the code. Monorepo, co-located, committed with the PR. Separate docs repos drift within two months.

How WhyChose helps

The hardest part of any ADR template isn't the template — it's getting the reasoning out of the 40-message ChatGPT thread where you actually thought it through. WhyChose ingests your ChatGPT or Claude export and emits one draft record per decision, in whichever shape you pick (Nygard, MADR, or arc42). You land the draft with a PR; the template's opinions about structure take care of themselves. The open-source extractor is the same engine, runnable locally against your own exports.

Get early access