Skip to content
Software Architecture Guide

Definition of Done for Architectural Decisions

Explanation

Section titled “Explanation”

Agile teams use a Definition of Done to avoid misunderstandings and keep everyone focused. The same idea can be applied to architectural decisions. Feature-level Definitions of Done and Ready do not say when technical design work is ready or finished. Decision-specific criteria fill that gap. The article “Architectural Decision Definition of Ready” covers the counterpart at the start of a decision.

One proposal abbreviates five exit conditions as ecADR:

  • Evidence: the team has gained reason to believe the chosen design will work.
  • Criteria: at least two alternatives were identified, investigated, and compared.
  • Agreement: a mentor or peer, plus the team, challenged the decision. They accept the outcome and the rationale. Agreement can be light. Sometimes nobody objecting in a design workshop or review meeting is enough.
  • Documentation: the decision is captured and shared, preferably in a lean, light template.
  • Realization and review: the team knows when to realize the decision, review it, and possibly revise it.

The quick test turns these into five questions. If you can answer “yes” five times, the decision is done.

Timing matters too. Deciding too early harms flexibility. Deciding too late is also bad. The criteria help a team notice when a decision is premature or poorly founded. The article “Last Responsible Moment” covers timing in more depth.

Teams can use the five questions as a checklist in a decision meeting or when reviewing a decision record. One design practice collection lists establishing done criteria, such as ecADR, as part of decision capturing. It also suggests lean templates such as MADR or Y-Statements. See “Markdown Architectural Decision Records” and “Y-Statement”.

Example

Section titled “Example”

A team must choose how two services exchange data. They test one option with a small prototype and feel confident it works. They compare it with a second option. In a review meeting, nobody objects. They write a short decision record. They note that they will review the choice after the first release. All five answers are yes, so the decision is done.

Trade-offs

Section titled “Trade-offs”

ecADR is one proposal, not a standard. The sources do not describe broad agreement on how to define “done” for decisions. Teams may adapt the criteria. Keeping agreement light, as in a review meeting where nobody objects, saves time. A stricter check may suit riskier decisions. The facts given do not say how to choose between them.

Checks

Section titled “Checks”
  • The decision record shows at least two alternatives that were investigated and compared.
  • The decision is captured and shared in a lean template.
  • The record states who challenged the decision and that the team accepts outcome and rationale.
  • The record says when the decision will be realized and reviewed.
  • The record gives a reason to believe the chosen design will work.
Section titled “Related”

Sources

Section titled “Sources”