Key decisions are recorded
At least one architecture decision is written down and accepted, with its context and consequences.
LowChecked automatically
- Applies to:
- Every service
- Rule id:
- decisions.accepted-adr
Why it matters
Six months on, nobody remembers why the service uses events instead of a direct call, and the next engineer either undoes a deliberate choice or is afraid to touch it. A short record of the decision, and of what was given up, is the cheapest documentation there is.
How to apply it
- Record decisions that are costly to reverse: the data store, sync or async integration, a consistency trade-off, a pattern such as a saga.
- One decision per record: context, the decision, the consequences, including the bad ones.
- Mark it accepted when the team agrees. Supersede it with a new record rather than editing it.
- A rule marked not applicable on this service is a decision too: link the record.
Example
"ADR-003, accepted: stock is reserved through a saga instead of a distributed transaction. Consequence: an order can be briefly accepted and then rejected, so the UI shows 'confirming'."
References
Checklists with this rule
Related agent skill: writing-adrs