A year after launch, the team wants to replace its database. Everybody can see the current design is uncomfortable. But why was it chosen? Perhaps the team lacked a certain skill, the deadline was severe, or the product could not tolerate a risky migration. Or perhaps the decision was simply poor. Without its context, we cannot tell.
An Architecture Decision Record is a short record of a significant technical choice. It preserves not just what was chosen, but the conditions that made it reasonable at the time.
What deserves space in an ADR
A useful record states the problem, constraints, considered alternatives, decision and expected consequences. It should also make conscious sacrifices visible. A managed database, for example, may cost more but avoid building a specialist operations function.
It does not need to become a large architecture specification. A document nobody can quickly understand a year later is failing at its one job. A concise statement of context and trade-offs is often more valuable.
Record the reasons to revisit it
Teams sometimes use an approved ADR as a permanent defence: “We already decided.” But the choice was made under particular budget, skills, deadlines and traffic assumptions. Change those conditions and the original reasoning may no longer hold.
For important decisions, I would record what might trigger a review: increasing operating costs, regulatory changes or a new team boundary. If the decision is replaced, create a new record linked to the old one instead of silently rewriting history.
That preserves both how the system evolved and which assumptions changed along the way.
When records become bureaucracy
If every database index or method rename requires a committee, engineers will start writing documents for approval rather than better decisions. Use ADRs for choices that are hard to reverse, change ownership boundaries or materially affect future cost and operational risk.
Records are not substitutes for experiments or measurements. They explain why a trade-off was accepted. Architecture Fitness Functions can help verify that important constraints remain respected.
Good architectural memory does not make past decisions permanent. It helps a company understand why they were right — and recognise when they stopped being right.