Architecture Decision Record
By Spencer Garcia · Published · Updated
Records one technical decision with its context, the options weighed, the choice and its consequences, in a form a newcomer can understand a year from now.
Prompt template
## Architecture Decision Record
Write an ADR for this decision.
- Decision title: [text: A short noun phrase such as Use Postgres for events]
- Context: [textarea: The problem and the forces at play]
- Options considered: [textarea: Each option with the main point for and against]
- Chosen option: [text: What was picked]
- Reason for choosing it: [textarea: The deciding factors]
- Status: [dropdown: Proposed, Accepted, Superseded, Deprecated]
- Decision makers: [text: Names or roles]
Write for a reader who joins in a year and has none of today's context. State the context first: the situation, the constraints, the scale and the deadline, without hinting at the answer. Present each option fairly in two or three lines, including the ones you rejected, with the cost of each. State the decision in one active sentence ("We will use ..."), then explain the deciding reasons in order of weight. Spell out the consequences honestly: what becomes easier, what becomes harder, what new risks or work follow, and what would make the team revisit this choice. Keep it to one page, avoid jargon without a definition, and add the date, status and links to related records so the history can be followed.