architecture-decision-record

name	architecture-decision-record
description	Capture significant architectural decisions as immutable, versioned MADR 4.0 records. Use when a choice is hard to reverse, affects multiple teams, or sets a long-lived constraint.

Architecture Decision Records (ADR)

ADRs make architectural intent legible. They convert tribal knowledge into a durable, searchable log of context, options, and consequences so future contributors understand why, not just what. Adopt MADR 4.0 (2025) as the canonical schema and keep records co-located with the code they govern.

Stack Baseline (2026)

Concern	Recommended
Schema	MADR 4.0 (adr.github.io)
Storage	docs/adr/NNNN-title.md in the owning repo
Tooling	adr-tools v4, log4brains, or Backstage TechDocs
Lifecycle states	Proposed, Accepted, Deprecated, Superseded
Review	PR-based, CODEOWNERS-gated, async RFC channel
Index	Auto-generated README.md rolled up in Backstage

When to Use

• Choosing a runtime, datastore, message bus, or auth model.
• Defining cross-cutting conventions (multi-tenancy, error contracts, eventing schema).
• Deprecating or replacing a previously accepted ADR.
• Recording a deliberate non-decision ("we will defer this until...").

Prerequisites

• Repo with docs/adr/ directory and CODEOWNERS entry.
• Markdown linter and PR template referencing an ADR checklist.
• Agreed numbering scheme (zero-padded, monotonic).
• Stakeholder list (consulted vs. informed) per Team Topologies.

Instructions

flowchart LR
  A[Trigger: significant decision] --> B[Draft ADR Proposed]
  B --> C[Async review on PR]
  C --> D{Consensus?}
  D -- yes --> E[Merge as Accepted]
  D -- no --> B
  E --> F[Implement + link from code]
  F --> G{Context changed?}
  G -- yes --> H[New ADR Supersedes prior]
  G -- no --> E

1. Detect a decision. If the choice is reversible within a sprint and local to one module, skip the ADR. Otherwise open a draft.
2. Scaffold from MADR 4.0. Use the template below; assign the next number; set status Proposed.
3. Frame the problem. State context, drivers (quality attributes), constraints. Link a Wardley Map or Cynefin domain when relevant.
4. Enumerate options. Minimum two viable alternatives plus "do nothing". Cite evidence (benchmarks, vendor docs, ThoughtWorks Radar Vol 31+).
5. Decide and record consequences. Capture positive, negative, and neutral consequences. Name owners and a review date.
6. Open PR for async review. Require approvals from CODEOWNERS and one consulted stakeholder. Resolve threads in-line.
7. Merge as Accepted. Reference the ADR id from affected READMEs and source files (// see ADR-0042).
8. Maintain lifecycle. Never edit accepted ADRs except to flip status. Supersede via a new ADR that links back: Supersedes: ADR-0042.

MADR 4.0 Template

# ADR-NNNN: <Short title of decision>

- Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
- Date: YYYY-MM-DD
- Deciders: @handle1, @handle2
- Consulted: @teamA
- Informed: #channel

## Context and Problem Statement
<2-4 sentences. What forces are at play? Link tickets, metrics, ADRs.>

## Decision Drivers
- <Quality attribute or constraint>
- <Cost / time-to-market>

## Considered Options
1. <Option A>
2. <Option B>
3. Do nothing

## Decision Outcome
Chosen option: "<Option B>", because <justification>.

### Consequences
- Positive: <…>
- Negative: <…>
- Neutral: <…>

## Pros and Cons of the Options
### <Option A>
- Good, because …
- Bad, because …

## More Information
Links, benchmarks, prototypes, related ADRs.

Common Pitfalls

Pitfall	Symptom	Mitigation
Retrofitting ADRs months later	Vague context, no alternatives	Write at decision time; allow short ADRs
Editing accepted ADRs	Audit trail lost	Supersede via new ADR; keep originals immutable
One-option ADRs	Rubber-stamp culture	Require >=2 alternatives + "do nothing"
ADRs in a wiki	Drifts from code	Co-locate in repo under docs/adr/
No index	Discoverability collapses	Auto-generate index in CI

Output Format

• One Markdown file per decision: docs/adr/NNNN-kebab-title.md.
• Auto-generated docs/adr/README.md index grouped by status.
• Cross-links from affected source files and service READMEs.

Authoritative References

• MADR 4.0 specification - https://adr.github.io
• Michael Nygard, "Documenting Architecture Decisions" (2011, canonical)
• ThoughtWorks Technology Radar Vol 31 (2026) - Lightweight ADRs (Adopt)
• Team Topologies, Skelton & Pais - stakeholder modes
• adr-tools v4 - https://github.com/npryce/adr-tools