What Is an Architecture Decision Record (ADR)? Template and Guide for EA Teams

In an enterprise enterprise architecture program, ADRs belong in the architecture repository as governed records — not scattered across Confluence, email chains, and Word documents that are never found again. The rest of this guide covers the format, how to extend it for enterprise use, and how to implement it in Sparx EA.

Why architecture decision rationale gets lost

The problem is structural. Decisions are made in meetings, threads, and informal conversations. The outcome often survives — a design document says “we will use PostgreSQL” — but the rationale rarely does: “we chose PostgreSQL for its JSONB support, the team’s existing expertise, and the licensing model versus SQL Server.”

Two years later, a new architect questions the choice. Nobody remembers. The team re-investigates and may reach a different answer — wasting the original analysis, or worse, missing a constraint that was embedded in it (the JSONB requirement came from a specific use case the re-analysis never sees).

The Architecture Review Board (ARB) faces the same gap. Governance reviews need evidence that decisions were deliberate, that alternatives were weighed, and that risks were acknowledged. Without ADRs, that evidence simply does not exist.

A decision without a recorded rationale is a decision your organization will pay to make again.

The Michael Nygard ADR format

The most widely adopted ADR format was published by Michael Nygard in 2011. It is deliberately lightweight — meant to be written at decision time, not as a retrospective documentation chore.

Title. A descriptive name, numbered sequentially in an ADR register. Example: “ADR-047: Use PostgreSQL for the new Customer Data Platform.”

Status. The current state of the decision:

• 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, which is referenced

Context. The situation that required a decision — the business or technical circumstances, constraints, and forces at play. Written as a neutral description, not an argument.

Decision. The actual decision, stated clearly: “We will use PostgreSQL as the primary database for the Customer Data Platform.” This is the record.

Consequences. What follows — both positive (the benefits) and negative (the trade-offs). The consequences section is what separates a good ADR from a bare record: it acknowledges that every decision has a cost.

Extending the format for enterprise EA

For enterprise programs, the Nygard format is a starting point. Sparx Services recommends adding:

• Alternatives considered — the options evaluated and the brief reasoning for rejection. Without this, the ADR fails to capture the analysis investment.
• Rationale — more detailed reasoning than Consequences allows: the specific factors that drove the choice.
• Impact — which architecture domains, systems, or capabilities the decision affects.
• Related decisions — predecessor and successor ADRs this one depends on.
• Review date — when the decision should be revisited as the landscape evolves.
• Decision authority — who approved it (the ARB, the CTO, a domain architect). This establishes accountability.

Implementing ADRs in Sparx EA

Element type. Sparx EA has no native “ADR” element, but a Requirement element with a custom stereotype is the right approach. Create a custom ArchitectureDecision stereotype extending the Requirement type, defined through your MDG Technology.

Tagged values on the ArchitectureDecision stereotype:

• ADR ID — ADR-001, ADR-002, and so on
• Status (enumeration: Proposed / Accepted / Deprecated / Superseded)
• Decision Date (date)
• Decision Authority (text)
• Business Domain (enumeration matching your domain taxonomy)
• Alternatives Considered (memo)
• Rationale (memo)
• Review Date (date)
• Superseded By (text — references the replacement ADR ID)

Package structure. A “Decision Register” package at the top level of the repository, with sub-packages by business or technology domain. All ArchitectureDecision elements live here.

Documentation. The Context, Decision, and Consequences sections go in the element’s Notes — Sparx EA’s rich-text documentation field.

Relationships. Link ArchitectureDecision elements to the architecture elements they affect using an InfluenceRelationship (ArchiMate) or Dependency (UML). This enables change-impact analysis: if a component changes, every decision linked to it can be retrieved.

Diagram. A “Decision Register” diagram displays all ADRs, color-coded by status — Accepted in green, Proposed in blue, Deprecated in gray, Superseded greyed or crossed out.

The ADR lifecycle in ARB governance

ADRs integrate directly with the ARB governance process:

1. Proposed — an architect drafts an ADR in Sparx EA and presents it to the ARB.
2. ARB review — the board reviews context, alternatives, and rationale; may request additional analysis.
3. Accepted — the ARB approves; status, Decision Date, and Decision Authority are recorded.
4. In effect — the accepted ADR governs subsequent decisions in its domain and may be referenced as a dependency.
5. Review — on the Review Date, or when circumstances change, the decision is re-evaluated.
6. Deprecated or Superseded — a new ADR replaces the old one, linking back to it.

The repository keeps the full history — accepted, deprecated, and superseded — the evidentiary record that governance and compliance require. Well-maintained ADRs become a compounding asset: every recorded decision becomes intelligence that architecture governance and search tools can surface for future architects. Where AI assistants are connected to the repository, that same register can answer “what have we decided about API management?” without an architect digging through old documents.

Frequently asked questions

Build your decision register with Sparx Services

Sparx Services helps you stand up ADR governance end to end: the ArchitectureDecision stereotype design, the Decision Register package structure, the diagram template, and integration with your ARB workflow — delivered as part of Configure the Solution. Your architectural decisions should be an organizational intelligence asset, not lost in email threads and meeting notes. See how the broader practice fits together under AI Augmented Architecture, or start from where your architects spend their day.