An architecture decision record is one file per non-default decision, numbered, in docs/adr/, committed with the change it describes. It exists so the next person can tell "we thought about this and chose X" from "nobody thought about this".
Write one when the decision is hard to reverse, costs money or time to change, or will surprise someone reading the code. Do not write one for choices that match section 1 of the skill — the defaults are the record.
Template
# ADR-<nnn>: <decision in five words, stated as the choice made>
- **Status:** Proposed | Accepted | Superseded by ADR-<nnn>
- **Date:** YYYY-MM-DD
- **Deciders:** <names or team>
## Context
What forces us to decide now: the requirement, the constraint, the pain. Two or three sentences,
no solution language. Include the numbers that matter (users, rows, teams, latency budget).
## Options considered
| Option | Pro | Con |
|---|---|---|
| A | | |
| B | | |
## Decision
We will <choice>, because <the one reason that outweighs the rest>.
## Consequences
- What becomes easier.
- What becomes harder, and what we accept because of it.
- What this commits us to (a dependency, a build step, an on-call surface).
## Revisit when
A concrete, observable trigger — not "in six months".
Filled example
# ADR-004: NgRx SignalStore for order management, plain signals elsewhere
- **Status:** Accepted
- **Date:** 2026-09-14
- **Deciders:** Orders team, frontend guild
## Context
The orders feature holds ~4 000 entities client side, has six async operations (load, filter,
bulk assign, bulk cancel, export, live status push) and is read by four routes plus the header
badge. The rest of the app is CRUD forms with one consumer each. The team has asked whether to
adopt NgRx Store app-wide "so everything is consistent".
## Options considered
| Option | Pro | Con |
|---|---|---|
| Plain signal services everywhere | No dependency, least ceremony | Orders needs entity maps, request cancellation and shared derived state that we would hand-roll |
| NgRx SignalStore for orders only | Entity helpers, `rxMethod` cancellation, DI-scoped to the route | Two state idioms in one codebase |
| NgRx Store app-wide | One idiom, devtools time travel | Actions/reducers/effects for 20 single-consumer forms; measured ~3x the code for the CRUD screens |
## Decision
We will use NgRx SignalStore (`withEntities`, `rxMethod`) for the orders feature, provided on the
orders route, and keep plain signal services everywhere else, because the cost of the second idiom
is one paragraph in ARCHITECTURE.md while the cost of Store app-wide is paid in every CRUD screen.
## Consequences
- Easier: order list filtering, cancellation of stale loads and the live-status merge are library
features instead of our code.
- Harder: new joiners meet two patterns. Mitigated by the rule "SignalStore only where the folder
already has one" and a linked example in the onboarding doc.
- Commits us to `@ngrx/signals`, which must be upgraded with each Angular major.
- No devtools time travel for orders; we accept this, as no one has asked for it in 18 months.
## Revisit when
A second feature needs entity management and async cancellation — at that point either promote
SignalStore to the default, or extract the shared pieces into `shared/util`.
Where the ADRs live
docs/adr/0004-signalstore-for-orders.md, with docs/adr/README.md listing them in order with their status. ARCHITECTURE.md stays short and links the ADRs; it describes what is true today, the ADRs describe why.
Never edit an accepted ADR to change the decision. Write a new one and set the old one to Superseded by ADR-<nnn> — the history is most of the value.