Tracking Software Architecture Decisions

The Cost of Undocumented Decisions

Maybe this sounds familiar. You join a new team and are asked to keep evolving an existing product. The solution uses an uncommon architectural pattern — say, Event Sourcing for persisting domain aggregate state. You have opinions about that choice, but more urgently, you want to understand why it was made. You dig through the docs and come up empty. You ask the engineers. They don’t know either.

This is more than an inconvenience. Architecture decisions are load-bearing: they shape maintainability, performance, security, and every other quality attribute the product will live or die by. When the rationale disappears, so does the ability to evolve the system confidently. Every future change becomes an exercise in archaeology.

Why Architecture Decisions Are Hard to Track

There is no perfect architecture decision. Good architects don’t search for the “right” answer — they navigate trade-offs, make their reasoning transparent to stakeholders, and put mitigations in place to manage the consequences. That process only holds value if it is recorded.

The challenge is that modern software teams move fast. Agile practices, scaled through frameworks like SAFe in larger organizations, prioritize delivery over documentation. Decision tracking processes that are too heavy become obstacles. The goal is to find a format that captures enough context to be useful years later without grinding the team to a halt.

The Compliance Dimension

In most software products, undocumented decisions are a technical debt problem. In regulated industries — medical devices, financial systems, aviation, critical infrastructure — they are a compliance problem.

Regulatory frameworks such as IEC 62304, FDA 21 CFR Part 11, or ISO 26262 require evidence that architectural choices were made deliberately, with awareness of their risks and rationale. Auditors don’t accept “we thought it was a good idea at the time.” They ask for documented decision-making trails: what options were considered, what was chosen, who approved it, and why.

Without a structured process, teams end up reverse-engineering justifications during audits — a slow, expensive, and risky exercise. Getting this right up front is far cheaper.

Architecture Decision Records

Architecture Decision Records (ADRs) are the standard tool for capturing this trail. An ADR is a short, structured document that records a single significant architecture decision: the context that drove it, the options considered, the decision made, and its consequences — both the benefits and the trade-offs accepted.

ADRs are not design documents or technical specifications. They are decision logs. Formats vary (MADR and Nygard’s original template are popular starting points), but the key is consistency and accessibility within the team.

Having the format is only half the problem. The other half is governance: making sure ADRs are actually written, reviewed, approved, and kept current as the system evolves.

The Decision Tracking Process

The following process ensures ADRs are produced with the right level of rigor and the right stakeholders involved.

graph TD
  %% Team Interactions
  subgraph "Team Interactions"
      A[Enabler / Story Refinement] --> B{Architecture Concern}
      C[Architecture Decision feedback sharing] --> B
      D[Inspect and Adapt Sessions] --> B
  end

  %% Architecture Team
  subgraph "Architecture Team"
      B --> S1[S1. Register & Prioritize Architecture Backlog Item, assign ADR Owner]
      S1 --> S2[S2. Gather Inputs / Perform Analysis]
      S2 --> S3[S3. Prepare / Update ADR]
      S3 --> D1{Ready for decision}
      D1 -- No --> S3
      D1 -- Yes --> S4[S4. Publish ADR for Pre-Reading by AB Members]
  end

  %% Architecture Board
  subgraph "Architecture Board"
      S4 --> S5[S5. Review ADR on Architecture Alignment]
      S5 --> S6[S6. Collect and review comments in GitHub pull request]
      S6 --> D2{Agreement}
      
      D2 -- No --> D3{Additional Considerations}
      D3 -- Yes --> S3
      D3 -- No --> S7[S7. Designated Software Architect make final decisions]
      
      S7 --> D4{Escalations / Organization wide impact}
      D4 -- Yes --> S8[S8. Involve Stakeholders]
      S8 --> D2
      
      D2 -- Yes --> S9[S9. Sign ADR accept merge request]
      D4 -- No --> S9
      
      S9 --> D5{Replaces existing ADR}
      D5 -- No --> End(( ))
      D5 -- Yes --> S10[S10. Supersed former ADR and indicate replacement]
      S10 --> End
  end

  %% Styling for the end node
  style End fill:#000,stroke:#f00,stroke-width:4px

Identifying Architecture Concerns

The Team Interactions group captures the moments when architecture concerns surface. These are not always dramatic inflection points — they often emerge quietly during routine team activities:

• Product definition and refinement: At any backlog level (epic, capability, feature, story), architects should be present to spot concerns early. An architectural risk identified during refinement costs far less to address than one discovered during implementation.
• Team feedback loops: Architecture review sessions, system demos, iteration reviews, and retrospectives are all signals. If engineering teams are struggling with a past decision, that friction needs to surface. Architecture that teams don’t believe in doesn’t get implemented well, the earlier misalignments are caught, the better.

Analyzing and Drafting the ADR

The Architecture Team group, and, where relevant, technical leads from delivery teams, meets regularly to move concerns through the pipeline.

• S1 — Register and prioritize: Concerns enter the architecture backlog as enablers, get prioritized, and are assigned an ADR owner. The first concrete output is the ADR document itself, created in source control (we use GitHub) on a feature branch.
• S2 — Gather inputs and analyze: The assigned architect works with stakeholders and delivery teams to understand the problem space. This phase often spawns spikes — short, time-boxed investigations to evaluate alternatives. The depth of analysis should match the weight of the decision.
• S3 — Write the ADR: Analysis feeds the document. A well-formed ADR captures the decision context, the options considered (including their trade-offs), the decision made, and its consequences — both the benefits and what was accepted as a cost. This is the artifact auditors will eventually read.
• S4 — Open for review: When the ADR is ready, a pull request is opened and reviewers are assigned. Review is not limited to architects; engineers, product owners, and product managers are all valid stakeholders and often catch blind spots that purely technical reviewers miss.

Review, Agreement, and Acceptance

The Architecture Board group is where the decision is finalized. The architecture team reviews the ADR in their regular alignment meetings, aiming for consensus.

• S5 — Present and discuss: The ADR owner walks the team through the document. Reviewers have until the next meeting to study it and formulate feedback.
• S6 — Resolve comments: Feedback goes into the pull request as comments. The ADR owner responds and refines the document accordingly. This is deliberate: the full review trail (every question raised, every concern addressed) lives permanently in the PR, accessible to future maintainers and auditors alike.
• S7 — Designated architect decides: If consensus isn’t reached within a reasonable timeframe, the accountable architect (enterprise, solution, or system level, depending on the scope) makes the final call. Decisions cannot be delayed indefinitely. Accountability has to live somewhere.
• S8 — Escalate to stakeholders: A safety valve for cases where the architect’s decision is disputed with good cause. Stakeholders re-enter the loop to break the deadlock. Reaching this step is a signal that earlier alignment was insufficient.
• S9 — Accept and merge: Once approved, the ADR is merged to main. It is now official. From this point, ADRs are immutable, they record what was decided and why, not what we wish we had decided. Engineering teams implement against it, leveraging the analysis from S2.
• S10 — Supersede former decisions: If the new ADR replaces an existing one, the old record is updated to status Superseded with a reference to its replacement. The history remains intact; nothing is deleted.

Balancing Governance with Agility

This process can look heavyweight at first glance. In practice, once the analysis phase (S2) is complete, moving through to a merged ADR typically takes no more than two weeks. The upfront investment in rigor pays compounding returns: a clear, searchable decision history stored in the same tooling engineers use every day (GitHub, GitLab, or equivalent), with no separate wiki to maintain or knowledge base to keep in sync.

Critically, this is a collaborative process, not a top-down one. Engineering teams are involved at every stage — surfacing concerns, running spikes, reviewing drafts, and pushing back when something doesn’t feel right. That involvement is what keeps intentional architecture grounded in the reality of delivery, rather than drifting into documents that nobody reads.

Closing Thoughts

In a regulated product, undocumented architecture decisions are a liability — sometimes literally. But even outside regulated contexts, the pattern holds: teams that can explain their choices evolve their systems with confidence; teams that can’t are held hostage by the accumulated weight of forgotten reasoning.

ADRs, backed by a lightweight governance process, are a practical answer. They don’t require a dedicated tool or a heavyweight process. They require discipline: a habit of writing decisions down, getting the right people to weigh in, and keeping the record accessible. That habit is worth building early, before the first auditor asks, and before the next engineer joins the team wondering why things are the way they are.