Preview — full styling will appear after the next deploy completes.

bmad-method

Architecture Decision Records

Decisions that travel with the work

ADRs are the Architect persona's primary output. Each record captures a single design decision, the options considered, the rationale, and the consequences — making reasoning auditable and implementation predictable across sessions.

flowchart TD
    ADR[Architecture Decision Record]
    ADR --> DC[Decision<br>what was chosen]
    ADR --> CX[Context<br>why a decision was needed]
    ADR --> OP[Options Considered<br>what alternatives existed]
    ADR --> RT[Rationale<br>why this option was selected]
    ADR --> CN[Consequences<br>what becomes easier and harder]

An Architecture Decision Record (ADR) captures one design decision. Not a summary of all design decisions — one decision per record. The format is: the decision (what was chosen), the context (why a decision was needed), the options considered (what alternatives existed), the rationale (why this option was selected), and the consequences (what becomes easier and harder as a result). A record that cannot be read and understood in five minutes is too long.

ADRs solve the context problem that kills multi-session AI projects. When a developer opens a new session three days after the architecture was agreed, the AI has no memory of those decisions. Loading the ADR set restores the context: the technology choices, component boundaries, and trade-offs that were already made. The AI works within those decisions rather than reconsidering them from scratch.

The "minimum viable" discipline applies to ADRs as to the rest of BMAD. A BMAD architecture document does not try to capture every detail of the system. It captures the decisions that, if left implicit, would be made differently across AI sessions — causing incoherence across the implementation. Not everything needs a record. Patterns obvious from the existing codebase do not. Choices between equally reasonable alternatives do.