mediumConceptDesignMidSeniorStaffLead
What belongs in an architecture decision record, and how do you decide a decision deserves one?
6 min readUpdated 2026-08-15
Answer
Short answer
An ADR captures the context that forced a choice, the options considered with the reason each was rejected, the decision, and the consequences including the costs you accept.
Decision records are valuable when they preserve the trade-off, not when they decorate a repository. Good decision records state context, options, the decision, consequences, and what would make the decision worth revisiting. Weak decision records repeat the final answer and lose the rejected alternatives. Strong decision records help a future team understand why the architecture is shaped this way before they change it.
Was this answer helpful?
Likely follow-ups
- Someone proposes reversing an ADR from eighteen months ago. What do you do with the original document?
- How do you stop ADRs from being written after the fact purely to justify a choice already shipped?
- Where do ADRs sit relative to an arc42 or C4 document, and what belongs in which?
- How would you handle a decision made by one team that constrains three others?
Related questions
- You want to reverse a decision recorded in an ADR two years ago, and everyone who made it has left. How do you go about it?hardAlso on adr and governance6 min
- You need every service's pipeline to run a security scan, a license check, and require signed artifacts before deploy. How do you enforce that across a hundred repositories without ending up with a hundred slightly different pipeline files?mediumAlso on governance4 min
- Every architecture document you have inherited is out of date. How do you write documentation that survives contact with a changing system?mediumAlso on adr4 min
- The business wants to change a rating factor next Monday. Walk me through what actually has to happen.hardAlso on governance5 min