Architecture Decisions That Age Well
The lightweight habit that keeps a system understandable a year later: writing the decision down before you make it.
The expensive part of a system is rarely the code. It's the context that evaporates — why a boundary sits where it does, which option was rejected, what constraint forced the awkward shape. Six months on, no one remembers, so the team relitigates it or, worse, quietly works around it.
Write the decision down
An architecture decision record (ADR) is a tiny document you write before you commit. It costs ten minutes and saves the team from archaeology later.
# ADR-001: <short title>
Date: 2026-06-10
Status: Proposed | Accepted | Superseded by ADR-00X
## Context
What forces are at play? Constraints, requirements, the problem.
## Decision
What we are doing, in one or two sentences.
## Consequences
What gets easier. What gets harder. What we are explicitly accepting.
Why it works
- It separates the decision from the discussion, so the record stays short.
- "Consequences" forces honesty about the trade-off you're taking on.
- A superseded ADR is not deleted — it becomes the trail of how the system thinks.
How I use them in practice
The files live in /docs/decisions/ in the repository — same repo as the code,
versioned alongside it, discoverable with a normal file search. I write the ADR before
I open a pull request: if I can't articulate the context and consequences in the template,
I'm not ready to build yet. Review happens as part of the PR itself, which means the
decision and the implementation get discussed in the same thread, by the same people,
at the same moment.
The decision an ADR saved me from re-arguing: on a Supabase project, early in the build, I documented the choice to enforce access control at the database layer with Row-Level Security rather than at the application layer. Six weeks later, when a new surface was added and someone asked "can't we just check this in the API?", the ADR was the answer. Not my opinion — the written record of the trade-offs we'd already agreed to. The conversation took two minutes instead of two hours, and the boundary held.
The goal isn't process for its own sake. It's a system that can explain itself.