CodeOpinion on YouTube · Open on YouTube
Design docs, RFCs and ADRs · Proficient · Lesson 79 of 98 · 10 min video, then about 2 hours of practice
Architecture decision records
After this you can write an ADR that records one decision, its context, the alternatives and its consequences, and keep a decision log for a codebase.
Why it matters
An ADR is a short document, often a page, recording one significant decision: why we chose Postgres over DynamoDB, why we moved to a modular monolith. Stored in the repository next to the code, they answer the question every new engineer asks: why is it like this? Focus on context and consequences. The decision itself is one line; the value is in what was known at the time and what it costs. Trap: editing old ADRs when a decision changes. Write a new one that supersedes it, so the history stays honest.
How to use this resource
ADRs as a log that answers 'why?', with examples.