Field notes. Opinions are marked as opinions.
Code tells you what the system does. It rarely tells you why it was built that way. Six months after a decision, the people who made it are in another team, or another company. What remains is a message queue nobody dares remove, a database nobody understands, and a vague memory that “there was a reason”.
An Architecture Decision Record, or ADR, is the cheapest fix I know for this. It is a short document, usually one page, that captures one significant decision and the reasoning around it. Michael Nygard popularised the format in a 2011 blog post, and it has barely changed since because it does not need to.
The shape of a record
Nygard’s original template has five parts. Keep to them.
- Title. Numbered and short. “ADR-014: Use PostgreSQL for the orders service.”
- Status. Proposed, accepted, deprecated, or superseded by another ADR.
- Context. The forces at play: requirements, constraints, team skills, deadlines, budget. Facts, not advocacy.
- Decision. One clear statement, in active voice. “We will use…”
- Consequences. What becomes easier, what becomes harder, what we are now committed to.
Many teams add a sixth: alternatives considered, with a line on why each was rejected. My opinion: this is the most valuable section. A future reader who sees that Kafka was considered and rejected because the team had two engineers and a Chennai-only deployment will not waste a week proposing it again, or will at least know which assumption to challenge.
A small example
Here is what a good one sounds like, in prose. A team building an invoicing tool for small Indian businesses needs to generate GST-compliant PDFs. The context says: about 20,000 invoices a day at peak, generation takes 300 to 500 milliseconds, and the team of four has no one who has run a queue in production. The decision: generate PDFs synchronously inside the web request for now. The consequences: simple to build and debug; a spike at month-end filing time may slow the app; if peak exceeds roughly ten times today’s volume, revisit with a background worker. The status: accepted.
Notice what that record does. It admits the weakness. It gives a trigger for revisiting. It would take ten minutes to write and might save a month of argument.
Rules I would insist on
Keep them in the repository. A folder of plain text or Markdown files next to the code, reviewed through the same pull requests. A wiki page that is three clicks away gets stale. A file in the repo gets seen by anyone who clones it.
Never edit an accepted record to change its meaning. If the decision changes, write a new ADR that supersedes the old one and mark the old one as superseded. The history is the point. If you rewrite it, you have erased the evidence of what people knew at the time, and you can no longer tell whether the old decision was wrong or merely overtaken.
Keep them short. If it needs five pages, it is probably a design document, and the ADR should link to it and record only the decision. One page is a good ceiling; it forces clear thinking.
Write them when the decision is made, not later. Memory of the alternatives fades within weeks. Writing the ADR is also a useful test: if you cannot state the context and consequences plainly, the decision is not ready.
What deserves a record
Not everything. A rough test: would reversing this decision later be expensive, or would a new joiner be surprised by it? Choice of database, messaging approach, authentication provider, how services talk to each other, how you handle multi-tenancy, a deliberate departure from company standards. Naming conventions and library minor versions do not need one.
A team that writes forty ADRs a month is documenting for the sake of it. A team that writes none is relying on memory. Somewhere around one or two a fortnight, for a busy product team, feels about right, though that varies with how much is being built.
What ADRs do for the team, beyond documentation
The side benefits are bigger than the archive. A proposed ADR in a pull request is a cheap way to disagree. Instead of a two-hour meeting where the loudest person wins, people comment on a page. Quiet engineers and freshers, who rarely speak up in a room, will often write a sharp comment. That is useful, and it is a reasonably good way to spread architectural thinking in a team.
It also makes decisions less personal. “The ADR says we chose this because of our 2024 deadline, and the deadline has passed” is a much easier conversation than “your design was wrong”.
New joiners get a guided tour. Reading ten ADRs in order tells you more about a system’s shape and history than a week of code reading, because you see the pressures that produced the code, not only the code.
Where this goes wrong
Two failure modes. The first is ADRs as ceremony: written after the fact to justify a decision already made, with the alternatives section filled in with straw men. Readers can smell it. The second is ADRs as bureaucracy: a mandatory approval board that turns a one-page note into a three-week gate. If the process slows teams down, they will stop doing it. Nygard’s approach, and my preference, is lightweight: the author writes it, the team reviews it in the normal pull request, and it is done.
There are small tools that number and template ADRs for you, such as adr-tools, but a folder and a text editor are enough. Do not spend a day choosing tooling for a document that takes ten minutes to write.
Figures and names in the examples are illustrative.
Leave a Reply