What an ADR is
An architecture decision record, or ADR, is a short document about a single decision that shapes a system: which database, which queue, how services talk, how errors are handled. It records the decision, the context it was made in and the consequences. It is kept, not edited away, so the history stays honest.
Why teams write them
- People leave and memory fades. A year later nobody remembers why the system works as it does.
- New engineers can read the reasoning instead of guessing at it.
- A decision that is written down can be revisited properly when the conditions change, instead of by argument.
The format
Keep it to a page. The sections that earn their place:
- Title: a short, specific name for the decision.
- Status: proposed, accepted or superseded.
- Context: the forces at play, including constraints and deadlines, and what you did not know.
- Decision: what you are doing, stated in the present tense.
- Consequences: what gets easier, what gets harder and what you now have to live with.
- Revisit when: the condition that would make you reopen it.
When to write one
Write an ADR when a decision is hard to reverse, affects more than one team or will surprise a future reader. Do not write one for every choice: a record for each variable name buries the ones that matter.
How to keep them useful
- Number them in order and never delete one. If a decision changes, write a new record and mark the old one superseded.
- Keep them next to the design docs and the code they describe.
- Write them while the decision is fresh, not months later from memory.
- Link them from the technical design that led to them.
The statuses a record can have
| Status | Meaning |
|---|---|
| Proposed | Written and open for comment. Not yet in effect. |
| Accepted | Agreed, and the team is acting on it. |
| Superseded | Replaced by a later record, which it links to. |
| Deprecated | No longer followed, and nothing has replaced it. |
Proposed
Meaning
Written and open for comment. Not yet in effect.
Accepted
Meaning
Agreed, and the team is acting on it.
Superseded
Meaning
Replaced by a later record, which it links to.
Deprecated
Meaning
No longer followed, and nothing has replaced it.
When a decision changes
Decisions change when the world does: the team grows, the cost of a service rises, a better option appears. Do not edit the old record to say something new, because then nobody can tell what the team believed at the time. Write a new record, say what changed, set the old one to superseded and link the two. Anyone reading either can follow the trail.
Alternatives to a formal record
- A decision log at the top of the design doc, a table with the date, the decision and the reason, is enough for small teams.
- A short note in the task works for decisions that affect only that task.
- A dated decision in the meeting notes is better than none, if the notes are easy to find.
The format matters less than the habit: write down what was decided and why, in one place people can find, close to the work.
Decision records in Kanso
The decision record template has the decision, status, context, consequences and revisit condition ready to fill in. Keep each record as a sub-page of the project it affects, so the reasoning sits beside the work. See Kanso Docs.
