ADR foi formalizado por Michael Nygard em 2011 (post canônico
em cognitect.com). Diferente de RFC (que é proposta a
decidir), ADR é registro de decisão tomada — para que daqui a
2 anos, alguém entenda por que escolheu Postgres ao
invés de DynamoDB, e em qual contexto. Times maduros guardam
ADRs no repo (docs/adr/0001-*.md) versionados
junto com o código. ADRs antigos não somem; ficam como
arqueologia útil — quando alguém propõe mudar uma decisão, o
ADR original é o ponto de partida da conversa.
Template
# ADR-NNN: [Título curto: decisão tomada]
- **Status:** Proposed / Accepted / Deprecated / Superseded by ADR-XXX
- **Date:** [YYYY-MM-DD]
- **Deciders:** [@person1, @person2]
- **Tags:** [arquitetura, banco, infra, security, ...]
## Contexto
[Que problema ou pergunta motivou esta decisão? Qual a situação
atual? Que forças/restrições existem?]
[2-4 parágrafos. Foco em fatos: o que é verdade hoje, o que
precisa mudar.]
## Decisão
[A decisão tomada, em frase ativa: "Vamos usar X porque Y".]
[1-2 parágrafos detalhando a decisão concreta. O que vai ser
feito, com qual configuração se relevante.]
## Consequências
### Positivas
- [Benefício 1 — ex: latência cross-region reduzida em X%]
- [Benefício 2]
### Negativas / trade-offs aceitos
- [Custo 1 — ex: complexidade operacional aumenta com novo
componente]
- [Custo 2]
### Neutras / observações
- [Coisas que vão mudar mas não são positivas/negativas claras]
## Alternativas consideradas
- **Opção B:** [breve descrição] — rejeitada porque [motivo]
- **Opção C:** [breve descrição] — rejeitada porque [motivo]
## Referências
- [Links para benchmarks que sustentam a decisão]
- [RFC relacionado, se houver]
- [Tickets/issues de contexto]
Diferença entre RFC e ADR: RFC é a discussão; ADR é o registro. RFC pode ser rejeitado, descartado, ressuscitado. ADR é imutável (status muda para "Superseded by ADR-XXX", mas o texto original permanece). Times maduros geram um ADR para cada RFC aprovado, capturando a decisão final em formato curto e estável.
Referências
- Michael Nygard — Documenting Architecture Decisions (2011)
- joelparkerhenderson/architecture-decision-record (templates)
- adr.github.io — Architectural Decision Records community
- Michael Nygard, Release It! (Pragmatic Bookshelf, 2018) — capítulo de design records