ADRs: por que documentar decisões de arquitetura (e como começar hoje)

Em times que crescem rápido, a pergunta “por que fizemos assim?” aparece com a mesma frequência que “quando isso vai estar pronto?”. Sem registo claro, cada novo arquiteto ou PM reinventa o passado — e o custo aparece em retrabalho, incidentes e discussões que não terminam.

Os Architecture Decision Records (ADRs) são registos curtos que capturam contexto, decisão e consequências de escolhas estruturais. Não substituem diagramas nem código; ancoram a memória institucional onde ela mais falha: nas decisões que pareciam óbvias na época.

O que um ADR resolve (e o que não resolve)

Resolve: alinhar liderança técnica e produto sobre por que um caminho foi escolhido; facilitar onboarding; reduzir debates circulares quando o contexto muda.

Não resolve sozinho: má implementação, falta de testes ou ausência de ownership. ADR sem disciplina de revisão vira arquivo morto.

Estrutura mínima que funciona

1. Título — identificável (ex.: “Uso de fila para pedidos críticos”).

2. Status — proposto, aceite, substituído.

3. Contexto — pressão de negócio, restrições, o que estava em jogo.

4. Decisão — o que foi escolhido, em uma frase clara.

5. Consequências — trade-offs, riscos aceites, o que monitorizar.

Quanto mais curto e específico, maior a probabilidade de ser lido e atualizado.

---

Em síntese: ADRs são registos curtos que ligam decisões de arquitetura ao contexto de negócio — úteis para onboarding, auditorias e para não repetir debates já resolvidos.