Skip to content
Software Architecture Guide

Architectural Decision Management

Explanation

Section titled “Explanation”

Architectural decisions are choices that shape a system. Managing them means caring about the whole life of a decision, not only the moment of choosing. See Architectural Decision Management Cycle for the cycle itself.

Select what deserves a record. Not every decision needs an Architectural Decision Record (ADR). arc42 advises documenting only architecturally significant decisions. These affect structure, quality characteristics and important dependencies, especially external ones. arc42 also points to decisions that are important, expensive, large-scale or risky. A significance test can help prioritize. It is a qualitative judgment, not an exact calculation.

Decide at the right time. Each decision has a Most Responsible Moment (MRM). Hitting it matters.

Check readiness. START is a definition of ready. It holds five criteria to answer before a decision is made. Once they are met, the decision should be made.

Check completeness. ecADR names five exit criteria. It works as a quick yes/no test. Five “yes” answers mean the decision is done.

Justify well. A good justification refers to the requirements and the information gathered. It also cites supporting evidence, criteria and agreement. Do not list fake alternatives just to satisfy a template. arc42 adds that all consequences belong in the record, not only the positive ones.

Decide with care. One fallacy is assuming that what worked for others will work for you. The countermeasure is to make your requirements and context explicit. Some bias is unavoidable in big decisions, so blending in gut feeling is acceptable.

Involve people. Plan stakeholder involvement ahead, at least a little. Otherwise it may be forgotten. At higher maturity levels, the ADR review process is documented and enforced, depending on the type of decision. Sharing decisions only pays off when people have architecting skills and experience.

Example

Section titled “Example”

A team must pick how its web shop talks to a payment provider. The choice is external, costly to undo and affects reliability, so it passes the significance test and gets an ADR. The team waits until the requirements are clear enough, then checks its readiness criteria. It writes the justification with the requirements, evidence and the agreement of the people involved. It lists the downsides as well as the benefits. A short yes/no check confirms the decision is done. A minor choice, such as a button color, gets no ADR.

Trade-offs

Section titled “Trade-offs”

Recording every decision costs effort and buries the important ones, so selection is needed. The significance test is only a rough guide, so judgment stays necessary. Gut feeling is acceptable, but it brings some bias. Higher maturity means documented and enforced reviews, which also asks for more skills and effort.

Checks

Section titled “Checks”
  • The ADR log contains only architecturally significant decisions, those affecting structure, quality characteristics or important dependencies.
  • Each ADR justification refers to requirements, gathered information, evidence, criteria and agreement.
  • Alternatives listed in an ADR are real options, not filler added to satisfy a template.
  • Each ADR lists all consequences, not only the positive ones.
  • Stakeholder involvement in decisions is planned ahead.
Section titled “Related”

Sources

Section titled “Sources”