Every Phoned-Tech project, regardless of scope, ships with at least one Architecture Decision Record. ADRs are short documents that record a decision, the alternatives considered, and the reasoning. We’ve been writing them for nine years. They are the single most boring practice we have, and they save more time than any other process.
The template
We use a four-section format that fits on a printed page:
- Context: what’s the situation, what constraints exist
- Decision: what we’re going to do, in one sentence
- Alternatives: what else we considered, why we rejected each
- Consequences: what becomes harder, what becomes easier, what we’ll need to revisit
That’s it. No template ceremonies, no required diagrams, no approval workflows. The author commits the ADR to the repo. The team reviews it like any other PR.
When to write one
Three triggers, any of which is sufficient.
First, when the decision affects more than one system or more than one team. Choosing a database for a single service is a code review. Choosing a database that three services will use is an ADR.
Second, when the decision is hard to reverse. Adopting a vendor, picking an authentication scheme, deciding on a multi-tenant model — these all change the cost of every future project. Future engineers will want to know why.
Third, when the decision was contested. If two senior people argued for an hour, write the outcome down so you don’t argue again in six months when one of them has left.
What it isn’t
ADRs are not design documents. A design doc explains how you’ll build something. An ADR explains why you’ll build it that way and not another way. Different audience, different shelf life.
ADRs are not living documents. We don’t update them when the decision changes — we write a new one that supersedes the old one, and link the two. The git log of the docs/adr/ directory is the project’s reasoning history.
What it actually saves you
The value isn’t apparent in week one. It’s apparent in month nine, when a new engineer asks “why did we pick Postgres instead of DynamoDB,” and the answer is in a four-paragraph file that took ten minutes to write. Multiply that by every onboarding for the lifetime of the system.
For our consulting work, ADRs are how we leave a codebase that the client’s team can actually own. We don’t disappear after handover. The ADRs do.