Architecture decision records: a template and habits that stick

Architecture decision records are one of those ideas everyone agrees with. Someone shares a template, the team writes two or three, and then the folder goes quiet while the real decisions keep happening in Slack threads and pull request comments.

The problem is rarely the format. It is the missing habits around it. Here is a template that stays small, plus the triggers and rituals that keep teams writing ADRs a year later.

Where ADRs come from

The idea comes from Michael Nygard's 2011 post, Documenting Architecture Decisions. His proposal was deliberately light: a short text file per decision, one or two pages long, stored in the repository next to the code. Each record has five parts: title, context, decision, status and consequences. Records are never deleted. When a decision changes, a new record supersedes the old one.

Nygard's argument for doing this is still the best one. Without the reasoning, a newcomer who meets a past decision can only blindly accept it or blindly change it. Both are expensive.

The practice has been widely recommended since. Thoughtworks put lightweight architecture decision records in the "Adopt" ring of its Technology Radar, and recommends keeping them in source control rather than a wiki.

Why most teams stop after three

Research on public repositories matches what most teams experience. A study from JKU Linz found that about half of GitHub repositories that use ADRs contain only one to five of them, which looks a lot like "tried it, then stopped." A found that about 63% of roughly 5,800 ADRs were created already marked "accepted", meaning they were written after the fact rather than used to make the decision.