Topic: adr template nygard
The Nygard ADR Template (2026 Edition)
Michael Nygard's 2011 post "Documenting Architecture Decisions" launched the ADR practice. The template is five sections, short by design. Here it is in current Markdown, with the two extensions that have held up over fifteen years.
TL;DR
Nygard's original ADR has five sections: Title, Status, Context, Decision, Consequences. Nothing else. Two extensions have proven their weight since: Alternatives Considered (to capture what you rejected and why) and Stakeholders / Deciders (to record accountability). Anything beyond those seven sections is scope creep — you're writing a design doc, not an ADR.
The template (original 5 sections)
# ADR N: <Short noun-phrase title>
## Status
What is the status, as of this writing?
Proposed | Accepted | Deprecated | Superseded by ADR M
## Context
What is the issue that we're seeing that is motivating this decision
or change? State this in value-neutral language. Include forces at
play: technology constraints, team constraints, political constraints,
project/customer constraints.
## Decision
What is the change that we're actually proposing or doing? State this
in full sentences, with active voice: "We will..."
## Consequences
What becomes easier or more difficult to do because of this change?
Include positive, negative, and neutral consequences. Be honest about
the trade-offs.
That's the whole thing. Nygard's original ADR at Cognitect was a one-page Word document. Fifteen years of practice have validated the brevity.
The two extensions worth keeping
Nygard himself noted in follow-up talks that teams always added two sections. After watching dozens of teams adopt and evolve the format, these two always earn their keep:
Alternatives Considered
## Alternatives Considered
- **Option A:** Chosen above.
- **Option B:** Rejected because it required <constraint>.
- **Option C:** Rejected because <reason>.
- **Option D (do nothing):** Rejected because <reason>.
Without this, the reader six months later sees only the chosen path and assumes it was the obvious one. The "Option D (do nothing)" row is the one most teams forget — and the one reviewers most often flag.
Stakeholders / Deciders
## Stakeholders
- **Deciders:** @alice, @bob (made the call)
- **Consulted:** @carol (security review), @dave (SRE review)
- **Informed:** #eng-platform channel
Useful for two reasons: accountability (when something breaks, you know who to ping) and reversibility (if the people in "Deciders" have all left, the ADR is open for renegotiation, not sacred writ).
What not to add
Every team tries to add these. Every team regrets it:
- "Implementation Plan." That's what the PR description is for. ADRs describe what and why, not how.
- "Success Metrics." Belongs in the ticket, the OKR, or the retrospective — not the decision record.
- "Appendices" or "Further Reading" sections longer than three links. Put long material in a separate doc and link to it from "Context."
If you consistently feel the urge to add these, you're using ADRs for the wrong thing. Use RFCs for multi-page designs, ADRs for the single-sentence fork in the road.
How WhyChose helps
If you already sparred with ChatGPT or Claude over a technology pick — "should we use Postgres or Mongo for this?", "SQS vs Kafka?", "monorepo vs multirepo?" — the ADR is half-written already. WhyChose extracts those decisions from your chat export and emits Nygard-shaped records (exactly the seven sections above, filled in from the conversation itself). You get the ADR draft; you edit and commit. Same output format as the open-source CLI, which you can run locally against your own exports.
Related questions
Is the Nygard format still considered current?
Yes. It's been the de facto standard for 15 years. MADR (Markdown ADR) is a structured superset; arc42 section 9 and Microsoft Learn both adopt Nygard's five sections verbatim. You won't go wrong picking it.
How do I reference a superseded ADR?
Add Superseded by [ADR M](NNNN-slug.md) in the Status line of the old one, and Supersedes [ADR N](…) in the new one. This creates a bidirectional link that git-log can follow.
Can I use Nygard ADRs in Confluence or Notion?
Yes — the format is Markdown and renders cleanly in both. See the Confluence variant and the Notion variant for platform-specific tweaks.
Further reading
- ADR template in Markdown — copy-paste ready — a shorter version with the two extensions inlined.
- MADR template explained — the structured-frontmatter evolution.
- ADR example: Postgres vs MongoDB — the Nygard template, fully filled in.
- The ADR GitHub Action — a CI pipeline that lints the five Nygard sections this page defines and fails the PR when one is missing or empty.
- How to update an ADR (without breaking the audit trail) — what the Status field on the Nygard template actually changes through over a decision's lifetime, and the supersession protocol that keeps Context / Decision / Consequences immutable while the rest evolves.
- ADR supersession pattern — when to supersede, when to annotate, and how to stay bidirectional — the Nygard format has a dedicated Supersedes section; this page is the standalone reference for that field: the four triggers, the two-file atomic protocol, bidirectional pointer maintenance, and what happens when a supersession PR gets reverted.
- ADR numbering scheme — padding, gaps, and collision recovery — the filename-level companion to this template: 4-digit IDs, never-renumber discipline, and the merge-base allocator for parallel PRs.
- ADR status template — format, fields, and the lifecycle beyond Accepted — Nygard ships Status as an H2 heading by default; this page covers the migration to YAML frontmatter (recommended for any directory with tooling), the five companion fields that earn their place next to Status, and the optional Trial-Period state mature teams add for decisions that ship-and-revisit.
- TOGAF ADR template — keeps the Nygard five-section body unchanged and adds a seven-field frontmatter block that maps the decision into the TOGAF Architecture Development Method (Phase H change request, Architecture Building Block reference, Stakeholder Map / ARS / Capability Map traceability); the right pick for enterprises that need audit-trail defensibility on top of the Nygard body.
- ADR review checklist — what to look for before merging — the Nygard five-section structure (Context / Decision / Consequences) maps directly to three of the checklist's four categories; this page is the quality gate that should run after the author picks the template and before the PR is approved.
- ADR adoption guide — how to introduce ADRs to a resistant team — this template is often the starting point for teams considering ADR adoption; the adoption guide covers how to get from "I found this template" to "the team is writing ADRs for real decisions" — retrospective-first rollout, the two-champion model, the minimum viable three-field format for teams that find the full Nygard template too formal to start with.
- ADR lightweight template — LADR, Y-Statements, and the minimum viable format — for teams that find the five-section Nygard format too heavy for prospective ADRs: the three-field LADR variant (Title + Decision + Consequences), the Y-Statement single-sentence form, and the format progression path back toward Nygard-complete once the habit is established. The contrarian insight: lightweight formats are for prospective ADRs; Nygard-complete is actually easier for retrospective ones because the full context is already visible.