Checklist · Architecture

Architecture Decision Checklist

Work through a design decision before it becomes expensive — what is actually being decided, what it costs to reverse, how it fails, and what you are choosing not to do.

Download the checklist Read the full guide

Markdown. No sign-up, no email.

Decision: _______________ Date: _______ Decider: _______

Use this for decisions that are expensive to reverse. Most decisions are not, and applying this to them is its own kind of waste.

1. What is actually being decided#

[ ] The decision stated in one sentence
[ ] The problem it solves, in the language of the business
[ ] Why now — what changed, or what is about to
[ ] Who is affected, including teams not in the room
[ ] Is this reversible? If yes, decide quickly and move on

2. The requirement, in numbers#

[ ] Expected load, and expected growth — measured, not assumed
[ ] Latency requirement stated as a percentile
[ ] Availability requirement, and what an hour of downtime actually costs
[ ] Data volume now and in two years
[ ] Consistency requirement: must this be correct immediately, or eventually?

Most architecture arguments are two people assuming different numbers. Write them down and half of them end.

3. Options#

[ ] At least two real options, plus doing nothing
[ ] The simplest thing that could work is one of them
[ ] Each option's cost: build, run, and to operate at 3am
[ ] Each option's failure modes
[ ] What each rules out later

4. Reversibility#

[ ] How long to reverse this, honestly
[ ] What would have to change: code, data, contracts, other teams
[ ] Can it be trialled on a slice first?
[ ] If it is one-way, what evidence would change the decision? Gather it first

	Reverse in
Data model and its meaning	Months to years
Service boundaries	Months
Synchronous vs asynchronous between components	Weeks to months
A dependency that leaks into every module	Months
A library used behind one interface	Days

5. Failure#

[ ] What happens when each dependency is slow, not only down
[ ] Blast radius: what else fails when this does
[ ] Is failure contained, or does it propagate to callers?
[ ] What degraded operation looks like, and whether users can tell
[ ] Whether a fallback exists, and whether it has been tested

Silent degradation into stale or partial results is worse than an error, because it is acted on.

6. Data#

[ ] One system owns each piece of data — named
[ ] Where copies exist, how stale they may be, and who says so
[ ] What happens when two sources disagree
[ ] Retention and deletion, including from copies
[ ] Personal data identified, and its residency requirement

7. Operating it#

[ ] How you will know it is working — not that it is running
[ ] What alerts, and who they wake
[ ] How a problem is diagnosed at 3am by someone who did not build it
[ ] Runbook for the failures you can predict
[ ] Skills needed to run it, and whether the team has them

8. Cost#

[ ] Build cost
[ ] Running cost at expected load
[ ] Running cost at ten times expected load
[ ] Cost of the people needed to operate it
[ ] What is stopped or delayed to do this

9. What is being given up#

[ ] Options this closes
[ ] Complexity added, and who pays it
[ ] The team that inherits this in two years
[ ] Accepted risks, named

10. Record it#

[ ] Decision, context, options considered, consequences — written down
[ ] Why the alternatives were rejected — the most valuable part, and the most often omitted
[ ] Stored with the code, not in a document nobody will find
[ ] Dated, with the decider named
[ ] What would prompt revisiting it

In two years the question will be "why did they do it this way". A record that lists only the chosen option cannot answer it.

Sign-off#

	Name	Date
Proposed by
Reviewed by
Decided by

Back to Architecture