Architecture Decision Record (ADR) Template

Record decisions that affect system boundaries, data models, API contracts, infrastructure, or cross-team interfaces. A good test: if reversing this decision would take more than a sprint, it is worth recording. Examples: choosing a database, defining an API protocol, selecting a message queue, deciding on a deployment strategy, or establishing a cross-service communication pattern. The [decision log template](/templates/decision-log-template) is better suited for lighter-weight product or process decisions that do not involve architecture.

A healthy team produces 1-3 ADRs per quarter. If you are writing 10+ ADRs per quarter, you are either over-documenting or making too many architecture changes. If you are writing zero, you are either making no significant decisions (unlikely) or not recording them (common and costly).

The engineer who understands the technical trade-offs best should write the ADR. The PM should review it to confirm the decision aligns with product requirements, timelines, and priorities. The PM's role is to ensure the decision drivers include business context (time-to-market, cost, customer impact), not just technical criteria.

Yes. Mark the original ADR as "Superseded by ADR-NNN" and write a new ADR that documents why the original decision is being reversed and what the new decision is. Do not edit or delete the original. The history of decisions is valuable, including the ones that turned out to be wrong.

In your code repository alongside the code they affect. A `/docs/adrs/` directory with sequentially numbered markdown files is the most common pattern. This ensures ADRs are versioned with the code, searchable via `grep`, and discoverable by new team members during onboarding. Avoid storing ADRs in a wiki unless your team's wiki is the actual source of truth for engineering documentation. ---