Architecture decision records: the habit I bring to every engagement

What an ADR is

The idea comes from a short 2011 post by Michael Nygard. Record each architecturally significant decision in a small document with a title, the context, the decision, its status and its consequences¹⁵. Consequences include the downsides, not just the benefits⁵.

Two rules make the format work. First, records are short: one decision, one page. Second, they are immutable. When a decision changes, you write a new record that supersedes the old one and link them, rather than editing history².

The practice spread widely. Thoughtworks put lightweight ADRs in the Adopt ring of its Technology Radar, recommending they live in source control as simple markup rather than in a wiki³.

The template I use

# ADR-014: Use an event-driven core for order processing

Status: Accepted (supersedes ADR-006)
Date: 2026-10-19
Deciders: CTO, platform lead, payments lead

## Context
Synchronous calls between order, payment and inventory
services cause timeouts at peak and cascading failures.

## Decision
Move order state changes to events via a transactional
outbox. Consumers are idempotent.

## Consequences
+ Peak load absorbed by queues; services fail independently
+ Clear audit trail of state changes
- Eventual consistency; UI must handle "processing" states
- New operational skills needed for the broker

## Options considered
1. Scale the synchronous services (rejected: cost, still coupled)
2. Event-driven core (chosen)

I add two sections to Nygard's original. Options considered shows the decision wasn't a default. Deciders makes ownership explicit. The example comes from the pattern in my post on idempotent payment and order pipelines.

Why I insist on them as a fractional CTO

• Decisions get faster. Writing the context and options forces clarity. Half the debates end when someone writes down what the options actually are.
• Disagreement becomes productive. People argue with a document, not with each other. Review comments on an ADR pull request are calmer than meetings.
• New hires ramp up faster. Reading twenty ADRs explains a system better than any onboarding deck.
• Handover is built in. When I step back, the reasoning stays. That matters more for a part-time leader than for anyone.
• Due diligence gets easier. Investors and acquirers can see that decisions were deliberate. I look for ADRs in every technical due diligence I run.

What counts as "architecturally significant"

Not every choice needs a record. My rule of thumb is to write one when a decision is expensive to reverse, affects more than one team, or will make someone ask "why?" in a year. In practice:

• Choosing a database, queue, cloud provider or core framework.
• Adopting a pattern across services: events, multi-tenancy, an AI gateway.
• Security, compliance and data-residency choices.
• Choosing an AI model provider, or deciding to run models locally.
• Deliberately accepting technical debt, with the conditions for paying it back.

Making the habit stick

1. Keep them in the repository, in a docs/adr folder, numbered.
2. Review them like code. An ADR is a pull request with reviewers.
3. Write them at decision time, not afterwards. A reconstructed ADR loses the alternatives that were rejected.
4. Link from code. A comment pointing to ADR-014 above a surprising piece of code saves an hour of archaeology.
5. Revisit quarterly. Mark superseded records, and check whether accepted debt has been repaid.

Red Hat's guidance makes a similar case for treating ADRs as a lightweight, continuous practice rather than a documentation project⁴.

ADRs for AI decisions

AI systems make this even more important. Which model, which retrieval approach, which guardrails, which data may be sent to a hosted provider: these choices change often and carry real risk. An ADR trail gives you the documentation that regulations increasingly expect, such as the EU AI Act's emphasis on technical documentation, which I cover in the EU AI Act after the Digital Omnibus.

How I can help

As a fractional CTO I set up decision records and architecture governance in the first month, and leave a team that owns its decisions. Or analyse your challenge and bring the result to a call.