Generate an Architecture
Decision Record

What is an Architecture Decision Record?

An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision, including the context, the decision itself, the alternatives considered, and the consequences.

Why Write ADRs?

• Institutional memory — New team members can understand WHY decisions were made, not just what was built
• Prevent rehashing — When someone asks "why didn't we use MongoDB?", point them to the ADR
• Track evolution — Your architecture evolves. ADRs document that evolution as a decision log
• Better decisions — The act of writing forces you to think through alternatives and consequences

When to Write an ADR

• Choosing a database, framework, or major library
• Deciding on an architectural pattern (monolith vs. microservices, REST vs. GraphQL)
• Changing deployment infrastructure
• Adopting or dropping a significant tool
• Any decision that a future developer would ask "why did we do this?"

ADR File Organization

docs/adr/
├── ADR-001-use-postgresql.md
├── ADR-002-adopt-nextjs-app-router.md
├── ADR-003-stripe-for-payments.md
├── ADR-004-switch-to-turborepo.md
└── README.md (index of all ADRs)