O que é um ADR?
ADR (Architecture Decision Record) é um documento curto — geralmente uma página em Markdown — que registra uma decisão arquitetural significativa: o contexto que motivou, as alternativas consideradas, a escolha feita e as consequências esperadas. O termo foi popularizado por Michael Nygard em 2011 e virou padrão de facto na engenharia moderna.
A regra é simples: ADRs são imutáveis. Uma vez aceito, um ADR não é editado. Se a decisão muda, você escreve um novo ADR que supersedes (substitui) o anterior. Isso preserva a linha do tempo — você consegue ler, na ordem, como o sistema chegou onde chegou.
Quando escrever um ADR?
Toda decisão que satisfaça pelo menos um destes critérios merece um ADR:
- É cara de reverter (escolha de banco, linguagem, cloud, protocolo).
- Afeta múltiplos times ou serviços.
- Contradiz uma convenção anterior.
- Foi discutida por mais de uma reunião — se gerou debate, merece registro.
Escolha de nome de variável não é ADR. Escolha entre Postgres e MongoDB é. Adotar arquitetura hexagonal é. Trocar REST por gRPC é. Se em 6 meses um dev novo perguntar "por quê?", você quer ter um ADR pra apontar.
Template MADR (recomendado)
O MADR (Markdown Architectural Decision Records) é hoje o template mais adotado. Substitui o Nygard original com uma estrutura mais rica sem ficar burocrática:
# ADR-0007: Adotar PostgreSQL como banco primário
* Status: Aceito
* Data: 2026-03-14
* Deciders: @cto, @tech-lead-backend, @sre-lead
## Contexto e problema
Precisamos escolher o banco relacional que sustentará o produto pelos
próximos 3 anos. Volume esperado: 50M linhas na maior tabela até 2028.
Requisitos: transações ACID, JSONB para atributos flexíveis, replicação
lógica para analytics e ecossistema maduro.
## Alternativas consideradas
* PostgreSQL
* MySQL 8
* CockroachDB
* MongoDB (rejeitado cedo — sem ACID cross-document na versão gratuita)
## Decisão
Adotamos **PostgreSQL 16** na versão gerenciada da AWS (RDS Multi-AZ).
## Consequências
### Positivas
* JSONB elimina 80% dos casos que exigiriam um segundo banco.
* Replicação lógica destrava CDC para o data warehouse sem tooling extra.
* Ecossistema pgvector nos deixa fazer busca semântica sem infra nova.
### Negativas
* Escala horizontal exige sharding manual acima de ~10TB.
* Time precisa aprender pg_stat_statements e VACUUM tuning.
## Superseded by
—Onde armazenar os ADRs
No repositório do código. Não em Confluence, não em Notion, não em Google Docs. A regra é: se o código mudar de casa, os ADRs vão junto. O padrão da indústria é uma pasta docs/adr/ ou architecture/decisions/ na raiz do repo, com arquivos numerados sequencialmente (0001-titulo.md, 0002-titulo.md).
Isso garante três coisas: revisão via pull request (arquitetura passa a ter code review), histórico via git log, e visibilidade — qualquer dev que clona o repo enxerga as decisões junto com o código que elas justificam.
Estados de um ADR
- Proposed — em discussão, ainda não implementado.
- Accepted — decisão vigente, código em produção reflete o ADR.
- Deprecated — não use mais, mas ainda há código legado nesse padrão.
- Superseded by ADR-XXXX — trocado por uma decisão mais nova.
ADR + diagrama como código: a dupla que documenta arquitetura viva
ADR responde por que. Diagrama responde como. Juntos, eles são o mínimo viável para documentação de arquitetura que não apodrece. Um ADR sem diagrama força o leitor a imaginar; um diagrama sem ADR envelhece sem contexto. Se você segue C4 Model e versiona os diagramas como código junto com os ADRs, o próximo dev que entrar tem tudo que precisa em um único git clone.
Erros comuns
- Escrever depois. ADR feito 3 meses após a decisão vira ficção — ninguém lembra das alternativas descartadas. Escreva enquanto a discussão está fresca.
- Editar ADR aceito. Se mudou de ideia, escreva um novo. Editar apaga a história e quebra a promessa da imutabilidade.
- ADR épico. Se passou de 2 páginas, você está escrevendo um RFC, não um ADR. Quebre em decisões menores.
- Ignorar consequências negativas. A seção mais valiosa é a de trade-offs. Sem ela, o próximo time vai bater na mesma parede.