When Should You Create An ADR

Imagine you are a climber preparing to trek to Everest Base Camp.
There is more than one way to get there. You could take the Classic Everest Base Camp route, follow the Gokyo Lakes and Cho La Pass variant, tackle the Three Passes Trek, or take the historic route from Jiri.
Each can lead you toward the same destination, but the journeys are very different. They vary in time, difficulty, altitude exposure, scenery, logistics, and risk.
Suppose the climber chooses the Classic route.
Months later, someone looking only at the route they took might ask:
“Why didn’t they take the Three Passes route? It’s better.”
But better according to what?
Perhaps the climber had limited time. Perhaps they wanted a more established route, simpler logistics, or less altitude exposure. The decision only makes sense when you understand the circumstances in which it was made.
Architecture decisions have the same problem.
Months or years after a system has been built, someone might ask:
“Why did we choose a relational database over a NoSQL database?”
"Why did we build this capability rather than buy a SaaS product?"
"Why did we choose Azure App Service instead of deploying the application to AKS?"
Looking at the finished system may tell you what was chosen. It rarely tells you why that choice made sense at the time.
That is the problem an Architecture Decision Record (ADR) is designed to solve.
An ADR preserves the context behind a significant architecture decision so that someone looking at it later can understand not only what was decided, but why that path was chosen.
That leads to the more difficult question:
Which decisions are significant enough to deserve an ADR?

