Every codebase carries the fingerprints of decisions made under pressure. Most of those decisions are never written down. A year later, someone asks “why did we build it that way?” and no one in the room was there when it happened.
Architecture Decision Records (ADRs) solve this. But most teams write them badly — either as sprawling design docs that no one reads, or as terse commit messages that capture the what without the why.
The format that works
An ADR needs exactly four things:
Title — A short phrase in past tense. “Use Postgres for event sourcing” not “Database evaluation.”
Context — Two or three sentences on the situation. What problem were we solving? What constraints mattered?
Decision — What we chose to do. One sentence.
Consequences — What becomes easier because of this? What becomes harder? Be honest about the downsides.
That’s it. Not a design doc. Not a justification essay. A record.
Why four sections is enough
Long documents don’t get read. An ADR that takes more than five minutes to write probably won’t get written at all. And an ADR that takes more than two minutes to read will only be read by the person who wrote it.
The value of an ADR isn’t in the depth of the analysis — it’s in the existence of the record. Future you needs to know that a decision was made and why it went a particular direction. The details of the evaluation are secondary.
Where to put them
In the repo. Next to the code. docs/adr/ or docs/decisions/. Numbered sequentially. If they live in Confluence or Notion, they’ll drift. If they live in the repo, they survive reorgs, tool migrations, and the departure of whoever championed them.
When to write one
Any time the answer to “why is it like this?” would otherwise depend on someone’s memory. A good heuristic: if the decision came out of a meeting that involved more than two people, write an ADR.
This is a small practice. But over time, a folder of ADRs becomes the closest thing your team has to an institutional memory.