ADRs in an evolutionary architecture

An architecture decision record (ADR) is a short document that captures one architecturally significant decision: the context, the decision, and its consequences. A collection of ADRs forms a decision log.

Why ADRs matter for evolution

Evolutionary architecture expects decisions to be revisited as things change. ADRs make that possible:

• They preserve context. Later, you can tell whether a decision was wrong or whether the conditions it depended on have changed.
• They’re superseded, not edited. AWS’s ADR guidance says an ADR becomes immutable once it’s accepted or rejected. If a new insight calls for a different decision, you write a new ADR that supersedes the old one. The log becomes a history of how the architecture evolved.
• They connect to fitness functions. A decision is only real if something checks that it’s followed. MADR’s optional Confirmation section is a good place to name the fitness functions that enforce the decision.
• They make trade-offs explicit, including what you chose not to optimise for. That links each decision back to the ranked characteristics.
• They suit decentralised decisions. With the advice process, the person deciding writes the ADR and records the advice they received.

Lifecycle

Based on the AWS Prescriptive Guidance ADR process:

1. The owner (usually whoever drafts it) writes the ADR with status Proposed.
2. The team reviews it at least once, then accepts it, rejects it, or asks for rework.
3. Once accepted or rejected, the ADR doesn’t change.
4. A later ADR can supersede it. Both records stay in the log, linked to each other.

The MADR format

These examples use MADR (Markdown Architectural Decision Records). Its required sections are the title, context and problem statement, considered options, and decision outcome. Optional sections include decision drivers, consequences, confirmation, the pros and cons of each option, and more information.

# {Short title of the problem and solution}

- Status: {proposed | accepted | rejected | superseded by ADR-NNNN}
- Date: {YYYY-MM-DD}
- Deciders: {who}

## Context and Problem Statement
## Decision Drivers
## Considered Options
## Decision Outcome
### Consequences
### Confirmation
## Pros and Cons of the Options
## More Information

These examples add one thing to More Information: Revisit when. These are explicit triggers for reopening the decision. That’s the evolutionary part: deciding up front what would make this decision wrong.

The scenario for these examples

Worked examples, not real decisions

These ADRs are for a hypothetical organisation, to practise the format and the reasoning. The facts about AWS services were checked against AWS documentation where cited, but the decisions themselves are illustrative reasoning, not recommendations for any real organisation. Your context will change the answers.

The same scenario as the characteristics worked example: a regulated organisation building a shared AWS platform for about 40 product teams, with an EU expansion planned. Its driving characteristics are:

1. Security and auditability
2. Self-service
3. Evolvability

ADR	Decision	Reversibility
ADR-0001	Account and OU structure	Hard (one-way door)
ADR-0002	Network topology	Hard (one-way door)
ADR-0003	Cross-team event backbone	Medium
ADR-0004	IaC tooling and golden paths	Medium

Sources

• AWS Prescriptive Guidance, ADR process and FAQ.
• InfoQ, AWS publishes guidance on architecture decision records.
• MADR and Olaf Zimmermann’s MADR template primer.
• Michael Nygard, Documenting Architecture Decisions (the original ADR post).