Direct Answer
An Architecture Decision Record (ADR) is a lightweight governance artefact that records an architectural decision — what was decided, why it was decided, what alternatives were considered, and what the consequences of the decision are. ADRs exist to solve a specific, pervasive problem: architectural decision rationale gets lost. Systems are built to reflect decisions that no one on the current team remembers making. New architects repeat analysis that was already done. Governance reviews lack evidence of past reasoning. The ADR is the discipline of writing down the decision, its context, and its justification at the time the decision is made — so future architects, auditors, and AI tools can understand why the architecture is the way it is. In enterprise EA, ADRs are stored in the Sparx EA repository as governed artefacts — not in Confluence, not in email chains, not in Word documents that are never found again.
Key Takeaways
- An ADR records what was decided, why, what alternatives were considered, and what the consequences are.
- ADRs solve the “why is it like this?” problem — decision rationale that architects cannot recover.
- The Michael Nygard format (Status/Context/Decision/Consequences) is the standard starting point.
- In Sparx EA: ADRs as Requirements elements with custom tagged values, stored in a Decision Register package.
- ADR status lifecycle: Proposed → Accepted → Deprecated → Superseded.
- ADRs link to the architecture elements they affect — a decision about a technology component links to that component in the model.
- AI tools (Copilot, Claude, Kernaro AI Hub) can surface relevant ADRs when architects face new decisions — preventing repetition of past analysis.
- ARB governance uses ADRs as the evidentiary record of architecture decisions.
Why Architecture Decision Rationale Gets Lost
The problem is structural. Architectural decisions are made in meetings, email threads, informal conversations, and Confluence pages. The decision outcome may be captured (a design document says “we will use PostgreSQL”) but the rationale is rarely captured with it (“we chose PostgreSQL because of the requirement for JSONB column support, the team’s existing expertise, and the vendor’s licensing model compared to SQL Server”).
Two years later, when a new architect questions why PostgreSQL was chosen, no one remembers. The team re-investigates, potentially reaching a different conclusion. The investment of the original analysis is wasted. Or worse: the original analysis had important constraints embedded in it (the JSONB requirement came from a specific use case) and the re-analysis misses those constraints.
The ARB (Architecture Review Board) has the same problem. Governance reviews require evidence that decisions were made deliberately, alternatives were considered, and risks were acknowledged. Without ADRs, this evidence does not exist.
The Michael Nygard ADR Format
The most widely adopted ADR format was published by Michael Nygard in 2011. It is deliberately lightweight — intended to be written at decision time, not as a retrospective documentation exercise. The core structure:
Title: A descriptive name for the decision. Numbered sequentially in an ADR register. Example: “ADR-047: Use PostgreSQL for the new Customer Data Platform”
Status: The current state of the decision. Values: Proposed, Accepted, Deprecated, Superseded.
- Proposed: Under discussion, not yet approved
- Accepted: Approved by the appropriate authority (ARB or equivalent)
- Deprecated: No longer recommended but still in effect (grandfathered)
- Superseded: Replaced by a newer decision (the newer ADR is referenced)
Context: The situation that required a decision to be made — the business or technical circumstances, constraints, requirements, and forces at play. This is the “why we had to decide something” section. It is written as a neutral description, not an argument.
Decision: The actual decision made, stated clearly and unambiguously. “We will use PostgreSQL as the primary database for the Customer Data Platform.” This is the record.
Consequences: What happens as a result of this decision — both positive (the benefits it delivers) and negative (the trade-offs or limitations it creates). The consequences section is what distinguishes a good ADR from a bare record — it acknowledges that every decision has trade-offs.
Extending the Format for Enterprise EA
For enterprise EA programs, the Nygard format is a starting point, not an endpoint. Sparx Services recommends adding:
Alternatives considered: List the options that were evaluated and the brief reasoning for rejection. Without this, the ADR does not capture the analysis investment. Future architects should not have to wonder “did they consider Option B?”
Rationale: More detailed reasoning than the Consequences section allows. Why this option over alternatives — the specific factors that drove the decision.
Impact: Which architecture domains, systems, or capabilities are affected by this decision?
Related decisions: ADRs that this decision depends on or is related to (predecessor decisions, subsequent decisions).
Review date: When this decision should be reviewed. Decisions about technology platforms should be revisited as the technology landscape evolves.
Decision authority: Who approved this decision — the ARB, the CTO, a domain architect. Establishes accountability.
Implementing ADRs in Sparx EA
Element type: Sparx EA does not have a native “ADR” element type — but the Requirements element with a custom MDG Technology stereotype is the appropriate approach. Create a custom stereotype ArchitectureDecision extending the Requirement element type.
Tagged values on the ArchitectureDecision stereotype:
ADR ID(text, auto-populated or manual) — ADR-001, ADR-002, etc.Status(enumeration: Proposed/Accepted/Deprecated/Superseded)Decision Date(date)Decision Authority(text)Business Domain(enumeration matching business domains)Alternatives Considered(memo)Rationale(memo)Review Date(date)Superseded By(text — references ADR ID of replacement decision)
Package structure: A “Decision Register” package at the top level of the EA repository, with sub-packages by business domain or technology domain. All ArchitectureDecision elements live in this package.
Element documentation: The Context, Decision, and Consequences sections are written as element documentation (Notes) — rich text fields in Sparx EA that support formatted content.
Relationships: ArchitectureDecision elements are linked to the architecture elements they affect using InfluenceRelationship (ArchiMate) or Dependency (UML) from the decision to the affected elements. This enables change impact analysis — if a technology component is being changed, all decisions linked to it can be retrieved.
Diagram: A “Decision Register” diagram displays all ADRs in the package, colour-coded by status. Accepted decisions are green; Proposed are blue; Deprecated are grey; Superseded are crossed out or greyed.
The ADR Lifecycle in ARB Governance
ADRs integrate directly with the Architecture Review Board (ARB) governance process:
- Proposed: An architect drafts an ADR in Sparx EA. Status = Proposed. The ADR is presented to the ARB for review.
- ARB review: The ARB reviews the context, alternatives, and rationale. May request changes or additional alternatives analysis.
- Accepted: The ARB approves the decision. Status updated to Accepted. Decision Date recorded. Decision Authority (ARB, CTO, domain architect) recorded.
- In effect: The accepted ADR governs subsequent architecture decisions in its domain. Future ADRs may reference it as a dependency.
- Review: On the Review Date (or when circumstances change), the decision is re-evaluated.
- Deprecated or Superseded: If the decision is no longer current, status is updated. A new ADR superseding the old one is created, linking back to the original.
The repository maintains the full history of decisions — accepted, deprecated, and superseded — providing the evidentiary record that governance and compliance require.
How AI Tools Use ADRs
With EA GraphLink deployed, connected AI assistants can query the Decision Register directly. This enables a capability that significantly reduces repeated analysis:
Precedent surfacing. When an architect is working on a new decision about, say, API gateway technology, they ask Copilot or Claude: “What architecture decisions have we made about API management?” The AI queries the EA MCP Server, retrieves all ADRs in the API management domain, and presents them with their context and rationale. The architect immediately understands what has been decided before and why.
Conflict detection. An AI can check whether a proposed decision conflicts with accepted decisions — “does this new proposal contradict ADR-023 about our cloud-first strategy?”
Governance evidence generation. An AI can summarise all ADRs relevant to a particular system for a governance review or audit, saving hours of manual research.
This is why well-maintained ADRs in Sparx EA become a compounding organisational asset: every decision recorded becomes a piece of intelligence that AI tools can surface for future architects.
Frequently Asked Questions
Q: Should ADRs be stored in Sparx EA or in a wiki like Confluence? Both have been used, but Sparx EA is strongly preferred for enterprise EA programs. ADRs stored in Sparx EA can be linked to the architecture elements they affect (creating searchable, relationship-navigable decision intelligence), queried by AI assistants via EA GraphLink, and managed with the same governance controls as other architecture artefacts. ADRs in Confluence are useful for developer-team contexts (where Confluence is the primary tool) but are isolated from the architecture model. For EA teams using Sparx EA, keep ADRs in the repository.
Q: Who writes ADRs — architects or developers? In an enterprise EA context, ADRs are typically written by architects — enterprise architects for strategic decisions, domain architects for domain-level decisions, and solution architects for project-level decisions. Development teams may maintain ADRs for code-level technical decisions (there is a strong ADR tradition in software engineering teams using Markdown ADRs in code repositories). The two practices can coexist — solution-level ADRs in Sparx EA for the enterprise record; code-level ADRs in the code repository for development teams. The EA ADR register captures the decisions that matter at the enterprise and domain level.
Q: How many ADRs should an EA program maintain? There is no right number — but a program that has been operating for two or more years with active ARB governance and multiple projects should have hundreds of ADRs, not dozens. If an EA program has fewer than 50 ADRs after two years, it is likely that decisions are being made without being recorded. The discipline of ADR creation is a governance behaviour that needs to be embedded in architecture processes — not left to individual architect initiative.
Q: What is the difference between an ADR and a Principle? An Architecture Principle is a high-level guideline that guides architecture decisions — “Cloud First,” “Security by Design,” “Prefer Open Standards.” A Principle is normative: it says what should be. An ADR records a specific decision made in a specific context: “We have decided to use AWS as our cloud platform for the Customer Data Platform because…” The ADR may reference the Principle (“consistent with our Cloud First principle”) but it is a specific, dated, contextual record — not a general guideline. Both are captured in Sparx EA (Principles as ArchiMate Principle elements; ADRs as ArchitectureDecision elements).
Q: Can AI generate ADR drafts from architecture discussions? Yes. AI assistants (Copilot, Claude) connected to meeting notes, email threads, or conversation transcripts can generate ADR drafts based on the decision content. An architect pastes or summarises a decision discussion; the AI produces a formatted ADR draft with context, decision, and consequences sections for the architect to review and refine. This reduces the friction of ADR creation significantly — the writing effort is the primary barrier to ADR adoption, and AI assistance addresses it directly.
Q: How are ADRs versioned when a decision changes? When a decision is revised, the original ADR is updated to status “Superseded” and a reference to the new ADR is added. A new ADR is created with status “Proposed” or “Accepted,” referencing the original. The original is retained in the Decision Register — it is important historical evidence. Deleting superseded ADRs removes the decision history. Sparx EA baselines can capture the decision register state at specific points in time, providing an auditable record of when decisions were in effect.
Q: Do ADRs need to be approved by the ARB, or can individual architects accept them? The decision authority depends on the scope and impact of the decision. Strategic decisions (choice of cloud platform, enterprise data architecture approach, major technology standard) should be approved by the ARB or equivalent senior governance body. Domain decisions (which API pattern to use within a domain, how to structure a domain’s data model) may be within a domain architect’s authority. Project decisions (specific implementation choices within an approved approach) may be within a solution architect’s authority. The Decision Authority tagged value in Sparx EA records who approved each ADR, making the governance chain clear.
Q: How do we migrate existing decision documentation into Sparx EA ADRs? Start with currently active, high-impact decisions — the decisions that govern the most significant systems or patterns in your current architecture. These warrant the migration investment. For historical decisions in old documents or Confluence pages, assess whether they are still in effect. Deprecated or superseded decisions from three years ago have lower priority. Create new ADRs for the active decisions first; add historical decisions as capacity allows. This is often a useful exercise for a new architecture team — the act of identifying and recording active decisions surfaces governance gaps and ambiguities that need resolution.
Q: What tools does Sparx Services use to build the ADR governance framework? Sparx Services builds the ADR governance framework as part of the Amplify engagement. This includes: the ArchitectureDecision MDG stereotype design (tagged value definitions, validation rules), the Decision Register package structure in Sparx EA, diagram template for the decision register view, integration of the ADR workflow with the ARB governance process, and the EA GraphLink query configuration that enables AI tools to surface relevant decisions. We also provide the governance process documentation (who creates ADRs, who approves them, when they are reviewed) and initial population of the register with existing active decisions.
Ready to Build Your Architecture Decision Register?
Sparx Services’ Amplify engagement includes ADR governance infrastructure: the MDG stereotype design, Decision Register package structure, ARB workflow integration, and AI-queryable configuration via EA GraphLink.
Your architectural decisions should be an organisational intelligence asset — not lost in email threads and meeting notes.
