writing-adrs

An ADR (Architecture Decision Record) is a structured document capturing significant architectural choices, their context, rationale, and consequences. ADRs create a searchable history of why frameworks, databases, API patterns, and infrastructure decisions were made, helping teams understand trade-offs and avoid revisiting settled choices.

Create an ADR with six sections: Title, Status, Context (the problem), Decision (what you chose), Rationale (why), and Consequences (impacts). Assign sequential numbers (ADR-001, ADR-002), document alternatives considered, and maintain current status as decisions evolve or are superseded.

Document decisions about frameworks, libraries, databases, API patterns, coding conventions, and infrastructure across multiple components. ADRs work best for choices that significantly affect system design, have trade-offs worth recording, or influence future development.

Use sequential numbering to track decisions chronologically, update Status fields as circumstances change, and include references to related ADRs. Store ADRs in version control alongside code so they evolve with the codebase and remain discoverable.

Yes. ADRs apply to any significant architectural decision including coding standards, infrastructure choices, deployment patterns, and library selections—anything that affects multiple components or constrains future development.