An Architecture Decision Record documents the relevant context, chosen solution, and consequences in a short, discoverable record. Current and future contributors can understand the decision and reassess it when context changes.

1. 1

   Frame

   Clarify decision and context

   

   Goal

   The record explains why a decision is needed.

   Inputs for this step

   • Architecture question and current system context

   Actions

   • Formulate one concrete question. Capture requirements, constraints, affected areas and relevant earlier decisions.
   • Assign an ID and title. Record draft status, contributors and decision ownership.

   Output

   Decision context

   Question · significance · constraints · ownership

   Quality check

   Can a future reader understand the starting point?

   Pitfall

   The title names a technology but the decision question remains unclear. Describe the concrete decision need and its constraints.

   Timing: A short drafting block when context is known.

2. 2

   Compare

   Compare relevant options

   

   Goal

   The choice can be justified against its context.

   Inputs for this step

   • Decision context and realistic options

   Actions

   • Evaluate relevant options and their benefits and drawbacks against the concrete context. Include the current state when it is a realistic option.
   • Record decisive assumptions and sources. Plan a targeted investigation before choosing when uncertainty is material.

   Output

   Traceable trade-offs

   Option · relevant impact · uncertainty · source

   Quality check

   Are realistic options evaluated against the same context?

   Pitfall

   Unrealistic options are used to make the preferred choice look better. Document realistic alternatives and the differences that actually matter.

   Timing: Effort follows uncertainty; research or an experiment may require additional work.

3. 3

   Decide

   Review and record the decision

   

   Goal

   Status and decision ownership are traceable.

   Inputs for this step

   • Draft, trade-offs and affected perspectives

   Actions

   • Write a clear proposal with rationale and relevant favorable and unfavorable consequences. Assign open follow-up work.
   • Review through the agreed process. Record explicit acceptance, rejection or required revision, along with date and ownership.

   Output

   ADR with an explicit status

   Choice · rationale · consequences · status · date

   Quality check

   Is the decision explicitly confirmed and recorded? Are relevant consequences and open tasks understandable?

   Pitfall

   A draft is automatically accepted after a waiting period. Retain proposed status until the agreed decision is explicitly recorded.

   Timing: A draft takes roughly 15 to 45 minutes; arrange review and decision time additionally.

4. 4

   Maintain

   Follow consequences and preserve history

   

   Goal

   New decisions explain their relationship to earlier ones.

   Inputs for this step

   • ADR with explicit status and follow-up tasks

   Actions

   • Link the record to architecture, implementation and relevant evidence. Track open consequences in the appropriate work context.
   • When context changes, assess whether a new decision is needed. Create a new ADR, link its predecessor and mark it superseded; preserve the original rationale.

   Output

   Linked decision history

   Follow-up · trigger · predecessor · successor

   Quality check

   Can the earlier rationale and current status be found?

   Pitfall

   The old decision is retroactively rewritten to match the new solution. Document a new decision with a backlink and preserve the earlier record.

   Timing: Brief maintenance when relevant changes occur; no universal review cadence is required.