Architecture Decision Record (ADR): What It Is and When to Write One

An architecture decision record, or ADR, is a short document that captures one significant technical decision, the reasons behind it, and the consequences the team accepted. It records what was chosen, what was rejected, and why, so anyone reading it later understands the call without having to track down the people who made it. ADRs are how engineering teams keep the reasoning behind their systems from disappearing.

Code shows you what a system does. An ADR shows you why it does it that way. Six months after a choice, the code is still there but the reasoning has often evaporated, and that gap is exactly what an ADR is built to close.

What is an architecture decision record?

An architecture decision record is a written record of one architecturally significant decision. "Architecturally significant" means the choice is hard to reverse or shapes a lot of the system: which database you use, how services talk to each other, whether you adopt a framework, how you handle authentication. Small reversible choices do not need an ADR. Choices you will have to live with for years do.

The format is deliberately light. An ADR is usually one page, written in plain language, focused on a single decision. The point is not ceremony. It is to capture enough context that a future engineer, who was not in the room, can understand why the team chose what it chose and what it gave up to get there.

ADRs grew popular because the alternative kept failing. Reasoning lived in people's heads, in chat threads, and in meeting memories, all of which fade. The team that built a system would move on, and the next team would inherit code with no explanation, afraid to change anything because nobody knew why it was built that way. An ADR is the cure for that fear.

What does an ADR contain?

Most ADRs follow a simple structure. You can adjust it, but these parts show up in nearly every version.

• Title. A short name for the decision, often numbered, like "ADR-012: Use Postgres for the events store."
• Status. Where the decision stands: proposed, accepted, deprecated, or superseded by a later ADR.
• Context. The situation and constraints that forced a decision. What problem were you solving, and what pressures shaped it?
• Decision. The choice itself, stated plainly. "We will use Postgres."
• Consequences. What follows from the choice, both good and bad. The tradeoffs you accepted, the doors it closes, the new work it creates.

The consequences section is the one people skip and later regret skipping. A decision with no recorded downside reads like it was free, which no real decision ever is. Writing the tradeoffs down is honest, and it saves the next team from rediscovering the cost the hard way.

When should you write an ADR?

Write an ADR when a decision is significant and hard to reverse. A few practical triggers:

You adopt or drop a major dependency, like a database, a queue, or a framework. You change how parts of the system communicate. You make a choice that several teams will have to build around. You pick one option when smart people argued for another, because that is exactly the decision someone will question later. And you choose something that constrains future work, where knowing the original reasoning will matter when the constraint starts to chafe.

You do not write an ADR for routine, reversible choices. Naming a variable, picking a minor library you can swap in an afternoon, or a one-off script does not need a record. The test is simple: will someone six months from now be confused or annoyed that this choice exists with no explanation? If yes, write the ADR.

The best time to write one is right when the decision is made, while the context is fresh and the tradeoffs are still vivid. Reconstructing reasoning weeks later produces a thinner, less honest record.

Why do ADRs work better when they are queryable?

Here is where the common practice falls short. Most teams store ADRs as static Markdown files in a repo folder, committed alongside the code. That is a real improvement over nothing, but it has a quiet weakness. A folder of files is something you read, not something you can ask.

Six months on, when someone needs to know "why did we choose Postgres over the option the team preferred?", a folder of forty ADRs means scrolling, searching filenames, and hoping the right one is titled clearly. The reasoning exists, but getting to it is friction, and friction is why people skip the record and ask a person instead, which defeats the purpose.

A queryable ADR is different. You ask the record a plain question and get back the specific decision that answers you, with the name of the person who stood behind it. Static files give you a document. A queryable record gives you an answer with an owner attached.

This is the model StandIn is built around. ADRs and other decisions become discoverable and pointable, so you can ask who decided something and why, and read the exact entry that person owned. Each person gets a Representative, called your StandIn, that answers only from records they explicitly stood behind. It does not invent a rationale or guess at intent. When no ADR exists for a question, it says so plainly and points you to the right person, which is honest in a way a confident guess never is. A clear "no decision was recorded" tells you the choice was never settled, and that is something you need to know.

The shift from static files to a queryable record is the same shift covered in our piece on how to query a decision log instead of just storing it. And if you want a starting structure, our decision log template for engineering teams lays out the fields that keep records useful.

Frequently Asked Questions

What is an architecture decision record?

An architecture decision record (ADR) is a short document that captures one significant technical decision, the context that forced it, the choice itself, and the consequences the team accepted, written so future engineers understand the reasoning.

What should an ADR contain?

A typical ADR has a title, a status, the context behind the decision, the decision itself stated plainly, and the consequences, including the tradeoffs and downsides the team chose to accept.

When should a team write an ADR?

Write one when a decision is significant and hard to reverse, such as adopting a database, changing how services communicate, or picking one option over an alternative that smart people argued for. Skip it for small reversible choices.

Why should ADRs be queryable instead of static files?

Static files have to be read and searched, which creates friction when you need one specific decision later. A queryable record lets you ask a plain question and get the exact decision back, with the name of the person who stood behind it.

What is the difference between an ADR and code comments?

Code comments explain how a piece of code works. An ADR explains why the team made a larger structural choice, including what was rejected and why, which is reasoning that rarely fits in a comment.