Architecture Decision Records

Overview

Document why you chose one approach over another. Future you (and future Claude sessions) need this context.

Core principle: Decisions without documented reasoning get relitigated endlessly. Write it down once.

When to Use

• Choosing a framework, library, or tool
• Deciding on architecture patterns (monolith vs microservice, sync vs async)
• Making trade-offs (consistency vs availability, simplicity vs flexibility)
• Changing an existing decision
• Any decision someone might ask "why did we do it this way?"

ADR Format