Make the reasoning durable
Write an architecture decision record that a future teammate can understand and challenge.
BY THE END, YOU CAN
- Separate context, decision, and consequences
- Compare alternatives against explicit drivers
- Define evidence that would trigger reconsideration
Diagram description: Context → Option A; Context → Option B; Context → Option C; Option A → Decision; Decision → Consequences
Preserve why, not just what
An architecture decision record is a small document explaining a consequential choice.
Start with the situation and constraints, name the decision, and describe its consequences. “Use SQLite” alone loses the reason. “Use one durable local store for a single-host prototype to simplify transactions; accept that multi-host worker access will require revisiting the storage design” is more useful.
A decision can be sensible within its context without being permanent. Keep the record close to the code so changes are reviewed together.
Make alternatives credible
Compare two or three realistic options against the same drivers.
For Relay’s first service, a database-backed queue may offer atomic submission with fewer moving parts. A separate broker may offer useful delivery features but adds operations and a consistency boundary. Do not give the rejected option absurd disadvantages to make the conclusion look inevitable.
State the unknowns and what evidence you have. A short prototype or failure test is often more valuable than a matrix filled with unsupported numerical scores.
Revisit without erasing the history
Give records a status such as proposed, accepted, or superseded.
When a constraint changes, add a new record and link the old one rather than rewriting history to make the current decision look inevitable. Set a reconsideration trigger, such as demonstrated contention, multiple independent teams, or a requirement the current boundary cannot meet. The trigger should prompt analysis, not an automatic migration.
Include both beneficial and adverse consequences so future maintainers understand the obligations created by the choice.
COMMON FAILURE MODE
Writing a decision record after the fact that lists only benefits. It becomes marketing for the implementation instead of evidence for future decisions.
TRY IT YOURSELF
Write an ADR for Relay’s initial queue storage. Include one credible alternative, one downside of your choice, an uncertainty, and a trigger for review.
Make the call in the laboratory.
The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.
Open in the laboratory ↗CONNECT IT TO RELAY
Save ADR-001 in your project, with context, options, decision, consequences, status, and review trigger. Ask someone to challenge one assumption.