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.
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.
Key Concepts
- One decision per record — not a summary of all architectural choices
- ADRs restore AI context across sessions without re-explaining past decisions
- Minimum viable scope — only decisions that would otherwise diverge across sessions
- Consequences section makes trade-offs explicit and reviewable by the team
- ADR set is loaded at the start of every Developer session