N100FN100F
Published on

Deciding in writing

An architecture decision record takes up one page and saves weeks. What it should contain, when to write it and how to stop it turning into bureaucracy.

Service line Cloud Architecture

The code says what; nobody says why

Anyone can read in the configuration that the database is relational, that the queue is managed or that the service runs in containers. What cannot be read is why: what problem it solved, what other options were looked at, what was sacrificed by choosing that one.

Without that why, every new person has two bad options: touch nothing out of fear, or change everything out of ignorance.

The decision record

An architecture decision record (ADR, a practice popularised by Michael Nygard) is a short document, one per decision, kept alongside the code and never deleted.

Anatomy of a decision recordAn illustrative decision record with context, options, decision, consequences and cost, annotated.ARCHITECTURE · DECISIONSAnatomy of a decision recordADR-014Managed queue for ordersStatus: accepted · 2026-03-04CONTEXTPeaks of 10× on Mondays; the ordersservice was saturating.OPTIONSA) Scale the database B) Managedqueue C) Do nothingDECISIONB: a managed queue between the web andthe orders service.CONSEQUENCES+ absorbs peaks − asynchronousprocessing, retriesESTIMATED COST≈ €40 / month at current volume1The most forgotten part2At least two options3One or two sentences4What is gained and lost5Almost nobody writes itIt is not edited: it is superseded byanother record that cites it.Illustrative exampleN100F · n100f.com

Its parts:

  • Title and status. What was decided and where it stands: proposed, accepted, superseded by another.
  • Context. What the problem was and what constraints existed at that moment. It is the part most often forgotten and the part that matters most.
  • Options considered. At least two, with their advantages and drawbacks. If there was only one option, it was not a decision.
  • Decision. What was chosen, in one or two sentences.
  • Consequences. What is gained, what is lost and what it forces you to do later.
  • Estimated cost. How much it costs to operate what was chosen. It is the part almost nobody writes and the one most appreciated afterwards.

When to write one

Not every choice deserves a record. The practical rule: you write one when the decision is expensive to reverse or somebody else is going to inherit it. Choosing the database engine, yes. Choosing the name of a variable, no.

How to avoid bureaucracy

  • One page at most. If it does not fit, it is two decisions.
  • It is written at the time, not afterwards. Ten minutes on the day of the decision.
  • It is not edited: it is superseded. If a decision changes, a new one is written citing the previous one. That way the full history remains.
  • It lives with the code, in the same repository, so it is reviewed and versioned the same way.

A set of decision records is the memory of the system. It is what allows somebody arriving a year from now to understand in an afternoon what took months to decide.

How we apply it: Cloud Architecture.

If your cloud cost keeps growing and nobody knows why, or your architecture depends on whoever built it, let’s talk.

Let’s talk