Architecture Decision Records

One file per decision: NNNN-kebab-case-title.md.

Per frontend-principal-engineering.md §42, every ADR must carry all seven fields. The last two are the ones most real-world ADRs skip, and they are the ones that separate a Principal-level record from a meeting summary.

Template

# NNNN — <Title>

- **Status:** proposed | accepted | superseded by NNNN | rejected
- **Date:** YYYY-MM-DD
- **Deciders:**
- **Module / context:**

## Context
What situation forces a decision now? What changed? Include evidence — numbers,
incidents, constraints — not opinions.

## Constraints
Technical, organizational, temporal, budgetary. Distinguish hard constraints from
preferences; most "constraints" are preferences wearing a costume.

## Options
At least three, each with an honest case *for* it. If an option has no honest case,
it is a strawman and does not count.

## Decision
What was chosen, and the single most important reason.

## Consequences
Positive and negative. Required: what gets *harder* as a result. An ADR with no
negative consequences has not been thought through.

## Reversibility
One-way or two-way door? What is the cost of reversing in 3 months? In 2 years?
What is the point of no return, and how will we know we passed it?

## Migration strategy
How do we get from current state to decided state incrementally? What is the
strangler seam? What happens if we stop halfway — is the intermediate state
survivable, or is it worse than both endpoints?

Index