Documenting Architecture Decisions
Nygard (2011) — origin of the ADR term and five-part template
2011 Cognitect blog post coining Architecture Decision Records — context, decision, status, consequences — kept in the project repository.
Michael Nygard (2011). Documenting Architecture Decisions. Cognitect blog, 15 November 2011.
URL: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
(To the extent possible under law, Cognitect waived copyright on this post — CC0.)
The decision (meta)
The post is itself formatted as an ADR. The team accepted keeping ADRs in-repo as short markdown files so motivation survives team turnover.
Template we cite (industry ADR)
Target length: one to two pages. Whole document readable as a letter to a future developer.
What this is not (in our corpus)
Nygard’s ADR does not specify:
- Epistemic tiers on claims
- Assumption tables with falsification triggers and monitors
- Named decision owner at the commitment boundary
- Recorded dissent, contest path, or quality mechanisms
- Binding as immutable L0 with event-sourced supersession
Those are corpus (A)DR extensions — grounded in Genesis, not in this post. See Architectural Decision Records.
Further reading (external)
- Martin Fowler — Architecture Decision Record — bliki pointer and post-2011 ecosystem notes
- adr.github.io — community templates (e.g. MADR) and tooling