How'd we get here? A guide to Architectural Decision Records
summary
Architectural Decision Records capture why a choice was made, the context, the decision, and its consequences so future work avoids blind refactors; examples include a REST API naming/pagination spec and a rule for non-breaking migrations to support Kubernetes rolling updates. Recommended formats: Michael Nygard format, MADR and y‑Statements; recommended tooling: adr-tools CLI to emit, supersede and generate a TOC for ADRs in-repo. Small teams keep ~15 ADRs per long-lived project and use CI to refresh listings.
AI-written summary · about
chapters (31)
- 0:00Intro
- 2:57How it goes
- 4:04The consequences
- 4:47Who am I
- 5:37Sustainable Architecture
- 6:44Architectural Knowledge
- 7:35Understanding Where You Come From
- 8:39Making Better Decisions
- 9:47Ghost of the Past
- 11:50Architectural Decision Records
- 12:50Context
- 16:04restful APIs
- 18:43Decision
- 19:46JSON payloads
- 20:52Consequences
- 24:51Example Consequences
- 27:23Formats
- 28:59When do we write them
- 29:39What do I think
- 30:44Technical debt
- 31:40Consequences field
- 32:49When and for what
- 36:07Can you change an ADR
- 36:20ADR Flow
- 36:56Where to put ADRs
- 40:21ADR Tools
- 41:28Creating a New ADR
- 45:23Demo Time
- 47:37QA
- 52:37Track Search
- 53:53Outro
related talks
14mArchitecture Decision Records: Make Peace with Your Docs
14mArchitecture Decision Records
43mGetting Started with Architectural Decision Records
43mWorking Efficiently with Architecture Decision Records (ADRs)
46mCreating Effective and Objective Architectural Decision Records (ADRs)
42mIntroduction to ADRs
15mCreating effective and objective architectural decision records (ADRs)
37mArchitecture Decision Records - How not to get lost in the past