Decision records
A decision record keeps one architecture decision, the reasons for it, and what it costs. Read the records before you propose a design that reverses one.
Each record is a file NNNN-short-name.md in docs/adr/. The number counts from 0001 and never repeats. A record that a later decision replaces keeps its file, and its status names the record that replaces it.
A record has these sections:
- Status: Proposed, Accepted, or Superseded by a later record. A record that a later record clarifies keeps its decision, and its status names that record.
- Context: the problem, and the facts that force a decision.
- Decision: what we do, in one or two sentences, then the rule in detail.
- Rejected options: the options we did not choose, and why.
- Consequences: what gets better, what gets worse, and what to watch.
Architectural priorities ranks correctness, simplicity, performance and shipping speed. A record applies that ranking to one recurring question.