ADR

Architecture Decision Records That Stay Useful

Software systems accumulate decisions that are obvious at the time and mysterious six months later. A database was chosen for a reason, a synchronous call became asynchronous for a reason, and a service boundary exists because some trade-off mattered. Architecture Decision Records, or ADRs, preserve that reasoning in small documents close to the code. Record decisions, not meetings An ADR should answer a future engineer’s practical questions: What problem were we solving? What constraints mattered? What did we decide? Which alternatives were considered? What consequences did we accept? Has this decision been replaced? It does not need to reproduce a design meeting transcript.