Architecture decision records: the cheapest insurance a project can buy
One page per decision, stored next to the code. Why we write architecture decision records on every engagement, and what goes in them.
Photo: Christina Morillo / Pexels
Six months into a project, someone asks why the system uses a message queue here, or why the team chose PostgreSQL over a document database. If the answer lives only in the memory of the person who decided, the project is carrying a hidden risk.
What an ADR is
An architecture decision record is a short document, usually under a page, that captures one decision: the context, the options considered, the choice made and its consequences. It lives in the repository, next to the code it explains.
- Context: the problem and the constraints at the time
- Options: what we considered, including doing nothing
- Decision: what we chose, and why
- Consequences: what gets easier, and what gets harder
Why they pay for themselves
New engineers onboard faster because the reasoning is written down. Debates end sooner because the trade-offs are explicit. When circumstances change, the team revisits a decision deliberately instead of drifting away from it.
How we use them
Every engagement starts with a handful of records written during the Define phase, covering hosting, data storage, authentication and integration patterns. We add new ones whenever a decision would be expensive to reverse. Clients keep all of them as part of the handover.
Code tells you what a system does. Decision records tell you why, and that is what you need when it is time to change it.
Working on something like this? We would like to hear about it.
Start a Project
