How to Make Better Architecture Decisions That Hold Up

You have sat in this meeting. Two options, four opinions, ninety minutes of debate, and the group agrees to take it offline. Three weeks later the same meeting happens again with the same slides and a slightly worse mood.

The usual advice is to write the decision down. That is the second half of the job. An architecture decision record is a receipt: it proves what you chose and what you knew. It does not make the choice better.

The first half is judgement, and it happens before anyone opens a template. You classify the decision, name one owner, frame real options, put a date on it, decide what would make you walk away, then commit. Get those moves right and the record almost writes itself.

I am not going to re-teach the record here. The template, section by section, is a different job, and I point you to that guide at the end. This post is about the thinking that should exist before the file does.

What makes an architecture decision different from any other?

An architecture decision is a choice you cannot cheaply undo. The cost of reversing it — migration work, broken contracts, moved data, other teams' plans — is what makes it architectural, not the number of boxes in the diagram.

Nygard's 2011 post set the boundary most teams still use: records are for decisions that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques. That is a good filter for documentation. It is a poor filter for effort, because it says nothing about how expensive being wrong will be.

The test I use is narrower.

Ask what it costs to be wrong. If being wrong costs a sprint of rework and one awkward email, you have a design choice. If being wrong means a data migration, a versioned API your customers depend on, or a re-platforming that your on-call rotation pays for, you have an architecture decision. Olaf Zimmermann's history of the practice puts the same point plainly: architectural decisions have been answering the why questions that code cannot answer since the 1990s.

That distinction is not pedantry. It decides how much process you are allowed to spend. Teams get into trouble in both directions: a two-week review for a thing you can revert on Friday, and a Tuesday-afternoon shrug for a thing that locks in a schema for three years.

How to make better architecture decisions in seven steps

You make better architecture decisions by running the same short sequence every time: classify the decision, name one owner, frame three options, set a deadline, write kill criteria, decide and commit, then review on a date you booked in advance.

That is the whole method. Everything else in this post is detail about one of those steps, because each of them fails in its own way.

The classification fails when you guess. The owner fails when there are five. The options fail when one of them is a straw man.

The deadline fails because nobody set one. The kill criteria fail because you wrote them after you fell in love with the answer.

Here is the sequence in the order I would run it:

1. Classify reversibility. One-way door or two-way door, before you choose a process.
2. Name one owner. A person, not a group, with a stated date to decide.
3. Frame three options. Include the status quo and the smallest reversible version.
4. Set the decision date. Diarised, shared, and sized to the door.
5. Write the kill criteria. The conditions that would make you reverse.
6. Decide and commit. Record the choice, the trade-off, and the owner.
7. Review on the booked date. Compare the outcome with the criteria, then act.

Two of those steps are the ones you will skip, and they are the cheapest: the date and the kill criteria. A decision without a date will expand to fill the attention available. A decision without kill criteria will be defended long after the evidence turned.

The design-doc practice at Google puts the intellectual weight in the same place. The doc exists to capture the trade-offs you made in designing your software, and the alternatives section is described as one of the most important ones because it shows why the chosen design wins against the ones a reader would otherwise wonder about. Nothing in that advice is about formatting.

If you want the sequence for the design that follows the decision, rather than the decision itself, the practical system design guide covers it.

Is this a one-way door or a two-way door?

If you can undo the change in a sprint at a cost you would accept without a meeting, it is a two-way door. If undoing it means moving data, breaking a contract, or re-planning another team's quarter, it is a one-way door. Classify before you pick a process.

Bezos drew the split in Amazon's 2015 shareholder letter: Some decisions are consequential and irreversible or nearly irreversible – one-way doors – and these decisions must be made methodically, carefully, slowly, with great deliberation and consultation. The letter calls those Type 1. Most decisions are changeable, reversible – they're two-way doors, and those can and should be made quickly by high judgment individuals or small groups.

The more useful half of the letter is the failure mode. As organizations grow, they use the heavy-weight Type 1 decision-making process on most decisions, including many Type 2 decisions, which produces slowness, unthoughtful risk aversion, failure to experiment sufficiently, and consequently diminished invention. That is the error you will actually see this quarter: a change that could ship on Thursday goes through a review board that meets on the second Tuesday of the month.

The opposite error is rarer in large companies and fatal in small ones. Bezos added a footnote for it: companies that habitually use the light-weight process on one-way doors go extinct before they get large. If you are in a startup, your risk is the reverse of the enterprise's. You are probably calling one-way doors two-way doors because the team is small and fast, and small and fast does not repeal data gravity.

Three questions that tell you which door you are standing at

Start with data, contracts, and other people's roadmaps. Those are the three places reversibility quietly disappears.

Can you reverse it without moving data? Data is the closest thing software has to concrete. Uber's currency service moved off PostgreSQL because incremental integer IDs could not be replicated the way its all-active data-center plan required, and the write-up is candid about what came next: Migrating consumers is a long, slow process, the team noted, so make it as easy as you can. A schema you can migrate in a maintenance window is a two-way door. A schema that three services and a reporting pipeline read directly is not.

Does it change a contract that someone outside your team depends on? A public API, an event schema, a shared table, a token format. If a consumer needs to change code before you can change yours, your reversibility depends on their calendar.

Would reversing it require another team's roadmap? Then the door is not yours to close or open. You are making a one-way door for somebody else, and you should say so out loud in the meeting.

If any of those is true, treat the decision as one-way even when the code change is twenty lines. The size of the diff is not the size of the commitment.

Doors also close by accumulation. Adopt a queue, add a service, give every team its own schema, and each step is reversible. Forty of them together become a platform you cannot leave, because leaving means forty migrations at once. That is how a team that made only reasonable local choices ends up with an architectural decision nobody remembers making.

Some doors are one-way because of physics rather than history. You cannot undo a consistency trade-off by working harder; you can only change what the product promises. The CAP theorem examples are the clearest place to see the difference between a choice you can revisit and a constraint you can only accept.

Who should actually make the call?

One named person, with the information and the accountability, on a date. Committees can shape a decision. They cannot own one.

Netflix is unusually explicit about the mechanism. Its culture memo says the company avoids decision-making by committee, which tends to slow companies down and undermine accountability, and instead identifies an informed captain for every significant decision. The captain is expected to farm for dissent — to seek out the opinions of people who know more, and to give those opinions more weight than seniority would suggest. Then the captain decides, and everyone else commits.

That last part is the bit teams drop. Amazon's version is the phrase disagree and commit, which Bezos called a time-saver in the 2016 letter: If you have conviction on a particular direction even though there's no consensus, it's helpful to say, 'Look, I know we disagree on this but will you gamble with me on it?' The leadership principles carry the same instruction to this day.

The failure this prevents is worse than a bad decision. Bezos named it precisely: without escalation, the default dispute resolution mechanism for this scenario is exhaustion. Whoever has more stamina carries the decision. The letter adds the line you should keep on a sticky note: 'You've worn me down' is an awful decision-making process.

Decision roles also explain why so many decisions stall. The authors of the HBR piece on decision roles found that decisions routinely get stuck inside the organization like loose change, and their fix was to assign explicit roles — the person who recommends, the people who must agree, the people who give input, the person who decides, and the people who perform the work. You do not need the full framework. You need the D: one name next to one decision.

What if two teams both own the outcome?

Give the decision to the team that will be on call for it, and make the other team a required reviewer with a deadline. Ownership follows maintenance, not enthusiasm.

If two teams genuinely share the pager, split the decision. Two records, two owners, one interface between them. If neither team will carry the pager, you have found the real problem: nobody has agreed to live with the result, so nobody should be deciding it yet.

The tie-break has to be a person and a date. One level up, one meeting, one decision, written down. Netflix's memo allows managers to step in when a decision is unethical, could materially harm the company, happens during a crisis, or comes from someone who lacks context — and frames all of that as the exception.

If your manager is in every architecture decision, you do not have informed captains. You have a queue.

You can measure how bad this is without asking anyone's opinion. DORA's guidance on loosely coupled teams suggests tracking what percentage of design and architecture changes for your service require a formal approval process from a body outside your team. A high number is not a governance success. It is decision latency with a logo.

How many options should you put on the table?

Three, at minimum, and one of them must be change nothing or do the smallest reversible version. Two options turn a decision into a side-picking exercise, and the loudest side usually wins.

The three I want in every framing: the status quo with its true cost, the smallest reversible step that buys information, and the full version that solves the problem properly. If the smallest step is genuinely enough, you have avoided the decision entirely. If it is not, you now know why, which is exactly the evidence you need for the expensive option.

Google's design docs formalize this as the alternatives section, which lists alternative designs that would have reasonably achieved similar outcomes and focuses on the trade-offs that each respective design makes. The word that matters there is reasonably. An option nobody would pick is not an alternative, it is decoration.

For decisions where the trade-offs are genuinely hard to see, there is a heavier instrument. The SEI's Architecture Tradeoff Analysis Method evaluates an architecture against quality attribute goals and, in its own words, provides insight into how those quality goals interact with each other — how they trade off against each other. It typically takes three to four days and a room full of stakeholders.

That number is the point. ATAM is excellent and completely wrong for most of your decisions. Use the weight of the method as a signal: if a three-day evaluation would be absurd for this choice, you are holding a two-way door, and you should decide it this week.

Make the do-nothing option real

If you cannot describe the cost of the status quo in numbers your on-call rotation or your finance lead would recognize, you have not framed the decision. You have framed a preference.

Count the deploys that need coordination. Count the incidents caused by the coupling.

Count the days a new engineer needs before shipping safely. Put a monthly cost on the workaround somebody maintains by hand. None of these need to be precise; they need to be honest and comparable to the migration estimate.

This single move changes the argument. Instead of which architecture is better, the question becomes is the current pain bigger than the migration pain, and for how long. That is a question a team can answer. The first one is a question a team can only lose.

How fast should the decision be?

Decide by a date you set when you open the question, and size that date to the door. Days for a two-way door. Weeks for a one-way door. Never when we have time, because you will not have time.

Decision latency is the gap between someone saying we should look at this and a recorded choice with an owner. It is a delivery metric hiding in your architecture process, and most teams never look at it.

Start by timestamping two moments: when the question enters a document, issue, or channel, and when the decision lands with an owner and a date. Track the median, then track the ninetieth percentile. The median is usually fine. The tail is where the quarters go.

Bezos framed the stakes better than any process diagram: Day 2 companies make high-quality decisions, but they make high-quality decisions slowly. That was written about organizational decay, but the mechanism is local. A decision that waits for the one person who understands the billing tables is a decision with a single point of failure, and that person is eventually on holiday.

Amazon's writing culture is often copied badly at this point. The company replaced slide decks with six-page narrative memos read in silence at the start of meetings, which raises the quality of the argument. It does not make the decision faster, and it was never meant to. If you adopt it, adopt it for the decisions where the problem or the solution is genuinely ambiguous — the design-doc guidance from Google treats the document as overhead worth paying only when ambiguity is real.

For the biggest bets, Amazon works backwards from a press release and FAQ describing the finished product. That is a one-way-door instrument: it forces you to describe the customer outcome before you commit a year of engineering. Using it to choose a message broker is how a good practice becomes a bottleneck.

The DORA research behind Accelerate treats this as a delivery constraint rather than a personality trait: a loosely coupled architecture is one of the capabilities that predicts performance, precisely because teams can change their systems without waiting on permission.

When should you stop analyzing and commit?

Stop when no remaining unknown can flip the answer, or when the cost of waiting exceeds the cost of being wrong. Then commit, and spend the saved time on the reversal plan.

Bezos gave the operational version: most decisions should probably be made with somewhere around 70% of the information you wish you had. If you wait for 90%, in most cases, you're probably being slow. The number is not magic. The habit is: name the threshold before you start gathering, so you cannot move it every time a new document appears.

Herbert Simon described the underlying behavior decades earlier. Because information is costly and consequences are uncertain, people do not maximize; they satisfice — they do as well as they think is possible. Simon meant it as a description, not a compliment. In an architecture decision it is the correct standard, provided you set the bar deliberately instead of letting the loudest person set it.

Here is the test I use in the room. Ask everyone in the room to name the specific fact that would change your mind. If nobody can name one, the decision is ready. If somebody can, you have exactly one research task, and it gets a time box.

What you must not do is reopen the whole question, because that is how a decision becomes a hobby.

Analysis without a decision date is procrastination with better diagrams. The work feels like progress: more benchmarks, another spike, one more conversation with the platform team. None of it changes the answer, and all of it costs you the thing you cannot buy back.

What kill criteria should you set before you commit?

Two or three measurable conditions that would make you reverse or stop, written before you start, with a review date and a named person who acts on them. A decision without kill criteria is a commitment to defend your past self.

The cheapest way to find them is a premortem. Gary Klein's version of the exercise asks the team to assume the project has already failed, then generate plausible reasons why. The framing does real work: it makes dissent safe, because the dissenters are no longer attacking a plan that someone is proud of. They are explaining a failure that has already happened.

Good kill criteria look like the signals your operations already produce. Error budget burn on the service you are splitting out. Migration completion percentage against a date. Cost per request after the new tier lands.

The rate of support tickets about the thing you changed. Pick the two that would embarrass you to ignore, and write the threshold as a number rather than an adjective.

Book the review date before you ship

A kill criterion with no calendar entry is a wish. Put the review on the calendar at the same time you write the criteria, and invite the person who has to act on those thresholds.

Amazon's correction-of-error process is a useful model for the shape: action items must state priority, who is the person responsible, and a due date, and the mechanism exists to produce corrective actions, not just documenting failures. You do not need an incident to borrow the pattern. A decision review with no owner and no date will produce a paragraph nobody reads.

How do you correct a bad decision without a blame cycle?

Separate the decision from the person, review against the criteria you wrote, and change the system rather than the story. The question is never who chose this. It is which assumption failed, and what do we change now.

Amazon's COE guidance is blunt about the failure mode: the process is not a process for finding whom to blame, because blame suppresses the disclosure that makes the review useful. The same logic applies to architecture decisions. If reversing a decision costs someone their reputation, nobody will bring you the evidence that it needs reversing.

Bezos again, because the economics are the whole argument: you need to be good at quickly recognizing and correcting bad decisions. If you're good at course correcting, being wrong may be less costly than you think, whereas being slow is going to be expensive for sure. Netflix's memo expects the same reflection after the impact is clear, so that the next decision is better.

The mechanics differ by door. Reversing a two-way door is normal operation: flip the flag, redeploy, move on, no ceremony. Reversing a one-way door is a new decision with a migration plan, a new owner, and new kill criteria — not a rollback. Treating the second like the first is how teams end up with two half-migrated systems and no owner for either.

One discipline makes this survivable: review the decision, not the outcome alone. A good decision can produce a bad outcome, and a bad decision can get lucky. Ask whether the criteria you set were the right ones, and whether you would decide the same way with the same information. That is the only question that improves the next decision.

Where does the decision record fit — and where doesn't it?

At the end, as evidence. A record cannot rescue a decision that was never framed. It can only show what you knew when you chose.

This is exactly the problem Nygard described in 2011. Without a record, the next engineer has two options: blindly accept the decision or blindly change it. Both are expensive. The record exists so that neither is necessary, not so that a folder looks tidy.

Fowler adds the part that matters more than the archive: the act of writing them helps to clarify thinking, particularly with groups of people. Writing a document of consequence often surfaces different points of view. That is a quality effect, and it happens because writing forces the options and trade-offs into the open. You get it from the writing, not from the filing.

Spotify's sequence is the practical version. Teams arrive at decisions through request for comments and design reviews, then write the record once the proposal concludes. The proposal is where the decision is made. The record is the receipt, and the trigger for writing one is simply that a significant decision now exists.

The formats differ and none of them matters much. AWS Prescriptive Guidance, the ADR community index, and Thoughtworks' lightweight ADR technique all describe the same object with different headings. Pick one, keep it short, and stop optimizing the template.

What none of those formats can give you is the judgement upstream. If the owner was a committee, the options were two, the date was never set, and the kill criteria were written after the demo, the record will document a decision that was already weak. It will just do so neatly.

For the template itself, section by section, use the architecture decision record guide. For the judgement, stay here.

What this post is not — and what to read instead

This post is about the decision, not the paperwork or the architecture pattern. Three places to go next:

• Monolith vs microservices — for the trade-offs when the boundary itself is the one-way door.
• Modular monolith vs microservices — for when the honest answer is a boundary inside one deployable, not a new service.
• Event-driven architecture — for when asynchronous events look cheap and the kill criteria decide whether they stay cheap.