top of page

Architecture Decision Checklist

S. West
1 hour ago
5 min read

The team spent nine months splitting the monolith into services. Afterwards, every feature still needed four of them deployed together.

The decision had made sense on the whiteboard. Big tech ran microservices, the team expected to grow, and independent deploys sounded like speed. Nobody yet knew where the real domain boundaries were, so the services were cut along guessed lines, and the guesses were wrong. The team ended up with a distributed monolith: all the complexity of a distributed system and none of the independence.

(Composite example, assembled from patterns common in scaling teams that adopt big-tech architecture early. The figures are illustrative.)

Most architecture decisions teams regret share one root cause: they solve a problem the team doesn't have yet, engineering in service of imagination instead of evidence. Good architecture decisions are usually boring, the case Dan McKinley makes in "Choose Boring Technology". They use proven technology, solve today's problem, stay simple enough for a new hire to understand quickly, and leave room to change without a rewrite. This checklist starts from today's evidence, not tomorrow's forecast. Print one per decision and fill it in before the commit, with the person proposing the change in the room. If a section stalls, or the answers lean on the future tense, the answer is almost always "not yet".

Step 1: write down the decision

The decision on the table: ______

Proposed by: ______ Date: ______

Step 2: name the problem you're solving right now

Not next quarter. Not at scale. Right now.

  • ☐ I can name the specific problem in one sentence, with no "eventually" or "might".

  • ☐ The problem is causing real pain today (name it): ______

  • ☐ Someone can point to evidence it exists today, such as a metric, an incident or a blocked feature, not a forecast.

Stop condition: if the sentence starts with "eventually we might need to…", stop here. You are not solving a problem; you are decorating one.

Step 3: score the cost of being wrong

The cost of being wrong should set how rigorous the analysis is. These are our rough bands, not a formula. Check the row that fits:

  • ☐ Reversible in about a week: make the simpler choice and move on. Don't over-analyse a cheap mistake.

  • ☐ Somewhere in between: time-box a spike. Instrument first so you see the real signal before committing.

  • ☐ Reversing takes about six months: invest in understanding before you commit. This decision earns real rigour.

Fill in the estimate:

  • Undoing this decision would take roughly: ______

  • What it locks us out of (database-specific features, provider services, independent deploys, query simplicity): ______

  • Could we build a clean interface to the concrete thing we use now, instead of a full abstraction? ☐ Yes ☐ No

Rule of thumb: the wrong abstraction is worse than no abstraction. Sandi Metz put it as "duplication is far cheaper than the wrong abstraction". If you might swap later, don't build the abstraction now; build a clean interface to what you actually use.

Step 4: check whether you're copying someone else's solution

You are not a hyperscaler. Their architecture solves their problems at their scale, not yours. Answer honestly:

  • ☐ Part of my reasoning is "a big-tech company does it this way".

  • ☐ I'm choosing this before I understand our own domain boundaries or actual load.

  • ☐ If I remove the big-tech example, I can still justify this from our own evidence: ______

If you checked the first two but can't fill in the third, the pattern is borrowed, not earned.

Step 5: run the regret radar

Check any that resemble the decision on the table, then read the "not yet" beside it.

  • ☐ Microservices before you know the domain boundaries: you get a distributed monolith. Start with a monolith and decompose when you feel the pain that decomposition solves (Martin Fowler's "Monolith First").

  • ☐ Premature optimisation: for example, Kafka for forty events per minute, or multi-region active-active for users in one time zone. Build for the load you have, monitor it, and scale when the metrics say so.

  • ☐ The abstraction that abstracts too much: a custom ORM or a provider-agnostic cloud layer, built so you can "swap later". Teams rarely switch, and they pay the tax on every feature. Build a clean interface instead.

  • ☐ A custom solution for a solved problem: auth, scheduling, search, email, PDF generation, rate limiting. (Illustration: one team's custom auth had two security incidents in three months before they moved to a managed identity provider.) Use the existing solution until you can say, with specifics, why it can't work.

  • ☐ A schema designed for "flexibility": entity-attribute-value tables, or storing everything as JSON, which trades validation, indexes and integrity for flexibility you rarely need. If you don't know what data you'll need, work out the data model first.

Step 6: record the verdict

  • ☐ Commit: the decision passes all three questions on today's evidence.

  • ☐ Not yet: the problem doesn't exist yet, the pattern is borrowed, or the cost of being wrong isn't understood. Instrument, and revisit when the data changes.

Record the outcome as an architecture decision record, in Michael Nygard's format, so the next team can see why.

How to use it

  • Who: the engineer proposing the change, with a staff engineer or engineering manager who will challenge it. One sitting, before the decision is committed.

  • Output: one completed sheet per decision: the problem stated in a sentence, a reversibility band, any regret patterns checked, and a commit or not-yet verdict.

  • Done when: the verdict is ticked, the evidence for it is written on the page, and the decision is recorded where the team will find it later.

Where this changes

A small team making a decision it can reverse in a week needs only Step 2 and the verdict; the rest is overhead for a cheap mistake. Regulated systems, or decisions that lock in a vendor or a data model for years, need more: a full architecture decision record with the options considered, a named approver and a review date. Large organisations should run the checklist in an architecture review, not alone at a desk.

The reasoning behind this checklist is in architecture decisions you'll regret. For the broader habit of deciding from evidence, read how to make technical decisions.

Final takeaway

Build for what you know, instrument so you learn, and change when the data tells you to. Most regretted architecture began as a confident answer to a question nobody had asked yet; this checklist makes you write the question down first.

Sources

bottom of page