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

In an enterprise architecture program, ADRs belong in the architecture repository as governed records, where they can be linked to what they affect. Confluence pages, email chains and Word documents are where decisions go to be lost. This guide covers the format, how to extend it for enterprise use, how to implement it in Sparx EA, and how the work changes when AI drafts the record and the architect owns the decision.

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.” 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 missing a constraint embedded in it, such as a JSONB requirement that came from a 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 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 instead of 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.

Decision. The 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 makes a good ADR, because it acknowledges that every decision has a cost.

Extending the format for enterprise EA

For enterprise programs, the Nygard format is a starting point. We recommend adding:

• Alternatives considered: the options evaluated and the brief reasoning for rejecting each. Without this, the ADR loses the analysis.
• Rationale: more detailed reasoning than Consequences allows, naming the 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.
• 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. A Requirement element with a custom stereotype is the right approach: create an 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 Influence relationship (ArchiMate) or a 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 grayed or crossed out.

Writing ADRs AI-augmented

Today an architect writes the ADR after the meeting, fills in the tagged values by hand and links it to the affected elements, if there is time. Often there is not, which is why registers stay thin. Working AI-augmented, the architect states the decision, the context and the alternatives in a few plain sentences, or hands over the meeting notes, and AI drafts the ADR in the register, sets the tagged values, links it to the elements it affects and flags what is missing, such as an empty alternatives section or no decision authority. The architect reviews the draft and corrects it.

The skill this asks is being clear about the decision and the position behind it. AI can write the record. It cannot know why the team chose what it chose, which alternatives were seriously considered or which constraint mattered most, unless the architect says so. A drafted rationale that sounds plausible and is wrong is worse than none. Tools that help include Claude or GitHub Copilot with AI Power Tools for Sparx EA, and Kernaro Assist in the EA client.

The ADR lifecycle in ARB governance

ADRs fit directly into 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, and may request more analysis.
3. Accepted: the ARB approves, and status, Decision Date and Decision Authority are recorded.
4. In effect: the accepted ADR governs later 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 and links back to it.

The repository keeps the full history of accepted, deprecated and superseded decisions, the evidentiary record that governance and compliance require. A well-kept register grows in value: every recorded decision is something architecture governance and search can surface for future architects. With AI connected to the repository, the register can answer “what have we decided about API management?” without anyone digging through old documents, and AI can point out Review Dates that have passed.

Frequently asked questions

How we help

We can set up the decision register in your repository: the ArchitectureDecision stereotype, the Decision Register package structure, the diagram, and the link to your ARB workflow. We can then teach your architects to keep it current AI-augmented, or keep it current for you. See how the wider practice fits together under AI-augmented governance.