Architecture Decision Records

Thinking Tools6.4 Conducting Follow-Up and Taking FeedbackAlso known as ADRs, Decision records

Originated by Michael Nygard (Documenting Architecture Decisions, 2011).

Records each significant decision in a short numbered note giving its context, the choice made, and its consequences, stored beside the work it governs.

Nine notes from one database decision, sorted into a one-page record

The team is writing record 14: move the reporting database to a managed service. Each tag is a note someone wants in it. Select one, then the box where it belongs: context, decision, or consequences, or the bottom row if it does not belong in the record at all. The first is placed as an example. Illustrative.

Items (select one, then a box)
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record
  • Not placedPlacedContextDecisionConsequencesNot in the record

In the record

Write it inLeave it out
Context
Decision
Consequences
Not in the record
ContextDecisionConsequences

Section of the record

Reports time out. Month-end reports time out above two million rows, three nights in five.Not placed yet.Reports time out. Month-end reports time out above two million rows, three nights in five.Context: The situation and the forces that made a decision necessary, with numbers where they exist.A force behind the decision, measured: a later reader can check whether it is still true.Reports time out. Month-end reports time out above two million rows, three nights in five.Decision: What was decided, in one active sentence: we will.Reports time out. Month-end reports time out above two million rows, three nights in five.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Reports time out. Month-end reports time out above two million rows, three nights in five.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.No database admin. Nobody on the team can administer the database server; failures fall to whoever is free.Not placed yet.No database admin. Nobody on the team can administer the database server; failures fall to whoever is free.Context: The situation and the forces that made a decision necessary, with numbers where they exist.A constraint that made the managed service attractive. If the team hires one, the reasoning changes.No database admin. Nobody on the team can administer the database server; failures fall to whoever is free.Decision: What was decided, in one active sentence: we will.No database admin. Nobody on the team can administer the database server; failures fall to whoever is free.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.No database admin. Nobody on the team can administer the database server; failures fall to whoever is free.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Move to managed service. We will move the reporting database to the cloud provider's managed service.Not placed yet.Move to managed service. We will move the reporting database to the cloud provider's managed service.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Move to managed service. We will move the reporting database to the cloud provider's managed service.Decision: What was decided, in one active sentence: we will.The decision itself, in one sentence and the active voice.Move to managed service. We will move the reporting database to the cloud provider's managed service.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Move to managed service. We will move the reporting database to the cloud provider's managed service.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Reports read a replica. Reports will read from a replica, never from the primary database.Not placed yet.Reports read a replica. Reports will read from a replica, never from the primary database.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Reports read a replica. Reports will read from a replica, never from the primary database.Decision: What was decided, in one active sentence: we will.Part of the same decision: it says how the move solves the timeouts.Reports read a replica. Reports will read from a replica, never from the primary database.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Reports read a replica. Reports will read from a replica, never from the primary database.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Hosting up $1,400/month. The managed service costs about $1,400 a month more than the current server.Not placed yet.Hosting up $1,400/month. The managed service costs about $1,400 a month more than the current server.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Hosting up $1,400/month. The managed service costs about $1,400 a month more than the current server.Decision: What was decided, in one active sentence: we will.Hosting up $1,400/month. The managed service costs about $1,400 a month more than the current server.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.A cost, stated at the time. This is the line the new director needed eighteen months later.Hosting up $1,400/month. The managed service costs about $1,400 a month more than the current server.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Rewrite 11 procedures. Eleven custom stored procedures will not run on the managed service.Not placed yet.Rewrite 11 procedures. Eleven custom stored procedures will not run on the managed service.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Rewrite 11 procedures. Eleven custom stored procedures will not run on the managed service.Decision: What was decided, in one active sentence: we will.Rewrite 11 procedures. Eleven custom stored procedures will not run on the managed service.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Work that must follow from the decision, and a cost a later team would otherwise discover by surprise.Rewrite 11 procedures. Eleven custom stored procedures will not run on the managed service.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Self-serve restores. The team can restore a backup itself in minutes, without waiting for anyone.Not placed yet.Self-serve restores. The team can restore a backup itself in minutes, without waiting for anyone.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Self-serve restores. The team can restore a backup itself in minutes, without waiting for anyone.Decision: What was decided, in one active sentence: we will.Self-serve restores. The team can restore a backup itself in minutes, without waiting for anyone.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.A gain the decision enables, listed beside the costs.Self-serve restores. The team can restore a backup itself in minutes, without waiting for anyone.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Copy command flags. The exact command and flags for the overnight data copy.Not placed yet.Copy command flags. The exact command and flags for the overnight data copy.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Copy command flags. The exact command and flags for the overnight data copy.Decision: What was decided, in one active sentence: we will.Copy command flags. The exact command and flags for the overnight data copy.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Copy command flags. The exact command and flags for the overnight data copy.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.Implementation detail: it belongs in the migration runbook, and it will be out of date within a week.Who argued for what. A summary of the meeting, with each person's position by name.Not placed yet.Who argued for what. A summary of the meeting, with each person's position by name.Context: The situation and the forces that made a decision necessary, with numbers where they exist.Who argued for what. A summary of the meeting, with each person's position by name.Decision: What was decided, in one active sentence: we will.Who argued for what. A summary of the meeting, with each person's position by name.Consequences: What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.Who argued for what. A summary of the meeting, with each person's position by name.Not in the record: True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.The record keeps the reasons; who said what adds heat and no reasoning a later reader can use.

Your sort matched 0 of 9.Your sort matched 1 of 9.Your sort matched 2 of 9.Your sort matched 3 of 9.Your sort matched 4 of 9.Your sort matched 5 of 9.Your sort matched 6 of 9.Your sort matched 7 of 9.Your sort matched 8 of 9.Your sort matched 9 of 9.

Context
The situation and the forces that made a decision necessary, with numbers where they exist.
Decision
What was decided, in one active sentence: we will.
Consequences
What the decision enables, what it costs, and what must follow. Costs belong here as plainly as gains.
Not in the record
True and maybe useful, but it belongs elsewhere: in a runbook, a ticket, or nowhere.

The sort

  • Reports time out: Context. A force behind the decision, measured: a later reader can check whether it is still true.
  • No database admin: Context. A constraint that made the managed service attractive. If the team hires one, the reasoning changes.
  • Move to managed service: Decision. The decision itself, in one sentence and the active voice.
  • Reports read a replica: Decision. Part of the same decision: it says how the move solves the timeouts.
  • Hosting up $1,400/month: Consequences. A cost, stated at the time. This is the line the new director needed eighteen months later.
  • Rewrite 11 procedures: Consequences. Work that must follow from the decision, and a cost a later team would otherwise discover by surprise.
  • Self-serve restores: Consequences. A gain the decision enables, listed beside the costs.
  • Copy command flags: Not in the record. Implementation detail: it belongs in the migration runbook, and it will be out of date within a week.
  • Who argued for what: Not in the record. The record keeps the reasons; who said what adds heat and no reasoning a later reader can use.

An example

Eighteen months after a payments company moved its reporting database to a managed cloud service, a new engineering director asked why the team was paying $1,400 a month more for it and maintaining eleven rewritten stored procedures. Two of the three engineers who made the call had left. The answer was in the repository, in a one-page file numbered 14.

Its context section said that month-end reports had been timing out above two million rows three nights in five, and that nobody on the team could administer the database server, so failures fell to whoever was free. The decision was one sentence: we will move the reporting database to the managed service, and reports will read from a replica. The consequences listed the costs as plainly as the gains: the hosting increase, the procedures that would need rewriting, and restores the team could run itself.

The director read it in five minutes and left the decision alone. A year later, when a cheaper option appeared, the team wrote record 31, marked it as replacing 14, and linked the two.

Why it works

Decisions outlive the memory of why they were made. People leave, the constraints that forced a choice fade, and a later team sees only the cost of the choice, so it either relitigates a settled question or keeps a choice whose reasons no longer hold. A short record written at the time keeps the forces in view: what was true, what was decided, and what the decision was expected to cost.

The format's restraint is what makes it work. A record of one page per decision is cheap enough to write every time and short enough to read when it matters. Writing the consequences, costs included, at the moment of choice makes the trade-off explicit while it can still be questioned. Numbering the records and marking the ones that replace earlier ones keeps the history intact instead of overwritten.

The thinking behind it

Michael Nygard Michael Nygard, a software architect and author, proposed the architecture decision record in a 2011 blog post, Documenting Architecture Decisions. Each significant design choice gets a short numbered document giving its context, the decision, its status, and its consequences. The records are kept with the project they govern, so anyone who later wonders why the system is built a certain way can find the reasoning written down at the time the choice was made, by the people who made it.

How to run it

  1. Decide what counts as significant. Write a record for any choice that is costly to reverse or that someone will question later.
  2. Open a new numbered file. Give it the next number and a short title that names the decision.
  3. Write the context. State the problem, the constraints, and the forces at play, with numbers where they exist.
  4. State the decision in one sentence. Use the active voice: we will move the reporting database to the managed service.
  5. List the consequences, costs included. Say what the decision enables, what it costs, and what must follow from it.
  6. Mark the status. Proposed, accepted, or replaced, with the date.
  7. Replace instead of editing. When a later decision overturns this one, write a new record and link the two.

Where it goes wrong

Records are written after the fact, from memory, to satisfy a process. The context reads like a justification and leaves out the options that lost. Write the record while the decision is being made, and have someone who argued against it read the context.

The consequences list only benefits. A record that names no cost cannot tell a later team what was traded away, so it cannot help them judge whether the trade still holds. Require at least one cost in every record.

The records turn into design documents, ten pages each, and nobody writes or reads them. Keep each to a page; detail belongs in the code, the runbook, or a linked document.

When to use something else

  • IBIS. When the debate itself needs mapping, with each question, option, and argument recorded as the discussion unfolds.
  • One-Way and Two-Way Doors. When the first question is how much care a decision deserves, judged by how hard it is to reverse.
  • After-Action Review. When the decision has already played out and the team needs to compare what happened with what was expected.

Where it sits in SOLVE eX

Go to the source

Back to the catalog