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.

Get early access