Architecture decisions that age well

The most expensive sentence in engineering is "I don't know why it's like that, but I assume there was a reason."

It shows up about eighteen months after the decision, usually from someone who wasn't there, standing in front of something that looks wrong.

And they have two bad options.

Assume there was a good reason and work around it, which preserves a constraint that may well have expired years ago. Or assume there wasn't and change it, which occasionally reintroduces the exact problem the original decision was avoiding.

Both are guesses, and the information that would settle it was free at the time and is now unrecoverable.

The bar that decides how much effort a decision deserves

Not seniority. Not cost. Reversibility.

For a decision you can undo in a week, the correct process is one person with context deciding, quickly, and moving on.

The cost of deliberating exceeds the cost of being wrong.

Most technical decisions sit in that category. Most organisations treat them as though they don't.

For a decision you can't undo without a quarter of work (your primary datastore, your tenancy model, your public API surface, the language your core system is written in), the process changes completely.

Now you want alternatives written down, someone arguing the other side, and a document that survives the meeting.

The question I'd ask out loud in any architecture discussion, early on: if this turns out to be wrong in a year, what does it cost us to change.

The answer sets the process. And it converts a debate about the decision into a much shorter conversation about how much care the decision deserves.

The trap is treating everything as irreversible because that feels safer.

An org where every decision gets the full treatment is an org where decisions take three weeks and the good people leave.

Decide at the last responsible moment

The last responsible moment is the point where deferring further starts costing you options rather than buying them.

Before that point, delay is genuinely valuable, because information keeps arriving.

You'll know more about your access patterns after three months of production traffic than any amount of design discussion can tell you today.

The word doing the work is "responsible."

Deferring past that point isn't open-mindedness. It's a decision made by default, usually by whoever writes the first implementation.

Every deferred decision is being made anyway, in code, by someone who didn't know they were making it.

So name the decisions you're deliberately deferring, write down what information would let you make them, and put a date on when you'll look again.

A deferral with a trigger is a strategy. A deferral without one is procrastination with better vocabulary.

ADRs people will actually write

An architecture decision record is one page. The format matters far less than the fact that it exists at all.

What I'd insist on is four sections.

The context: what was true at the time, including the constraints that were about to change and the ones that felt permanent.

And inside the context, the field nobody writes and everybody later needs: what pressure you were under. Business pressure, cash-flow pressure, or the plainest and most avoided one, that nobody available had the skills to do it the other way. Decisions get recorded as facts stated without any of that, which is what makes them unreadable eighteen months on, because a reader can't distinguish a bad decision from a constrained one. "We built this rather than buying it" explains nothing. "We built this rather than buying it because we couldn't fund the licence that year" explains everything, including whether the reasoning still holds now that you can.

This is the part that cannot be reconstructed afterwards, and it's worth being clear about why.

Reconstruction runs on human memory, and human memory isn't up to it.

People forget the pressure long before they forget the decision. They're also attached to architecture patterns in ways that quietly rewrite what they remember having believed at the time. By the time anyone thinks to ask, the honest answer has usually been replaced by a tidier one.

The decision, in a sentence.

The alternatives, and why each was rejected.

This is the section people skip. It's also the one carrying all the value, because in eighteen months the useful question isn't what you chose, it's whether the option somebody is now proposing was already considered and rejected for a reason that still holds.

And the revisit conditions. What would have to become true for this to be the wrong call. "If we exceed roughly ten thousand writes a second, this design stops working." "If we ever need multi-region, this is the piece that has to change first."

That section turns a historical record into an early warning system. It's the difference between a document worth reading and a document worth having.

Two rules keep the practice alive.

They live in the repo, next to the code, in version control, because a wiki is where documents go to become inaccurate.

And you write them for irreversible decisions only. Five to ten a year, at most. An organisation that mandates an ADR per decision produces forty documents nobody reads, which is worse than none, because it teaches everyone that the format is bureaucracy.

The written doc for the big ones

For genuinely major, one-way-door decisions, I want more than an ADR.

I want a real document written before the decision, circulated, and read in silence before anybody talks. Amazon-memo style.

That's the one place I'm maximally formal, and the reason is specific to how these fail.

A one-way-door decision made in a meeting gets made by whoever argues best in real time, and the objection that would have mattered arrives three days later from somebody who needed time to think.

Writing inverts that. It forces the proposer to confront the weak parts while drafting, because you can't hand-wave in a paragraph the way you can in speech, and it gives the careful thinkers a chance to be heard at all.

Six pages, prose, no slides. Read in the room for the first twenty minutes. Then discuss.

Slower, and it should be. These are the decisions where the cost of being wrong is measured in quarters.

The decision log as onboarding

The underrated benefit: a chronological list of your ADRs is the best onboarding document an engineering organisation can have, and it costs nothing extra.

A new senior engineer reading fifteen decisions in order gets the outline of the system, the constraints it was built under, and the reasoning style of the people around them, in an afternoon. That last part matters more than it sounds. Knowing how decisions get made here is what lets a new person start making them.

It also does something for the people who were there: it shows which constraints have expired. Read your own ADRs from three years ago and you'll find at least two decisions justified by conditions that no longer exist. Nobody would ever have discovered that by looking at the code, because the code just looks like the way things are.