Somewhere in every engineering organization there is a decision that nobody can explain. A queue sits between two services that could just as easily call each other directly. A particular database was chosen over an obvious alternative, and the three people who argued about it have all left the company. The decision is load-bearing, and yet it is invisible. When you ask why, the best answer you get is a shrug and a sentence that begins with "I think someone decided that we needed to."
I have spent most of my career in regulated fintech, and I have come to believe that the single cheapest, highest-leverage practice a technical organization can adopt is the Architecture Decision Record. It is not a framework, not a tool you buy, not a methodology you certify in. It is a short document that captures one decision, the context that forced it, and the consequences you accepted. That is all. And it has saved my teams more time and credibility than any piece of tooling I can name.
What an ADR actually is
An Architecture Decision Record is a small, immutable document that records a single significant architectural choice. The canonical structure, popularized by Michael Nygard over a decade ago, is deliberately minimal: a title, a status, the context that prompted the decision, the decision itself, and the consequences. You write it at the moment the decision is made, commit it alongside the code it affects, and never edit it again. If the decision changes later, you write a new record that supersedes the old one.
The immutability is the part people resist and the part that matters most. We are trained to keep documentation current. But an ADR is not living documentation; it is a historical record. Its value comes precisely from the fact that it preserves what you believed and why at a specific point in time, including the things you turned out to be wrong about. A record that gets quietly rewritten to match present reality loses everything that made it worth keeping.
I want to be clear about scope, because over-application kills the practice. An ADR is for decisions that are costly to reverse and broad in their reach. Choosing your primary datastore is an ADR. Naming a variable is not. The test I give my teams is simple: if a competent engineer who joins in two years would be confused or frustrated by this choice, write it down.
The real cost of undocumented decisions
The expense of an undocumented decision is rarely visible on the day it is made. It surfaces months or years later, and it compounds. The most common form is the re-litigated debate. A team argues for an afternoon about whether to introduce an event bus, reaches a hard-won consensus, and ships. Eighteen months later, with different people in the room, the same argument happens again from a cold start, because nothing recorded that it had already been settled and on what grounds.
The second form is more dangerous: the fearful change. An engineer encounters a piece of architecture that looks wrong, and it might be. But because nobody can explain why it exists, the engineer is afraid to touch it, in case it is load-bearing in a way that is not obvious. So the strange thing stays, accumulates workarounds, and becomes genuinely load-bearing through sheer accretion. Undocumented decisions calcify your system around mistakes you would otherwise have corrected.
The most expensive sentence in engineering is "I don't know why we did it this way, so I'm afraid to change it." An ADR replaces that sentence with a paragraph you can actually evaluate.
Why this matters more under regulation
In consumer software, an undocumented decision is an inconvenience. In regulated fintech, it can be a finding. When an examiner, an external auditor, or your own second-line risk function asks why your system handles customer funds segregation the way it does, "the architecture evolved organically" is not an acceptable answer. You are expected to demonstrate that significant choices affecting data residency, money movement, access control, and resilience were made deliberately, by accountable people, with the trade-offs understood.
This is where ADRs quietly become a compliance asset rather than just an engineering nicety. A folder of dated, authored decision records is contemporaneous evidence of disciplined governance. It shows that when you decided to store personally identifiable information in a particular region, you considered the regulatory constraint and chose accordingly. I have walked auditors through ADR histories, and the conversation is dramatically calmer than the alternative of reconstructing intent from commit logs and the memories of people who may no longer be employed. The discipline of writing the consequences section also forces you to confront the regulatory implications before you ship, not after; more than once, writing down "this means customer data crosses a jurisdictional boundary" has stopped a decision in its tracks while we were still cheap to redirect.
The anatomy of a record that earns its keep
A weak ADR states the decision and nothing else. A strong one spends most of its words on context and consequences, because those are the parts that age into value. The context section should explain the forces in tension at the time: the deadline, the team's existing expertise, the regulatory constraint, the volume you were designing against. Someone reading it later should be able to understand the decision even if they think it was wrong, because they can see the box you were operating inside.
The sections I insist on are these:
- Context. The situation and constraints that made a decision necessary, written so a newcomer needs no other background.
- Decision. The choice, stated in active voice and unambiguous terms, with the alternatives you seriously considered and why you rejected them.
- Consequences. What becomes easier, what becomes harder, and what you are knowingly trading away. The negative consequences are the most important and the most often omitted.
- Status. Proposed, accepted, deprecated, or superseded, with a link to whatever replaced it.
I pay particular attention to the alternatives. A decision recorded without its rejected options reads like it was inevitable, and inevitable decisions invite no scrutiny and teach no lessons. When you write that you chose a managed message queue over a self-hosted one because you had no operational appetite for running it yourselves at your team size, you have given the future a gift. If the team triples and that constraint evaporates, the next engineer knows exactly which assumption to revisit.
Where the records should live
The location of your ADRs determines whether they get read, and whether they get read determines whether they get written. My strong preference is to keep them in the repository they describe, in a plain directory, as numbered Markdown files. They live next to the code, they are versioned with it, they show up in pull requests, and they are searchable with the same tools engineers already use all day. A decision that lives in a wiki nobody opens effectively does not exist.
Co-location with code does something else valuable: it ties the record to the change that implements it. When an ADR arrives in the same pull request as the architecture it describes, reviewers can evaluate the reasoning and the implementation together, as one unit. I have seen review comments improve decisions before they hardened, simply because the record was sitting right there in the diff inviting comment.
For decisions that span many repositories or sit above any single service, a dedicated architecture repository works well; the principle is the same. Whatever you do, resist the pull toward a heavyweight documentation platform. The friction of a clumsy editor and an approval workflow will, over time, quietly reduce the number of decisions anyone bothers to record, and a practice that only captures the easy decisions is worse than useless because it lulls you into a false sense of coverage.
The record as a thinking tool, not just an archive
The benefit I did not anticipate when I first adopted ADRs is how much they improve the quality of decisions while they are still being made. Writing forces a rigor that conversation does not. In a meeting, a confident voice and a whiteboard can carry a flimsy idea a long way. The moment you have to write down the consequences in a way a skeptical colleague will challenge, the flimsy parts become obvious. I have abandoned decisions halfway through drafting the record, because articulating the trade-offs revealed they were unacceptable.
This is why I encourage teams to write the ADR in the "proposed" status before the decision is final, and to use the draft as the artifact for discussion. Instead of debating in the abstract, people review a concrete document. The conversation becomes "this consequences section is missing the cost to our on-call rotation" rather than a vague exchange of opinions. The record turns an argument into a shared text everyone can edit together, which is a far healthier dynamic than the loudest person prevailing.
There is a leadership dimension here as well. When I ask for a proposed ADR before approving a significant architectural direction, I am not adding bureaucracy; I am asking the proposer to demonstrate that they have thought past the appealing first idea to its second-order effects. A team that cannot write a clear consequences section usually does not yet understand the decision well enough to make it.
How the practice goes wrong
ADRs fail in predictable ways, and most failures come from treating the form as the goal rather than the thinking. The first is volume: a team decides everything deserves a record, the directory fills with trivia, and the signal drowns. When every choice is documented, no choice is highlighted, and people stop reading. Reserve the practice for decisions that are expensive to reverse, and let everything else live in code and ordinary comments.
The second failure is the retroactive rewrite, where someone goes back and edits old records to reflect current reality. This destroys the historical value and quietly trains everyone to distrust the archive. If a decision changes, the discipline is to write a new record that supersedes the old one and to update the old one's status to point forward. The trail of superseded decisions is itself valuable; it shows how your thinking evolved and why.
The third failure is more insidious: ADRs written for an audience of nobody. If records are produced as a checkbox exercise and never consulted, they become theater. The fix is to make consultation a habit. Point new engineers at the ADR directory as required reading, and when a debate starts, ask first whether a relevant record already exists. The practice sustains itself only when reading the records is as normal as reading the code.
Starting without a grand initiative
You do not need executive sponsorship or a company-wide rollout to begin. The most successful adoptions I have seen started with one engineer writing one record for the next significant decision their team faced, and committing it to the repository. No announcement, no policy. The next time someone asked "why did we do it this way," there was an answer, and people noticed. Adoption spread because the records were useful, not because they were mandated.
If you want to seed the practice deliberately, pick your three most consequential current decisions and write records for them now, clearly marking them as reconstructions written after the fact. Backfilling is acceptable for a small set of foundational choices, as long as you are honest that the record was created later. From that point forward, the rule is simple: significant decisions get a record at the time they are made. The barrier to entry is almost nonexistent, which is exactly why the practice is worth defending against the people who will want to wrap it in process. A template, a directory, and a shared understanding of what counts as significant is the entire apparatus; the discipline is cultural, not technical.
Conclusion
Architecture Decision Records are a rare thing in our field: a practice with enormous return and almost no cost. They make decisions better by forcing the reasoning into the open while it can still be challenged. They make systems safer to change by replacing fear with explanation. In a regulated environment, they turn governance from a reconstruction exercise into a matter of opening a folder. I have never regretted writing one, and I have lost count of the times I wished a record existed for a decision someone made years ago and could no longer explain. Start with the next decision you face. Write down the context, the choice, and what you are giving up. Then commit it, and let the practice prove itself.