Skip to content
Software Architecture Guide

Architecturally Significant Decision

Explanation

Section titled “Explanation”

An architectural decision is a conscious choice among several options for a design problem. Teams often make it together. Usually no single best answer exists (see Architectural Decision).

Not every decision matters equally. A significant decision is one that is hard and costly to change once made. Switching from one integration style to another is a typical case. It costs a lot, so the team should make that choice with care. (Integration Style explains the term.)

Signals of significance

The ASR test proposes five plus two criteria for judging whether a requirement, or another artifact such as a decision, is architecturally significant. (ASR stands for Architecturally Significant Requirement.) The criteria cover:

  • high business value or business risk, and stakeholder concerns;
  • demanding quality-of-service needs;
  • external dependencies;
  • impact across the whole system;
  • first-of-a-kind work;
  • past trouble with similar work.

The first five criteria are fairly objective. The last two depend more on context.

A high-importance, high-difficulty rating in a utility tree is another sign. A utility tree ranks quality scenarios by importance and difficulty.

Judgment, not arithmetic

The assessment is qualitative and subjective. It depends on context. The ASR test is not a calculator that produces a score. Use it to prompt a discussion.

Why it matters for documentation

Significant decisions are the ones worth recording. Arc42 section 9 holds decisions that are important, expensive, large-scale or risky, together with their rationales. Logging everything backfires. A decision log with more than 100 entries becomes hard to maintain. So focus on the decisions that matter.

Example

Section titled “Example”

A team must choose how two systems exchange data. Later, switching that approach would mean rewriting both systems. The team treats it as significant. They compare options, discuss it with stakeholders and record the result with its reasons. The same team also picks a name for an internal helper function. Changing that costs minutes and affects nothing else. They do not record it.

Trade-offs

Section titled “Trade-offs”

Recording only significant decisions keeps the log small and useful. The cost is that the call is subjective. Two teams may rate the same decision differently, and a decision judged minor today may prove costly later. Treat the criteria as prompts for discussion, not as a score.

Checks

Section titled “Checks”
  • The architecture decisions section lists only important, expensive, large-scale or risky decisions, each with its rationale.
  • The decision log is kept small enough to maintain and does not record every decision.
  • Hard-to-reverse decisions, such as the integration style, are explicitly identified as significant.
  • The reasons a decision was judged significant are stated, for example business risk, quality demands or cross-cutting impact.
Section titled “Related”

Sources

Section titled “Sources”