Architecture Decision Record

Theo was changing Pagedeck's billing screen when he asked why the pricing data was stored the way it was. Nobody could answer. The person who chose that structure had left the company, and the code recorded only what had been done.

Code shows the outcome of a decision and nothing else. Which alternatives were on the table, which one was dropped and why, what constraints were in force that week — none of it survives. Faced with a structure whose reasoning is missing, a team goes one of two ways. Either nobody touches it and new code gets piled on top, or somebody assumes there was no good reason, rips it out, and falls straight into the trap the original choice was avoiding. The second way costs more. Pagedeck learned that firsthand: the storage layout got rewritten because it looked slow, and two months later enterprise invoices stopped reconciling, which is when the team discovered the old layout existed to make those invoices add up.

It wasn't that decisions never got made. The problem was that the only artifact left behind was meeting notes. Notes run in the order people spoke, so the conclusion has to be hunted for, and anyone who wasn't in the room reads it without the surrounding context. So teams moved to a different unit — one decision per document instead of one document per meeting — in a format short enough that nobody puts off writing it, stored right next to the code.

One record has four fields: what the situation was, what was decided, what follows from it, and whether the decision is still live.

1. Context — the circumstances that forced the decision. Write down what the problem was and which constraints applied. Someone revisiting the call six months later needs this field more than the conclusion.
2. Decision — what was chosen, in a sentence or two, plus the alternatives considered and the reason each was dropped. Leave out the rejected options and somebody will bring one back a year later as a fresh idea.
3. Consequences — what gets better and what gets worse. A record listing only upsides is a pitch, not a record. If search gets faster at the cost of double the storage, the doubled storage goes in the same field.
4. Status — whether this decision still holds. Proposed, accepted, superseded is usually enough. Superseded records are kept rather than deleted, because knowing what got reversed and when is often as useful to the next person as the decision itself.

A title, a date, and a number go on top. Numbers run in sequence so other records can point at this one. Record 007 at Pagedeck, written when real-time co-editing was added, looked like this. Context: two people editing the same document meant the later save overwrote the earlier edit. Decision: merge conflicting edits automatically, with a note on why document locking was rejected. Consequences: higher server cost and harder offline support. The whole thing fit on one screen.

The person who made the decision writes the record. The reasoning behind a rejected option lives only in the head of whoever rejected it, so a bystander writing it up preserves the conclusion and loses the judgment. At Pagedeck the last 15 minutes of the meeting where a decision lands go to writing it down. Put it off and it never gets written, and after a week the constraints that mattered have already gone fuzzy.

Three groups read it: whoever modifies that code half a year out, whoever joins and is learning the structure, and the author who no longer remembers their own reasoning. All three open the document to judge one thing — whether the decision can be reversed now. That narrows what the record has to answer.

Where it lives is part of the format. It goes in the same repository as the code, as a text file, rather than in a documentation tool, so that someone reading code can find the reasoning next to it. Sharing a location means sharing a review path too: a new record ships alongside the code and goes through code review, and when a colleague says the context field is too thin, it gets filled in right there.

"Why is this built this way? Is there a record for it?"

The code alone isn't enough to make a call, so find the circumstances at the time.

"The decision's made, so I'll write the record and close this out."

Stop the discussion and capture only the conclusion and the rejected options.

"That record is marked superseded. Read 012 instead."

An earlier decision has already been reversed, so go read the one that currently holds.

The day Theo proposed moving search onto a different storage engine, Mia dug up a record from two years earlier. The same proposal had come up then and had been dropped because of an enterprise customer's data retention requirement, which was written into the context field. Theo checked with Sofia on whether that requirement still applied, heard that the contract had changed and it no longer did, and brought the proposal back.

The record didn't block the decision. It moved the starting point. Without it, the conversation that day would have begun at whether the new engine is any good; with it, the conversation began at whether a condition from two years ago still binds.

The most common mistake is treating a record as a condensed design document. Both describe system structure, so the confusion is natural. But the unit differs. A design document describes what the whole system looks like right now and gets updated whenever the structure changes. A record holds one decision and the situation around it, and once written it stays put. Blur the two and records grow to the length of design documents, and a long format quietly stops being written within six months.

The other frequent one is assuming a reversed decision means editing the old record. Leaving stale text around feels wrong, which is where the instinct comes from. The practice is to flip the status to superseded and write a new record instead, with the old number cited in the new record's context field so the reversal reads as a chain. Overwrite it and that history disappears, and a year later somebody proposes the first rejected option as though it were new. The chain also carries information the individual records don't: three superseded records on the same subject in eighteen months says the team keeps circling a problem it hasn't actually solved, and that pattern is only visible if the old entries are still there to count.