architecture-decision

To document architectural decisions, you identify load-bearing choices regarding stack, module boundaries, and API contracts, then record the rationale in ADRs. This process outputs an architecture.md file and individual ADR markdown documents to guide implementation.

An Architecture Decision Record (ADR) is a document capturing non-obvious, load-bearing system choices and their rationale. You need an ADR during backlog refinement or architectural planning when deciding reversible versus irreversible decisions to prevent costly downstream coding errors.

To define frontend and backend API contracts for parallel implementation, you document the data model and system boundaries early. This establishes a clear agreement that enables implementers to work concurrently without waiting for dependent modules to be fully built.

Before making system architecture decisions, you need a backlog or a clear statement of goals and constraints. This input allows you to perform a simpler-alternative pass, evaluate stack options, and define module boundaries before drafting the final architecture documentation.

A limitation of deciding system architecture during backlog refinement is that it strictly requires clear goals and constraints upfront. Without a defined backlog, the architectural planning process cannot accurately identify load-bearing decisions or output valid ADRs to guide developers.