Why it gets skipped in the moment
At decision time, the reasoning feels obvious — of course we chose this database, of course this is the right pattern, everyone in the room agrees. Writing it down feels redundant precisely because it's so clear right now, which is exactly the feeling that makes it get skipped.
That obviousness is temporary. New team members, future-you, and anyone revisiting the decision under different constraints will not share the context that made it feel obvious at the time.
What makes a record actually useful later
A useful ADR states the alternatives seriously considered and why they were rejected, not just the chosen option — the rejected alternatives are often the most valuable part, because they tell a future reader 'we already thought of that, here's why it doesn't work' before they waste time re-litigating it.
It should also state the conditions under which the decision should be revisited, turning a static record into an actionable trigger rather than a historical curiosity nobody checks again.
Making it a habit, not a policy nobody follows
Policies requiring ADRs tend to get skipped under deadline pressure unless writing one is genuinely the path of least resistance. Templates that take under ten minutes to fill in, embedded directly in the pull request for any structurally significant change, survive deadline pressure far better than a separate wiki process.
The habit compounds: a team with six months of consistent ADRs has a genuinely different, much more legible codebase history than one with none, even if the actual decisions made were identical.
The rejected alternatives in a good ADR are often more valuable than the chosen option. They save the next person from re-discovering the dead end.MNB Software Practice
Key actions
- Write the ADR within the same session the decision is made
- State rejected alternatives and why, not just the chosen option
- Define the condition that should trigger revisiting the decision
- Embed the template in the PR, not a separate wiki process