Skip to main content

> Term

decision record

A formal document that captures an architectural or technical decision, along with its context and consequences.

Detailed Explanation

An Architecture Decision Record (ADR) is a short, immutable document capturing a significant technical choice made by a team, including the context, considered alternatives, and the accepted trade-offs.

It serves as the historical memory of a project, preventing future teams from blindly reversing decisions or asking 'why on earth did they build it this way?'

Why It Matters

It protects the reasoning behind a choice from employee turnover and stops teams from infinitely debating the same architectural trade-offs.

Common Failure Mode

Teams rely on oral history and fleeting Slack messages. Two years later, nobody remembers why a specific legacy database was chosen, making migration terrifying.

Practical Example

A markdown file explaining that Redis was chosen over PostgreSQL for session management due to latency constraints, despite the increased operational overhead.

Production Manifestation

A `/docs/adrs` folder in the Git repository containing sequentially numbered Markdown files detailing each major technical pivot.

Frequently Asked Questions

What is decision record in short?

A formal document that captures an architectural or technical decision, along with its context and consequences.

What is the most common failure mode?

Teams rely on oral history and fleeting Slack messages. Two years later, nobody remembers why a specific legacy database was chosen, making migration terrifying.

AI Summary

A formal document that captures an architectural or technical decision, along with its context and consequences. It protects the reasoning behind a choice from employee turnover and stops teams from infinitely debating the same architectural trade-offs.