# ADR format

ADRs live in `docs/adr/`, numbered sequentially: `0001-slug.md`, `0002-slug.md`. Scan the directory
for the highest existing number and increment. Create `docs/adr/` lazily, only when the first ADR is
needed.

## Template

```md
# {Short title of the decision}

{One to three sentences: the context, what was decided, and why.}
```

That is the whole template. An ADR can be a single paragraph. The value is in recording *that* a
decision was made and *why*, not in filling out sections.

## Optional sections

Include these only where they add something. Most ADRs need none of them.

- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful once
  decisions start getting revisited.
- **Considered options**: only where the rejected alternatives are worth remembering.
- **Consequences**: only where a non-obvious downstream effect needs calling out.

## When an ADR is warranted

All three must hold:

1. **Hard to reverse.** An easy decision to reverse does not need a record; it will simply be
   reversed.
2. **Surprising without context.** If nobody would wonder why, nothing needs explaining.
3. **The result of a real trade-off.** With no genuine alternative there is nothing to record beyond
   "we did the obvious thing."

### What qualifies

- **Architectural shape.** "The write model is event-sourced; the read model is projected."
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not
  synchronous HTTP."
- **Technology choices carrying lock-in.** Database, message bus, auth provider, deployment target.
  Not every library: the ones that would take a quarter to swap.
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; others reference
  it by ID only." The explicit noes are as valuable as the yeses.
- **Deliberate deviations from the obvious path.** "Manual SQL instead of an ORM, because X."
  Anything a reasonable reader would assume the opposite of. These stop the next engineer from
  "fixing" something deliberate.
- **Constraints invisible in the code.** "Response times must stay under 200ms because of the partner
  API contract."
- **Rejected alternatives where the rejection is non-obvious.** Picking REST over GraphQL for subtle
  reasons earns a record, or someone proposes GraphQL again in six months.