Writing the Decision Record

Writing the Decision Record is the artifact that makes every decision in this book reversible by somebody who was not in the room. A design is not a diagram and not a running system; it is a set of choices, each of which was forced by a constraint that may no longer be true, and a record is how a future engineer finds out which ones have expired.

Key takeaways

• Nygard's 2011 form has five fields: Title, Status, Context, Decision and Consequences. Context describes the forces at play and is value-neutral, and Decision is written in active voice as we will.
• Consequences means all of them. Nygard's instruction is explicit that the record lists the unwelcome consequences and not just the positive ones.
• The constraint is the field people skip and the one that matters. It is the reason the alternative was not available, stated so somebody can check whether it still holds.
• A reversal signal has to be a threshold somebody could observe. The SRE Workbook's error budget policy is the worked example: a pre-agreed number that authorises a change of course.
• Mark a reversed decision superseded and keep it. IEEE/ISO/IEC 42010-2022 places architecture decisions and their rationale inside the architecture description itself.

Read this as the closing bracket on Chapter 1. That chapter said the load model comes before the diagram; this one says the constraint comes after the decision, and everything between them is the ordered set of choices those two brackets make arguable. The companion treatment of the reversibility argument makes the product-side case for the same discipline.

An engineer joins and inherits a service that uses a document store for data that looks relational. The obvious conclusion is that somebody made a mistake.

Six weeks of work later, the migration is half done and a former colleague mentions in passing that the store was chosen because a compliance requirement demanded per-record encryption keys and the relational option could not do it at the time.

The decision was correct. The reason was never written down, so the correctness was not inheritable.

A decision record is five fields and one page

The form is settled and there is no reason to invent another one.

Nygard's post, Documenting Architecture Decisions, published on 15 November 2011, gives five fields: Title, Status, Context, Decision, Consequences. Context describes the forces at play, including technological, political, social and project-local forces, and is written in a value-neutral voice. Decision is written in active voice, as we will. Consequences describes the resulting context after the decision, listing all consequences rather than only the positive ones.

The ADR community site, adr.github.io, states the scope compactly. A record captures a single architectural decision and its rationale. The practice extends beyond architecture to any significant decision.

One page is the right size. A record that takes an afternoon will not be written. A record longer than a page will not be read a year later by the person who most needs it.

Context is forces, not justification

The most common failure in a decision record is that Context becomes advocacy for the decision that follows.

Nygard's specification is that Context describes the forces at play, and the value-neutral instruction is doing real work there. Forces include the ones that argued against your choice. Political forces count: a partner integration that had to ship by a date, a team that owned the other system, a budget that had already been committed. Social forces count too.

Write it as though the reader might reasonably disagree with your conclusion. In a year they might. Their disagreement is more useful if they can see what you were up against.

Here is the test I apply. If somebody reading Context alone cannot construct at least one argument for a different decision, the section is advocacy rather than context.

The constraint is the field people skip

The single most valuable sentence in a decision record is not in Nygard's field list under that name, and it belongs in Context.

The constraint is the reason the alternative was unavailable. Not the reason your choice was attractive. It is the thing that would have to change before somebody could reasonably reverse you. That is what converts a record from a historical note into a live document.

Every chapter in this book ends in one. The load model's constraint is arithmetic: Little's 1961 result fixes concurrency once arrival rate and service time are known. Chapter 2's constraint is that a write cannot be both instantly durable across regions and low-latency. Chapter 9's constraint is a contractual availability expectation from three named customers.

Notice that all three are checkable. Somebody in eighteen months can ask whether the arrival rate assumption still holds. Or whether cross-region latency has changed. Or whether those customers still have those terms. A constraint that cannot be checked is a preference in formal clothing.

What each field is for, and how it fails

This table is the skeleton to copy. The third column is the one to read before writing, because each entry is a failure I have seen more than once.

The Consequences row carries the most weight and gets the least attention. A record that names the thing you accepted, in the sentence where you accepted it, is the difference between a known trade-off and a surprise.

A reversal signal is a number, not an intention

Every record should say what would make it wrong, and the sentence has to be observable rather than aspirational.

Revisit if this becomes a problem is not a reversal signal. Revisit when customers per cell exceed 700 is. The difference is that somebody can write a query for the second one, and a recurring review can check it without a judgement call.

The SRE Workbook's chapter on implementing SLOs supplies the worked example of this pattern operating in production. The error budget is 100 percent minus the SLO. It needs a written policy for what happens when it is spent, and four-week rolling windows are a good general-purpose interval. That is a pre-agreed threshold that authorises an action, decided before the pressure arrives.

Copy the structure into every record. One observable quantity, one threshold, one action. The action is usually revisit this record, which is enough.

Supersede, never delete

Records accumulate and some of them become wrong, and the instinct to tidy is the wrong instinct.

Nygard's instruction is that a reversed decision is marked superseded and kept rather than removed, with a pointer to the record that replaced it. The reason is narrow. The old record still explains why the system looked the way it did between two dates, which is exactly what somebody investigating an old data shape needs.

There is a second benefit that is less obvious. A chain of superseded records shows how the constraints changed over time, which is the closest thing a team has to institutional memory about its own design. A repository with thirty records, four of them superseded, tells a newcomer more than any architecture diagram.

Keep them in the repository beside the code, numbered sequentially, in the same review process as everything else. That is the whole storage decision.

Rationale belongs inside the architecture description

This practice has standing beyond a well-known blog post, which is worth knowing when somebody calls it a personal preference.

IEEE/ISO/IEC 42010-2022, Software, systems and enterprise, Architecture description, was approved on 21 September 2022 and published on 7 November 2022. It supersedes IEEE 42010-2011. It places architecture decisions and their rationale inside the architecture description, and it distinguishes the architecture of an entity from the description that expresses it.

That distinction is the point. Your architecture is the set of properties the running system has. Your architecture description is the artifact that expresses it, and an international standard says decisions and rationale belong in that artifact rather than in somebody's memory.

So if a reviewer asks whether decision records are worth the effort, the answer has a citation now. They are a named part of what an architecture description contains.

A worked record, composited and labelled

The details here are composited from ordinary production shapes rather than one system, and the shape is exact. This is the cell decision from Chapter 9, written as a record.

Title: 0027, Serve tenants from eight cells rather than one shared stack. Status: accepted, March 2026. Context: 4,000 customer organisations are served from a single stack, so any single fault reaches one hundred percent of them. Three named organisations have contractual availability expectations that a total outage would breach. Splitting further than eight cells was considered and rejected on cost. The constraint is that each cell carries its own baseline infrastructure and its own headroom, so fixed cost scales with cell count while variable cost does not.

Decision: we will run eight cells with a routing layer that holds a routing table and no business logic, and we will place the three largest organisations in cells of their own.

Consequences: no single fault affects more than fifteen percent of organisations. Fixed infrastructure cost multiplies by roughly eight, priced in the cost model as an accepted increase. Deployment becomes sequential with a soak period, so a release now takes most of a day, which the team accepted in exchange for staged blast radius. Reversal signal: revisit when customers per cell exceed 700, or when any new dependency appears on the request path that spans all cells. Either one restores the original blast radius.

The objection: nobody reads these

Sometimes true, and the observation is usually about records that were not worth reading.

A record nobody reads is normally missing the two fields this chapter argues for. With no constraint there is nothing to check, so reading it teaches you only what was chosen. You could see that from the code. With no reversal signal there is no reason to revisit it, so nobody ever does.

There is also a moment when records get read, and designing for that moment is the whole justification. Somebody proposes replacing a component. Somebody joins and finds a surprising choice. An incident traces back to a trade-off. In all three cases the reader is looking for exactly one thing: was this deliberate, and does the reason still hold.

The cost is genuinely small. One page, ten minutes, at the moment you already understand the decision better than you ever will again. Compare that against Chapter 12, which is what an undocumented decision costs when its reason expires and nobody notices.

Chapter summary

A decision record makes a design reversible by somebody who was not in the room, and Nygard's 15 November 2011 form supplies the five fields of Title, Status, Context, Decision and Consequences, with Context describing the forces at play in a value-neutral voice, Decision written in active voice as we will, and Consequences listing all consequences rather than only the positive ones. Context fails when it becomes advocacy, and the test is whether a reader could construct an argument for a different decision from it alone. The constraint is the field teams skip and the one that gives the record a working life, because it names the reason the alternative was unavailable and is therefore checkable later, as with Little's 1961 result fixing concurrency, or a contractual availability expectation from named customers. A reversal signal must be an observable quantity with a threshold and an action rather than an intention, and the SRE Workbook's error budget policy, being 100 percent minus the SLO over a four-week rolling window with a written policy for exhaustion, is the worked example of a pre-agreed threshold that authorises a course change. Reversed records are marked superseded and kept rather than deleted, because the old record explains why the system looked as it did between two dates and a chain of them is a team's institutional memory. The practice has formal standing: IEEE/ISO/IEC 42010-2022, published 7 November 2022, places architecture decisions and their rationale inside the architecture description itself.

That is the book. Its argument in one line: almost every scaling problem is a decision made early, cheaply and without evidence, so start from a load model rather than a diagram, decide where state lives and what durability it gets, choose a consistency guarantee you can state in one sentence, pick a data model from the questions you will actually ask, put the boundary where the transaction already stops, give every cache a written staleness contract, bound your queues and shed by criticality, derive timeouts and budget retries behind an idempotency key, choose your blast radius on purpose, decide what you will need to see while it is still cheap, put a formula behind the bill, and migrate through states that are each safe alone. The measure of whether it worked is not that nothing had to change. It is that when something did, the record said what constraint had expired, and the next engineer could tell the difference between a mistake and a decision that outlived its reason.