Why should a team document decisions they disagreed on?

Because disagreement is evidence that the decision was not obvious, and non-obvious decisions are the ones most likely to be relitigated when circumstances change or when new people join. A documented decision tells the next person why the choice was made, so they can evaluate whether the original reasoning still applies rather than restarting the same argument from scratch. Undocumented decisions get argued again.

What is an architectural decision record?

An architectural decision record is a short document that records a technical decision, the context it was made in, the options that were considered, and the reason for the choice. It is not a design document or a specification. It is a record of a decision already made, intended to be read by the people who will live with the decision later and need to understand why it was made the way it was.

What should a decision record contain?

Five things: the decision that was made, stated plainly. The context, meaning the situation that made the decision necessary. The options that were considered. The reasons for the choice. And the tradeoffs that were accepted. A decision record that states only the choice without the reasoning is not useful, because anyone who reads it later can see what was decided but not why, which is the part they need when they are trying to decide whether the original reasoning still applies.

Should the minority view be included in a decision record?

Yes. Recording why reasonable people on the team disagreed with the choice is part of recording the choice. The minority view often contains the specific conditions under which the decision should be revisited. If the team chose approach A over approach B because of a constraint that may change, the person who argued for B was making an argument that may become correct later. Including that argument helps future readers know when to reconsider the decision.

How long should a decision record be?

One to two pages of plain prose, or the equivalent in a structured format. Long enough to explain the reasoning clearly. Short enough that someone will actually read it. A decision record that runs to ten pages will not be read by the people who need it most. Write the context and the tradeoffs concisely rather than exhaustively.

When should a decision be revisited?

When the conditions that justified it change. The best decision records make this explicit by naming the conditions under which the decision should be reconsidered. If the team chose a monolithic architecture because the team was small, the record should note that this choice should be revisited when the team reaches a certain size or when the deployment complexity justifies the split. This turns the record from a historical artifact into a living document.

How do you document a decision without making people feel they lost an argument?

Frame it as a record of reasoning rather than a record of winners and losers. The purpose is not to validate one side of the argument. It is to preserve the thinking that went into the choice so it is available to people who were not in the room. Including the minority view as a legitimate position that the team weighed, rather than as an objection that was overruled, reflects how good decisions actually get made.

What format should a decision record use?

Whatever the team will actually read. For teams that work in Markdown, a simple text file in the repository is the most accessible format. For teams that use a wiki or a documentation tool, a page in that system is better. The format matters less than the location: decision records that live where engineers already go for context will be read. Records in a separate system that nobody uses will not.

How do you handle a decision that turned out to be wrong?

Record the update. Add a note to the original decision record explaining what changed, when it was reconsidered, and what the new decision is. Do not delete the original. The original record explains why the original choice was made, which is still relevant to understanding why the product is built the way it is. A decision record that shows how the team's thinking evolved is more useful than one that only shows the current state.

What is the difference between a decision record and meeting notes?

Meeting notes record what was said. A decision record records what was decided. Meeting notes are useful for people who want to know what happened in a meeting. A decision record is useful for people who want to know why the system is built the way it is and whether that reasoning still applies. The two serve different readers at different points in time.

How to document a decision the team disagreed on: Reveneau

The decisions most worth documenting are the ones the team argued about. Not the obvious choices, the ones where everyone agreed immediately, those do not need a record because anyone facing the same situation would reach the same conclusion. A contested decision was contested because the right answer was not clear, and the conditions that made one option better than another were specific. Those conditions can change. When they do, the next person who faces the question needs to know what the original reasoning was.

Without a record, that person restarts the argument from scratch. They talk to whoever is still on the team. They get a partial account of what was decided and no account of why. They make a choice that may replicate the original one or may overturn it, without knowing which history they are repeating.

This is why architectural decision records exist, and why the ones that matter most are written for decisions the team disagreed on.

What a decision record is

An architectural decision record is a short document that captures a decision already made. It is not a design document or a proposal. It records what was chosen, the context that made the decision necessary, the options that were on the table, and the reasoning behind the choice.

The most important part is the reasoning, not the choice. Anyone reading the record later can see what was decided by looking at the codebase. What they cannot see is why. The reasoning is what tells them whether the original logic still applies to the situation they are facing now.

A good decision record is one to two pages. It answers these questions: What was decided? What situation made this decision necessary? What were the realistic options? Why was the chosen option better than the others, given the constraints at the time? What was accepted as a tradeoff? A record that answers these questions and no more is useful. A record that runs to ten pages will not be read by the people who need it.

Why the minority view belongs in the record

Recording the view that did not win is part of recording the decision. The team member who argued for the other option was usually making a coherent argument. Including it is not about validating the losing side. It is about preserving the specific conditions under which the decision might be revisited.

If the team chose to keep a monolithic architecture because the team was small and the deployment complexity of a service split was not worth it, the person who argued for splitting the services was probably right that splitting would become necessary eventually. Including their argument tells future readers: here is the condition under which we should reconsider. If the team grows past a certain size, or if the deployment friction from the monolith becomes the main source of slowdowns, that is the moment to revisit the choice.

A decision record that includes only the winning position records a choice. A decision record that includes the minority view records a choice with the conditions under which it should be reconsidered. The second version is more useful over time.

How to frame it without assigning blame

The goal is a record of reasoning, not a record of who won. That framing matters for how the document reads and for whether the people who disagreed will engage with it honestly.

Write the minority view as a position that reasonable people held, with the specific reasons they held it. "The team considered building a separate service for the notification system. The argument for this was that notification volume would eventually justify independent scaling, and coupling the notification logic to the main application would make both harder to change." This is a fair account. It respects the people who made the argument and it gives readers the information they need.

Compare that to: "Some team members preferred a microservices approach, but we decided against it." That version preserves the choice but loses everything that makes the record useful.

Where to keep decision records

Decision records that live where engineers already go for context will be read. Records in a separate documentation system that nobody uses will not. For most engineering teams, the right location is the repository: a directory called decisions or adr with one file per decision, in Markdown. The decision is in the same place as the code it explains, and it is versioned alongside the code.

This matters most when the decision is about the structure of the code itself. If the decision explains why the product uses one database rather than two, or why a particular abstraction was introduced, the record belongs next to the code that embodies the decision. A reader who wants to know why the code is shaped this way should not have to look in a separate system.

Keeping records current

A decision that gets reconsidered should produce an update to the original record, not a new document that replaces it. Add a note at the top: the original decision, made on a specific date, was updated on a later date. The new record explains what changed and what was decided.

Do not delete the original. The original record explains why the product was built the way it was during the period when the original decision was in effect. Future readers working through the history of the codebase need to know that the architecture changed, and why the original architecture made sense at the time it was chosen. A decision record that only shows the current state has lost the reasoning that connects each stage of the product's history.

The decisions that never get written down

The highest-value decision records are the ones that feel too controversial to write down formally. A decision to use a third-party service rather than build in-house. A choice to defer a security feature until a later release. A tradeoff between consistency and performance that reasonable engineers argued about for weeks.

These decisions are contested because they were genuinely hard, and the reasoning behind them is exactly what future engineers need. The teams that document them have fewer repeated arguments and fewer cases where a new engineer undoes a decision the team spent weeks reaching, because the reasoning that produced the decision is available to anyone who reads the record.

The team that argues hard and then writes down nothing has done half the work.

How to document a decision the team disagreed on