ADRs — Architecture Decision Records
Decisão registrada. Contexto preservado. Advice Forum em vez de Ivory Tower.
Por que ADR existe: 6 meses depois ninguém lembra por que aquela escolha foi feita. Sem ADR, o novo dev "melhora" o sistema desfazendo decisão antiga (que tinha razão válida). Com ADR, decisão fica auditável e o "porquê" sobrevive a rotatividade.
O que vai num ADR
- Contexto — qual problema obrigou essa decisão? Que pressão existia?
- Opções consideradas — pelo menos 2-3 alternativas reais
- Decisão — o que foi escolhido
- Consequências — o que muda, bom e ruim. Trade-offs aceitos.
ADR sem "opções consideradas" geralmente é racionalização pós-fato — não é decisão, é registro. Listar 2-3 opções obriga a pensar de verdade.
O que ADR não é
- Não é documentação geral do sistema (use README + diagrams)
- Não é tutorial nem post mortem (são documentos separados)
- Não é instrumento de aprovação top-down (veja Advice Forum)
- Não é eterno — pode ser superseded por outro ADR
Quando criar um ADR
| Crie ADR para | Não crie para |
|---|---|
| Escolha de banco (Postgres vs Mongo) | Renomear uma classe |
| Pattern de comunicação (sync REST vs async events) | Subir versão de patch |
| Auth strategy (JWT vs session) | Decisão de formato de log único |
| Estrutura de monorepo vs polyrepo | Estilo de código (já cabe no linter) |
| Política de versionamento de API | Cor do botão |
Regra prática: se a decisão vai doer reverter em 6 meses, registre. Se for trivial reverter, não polua o log.
Por que escrever um ADR em vez de só decidir e mover?
Três razões. (1) Memória organizacional: 6-12 meses depois, ninguém lembra o porquê — sem ADR alguém vai "consertar" o que era decisão intencional. (2) Onboarding: novo dev lê 15 ADRs e entende como o sistema chegou onde chegou — vale dias de pareamento. (3) Pensamento forçado: o ato de listar opções e consequências obriga você a pensar em alternativas que você não tinha visto. ADRs bons são curtos (1-2 páginas), não burocráticos.