O Que É ADR (Architecture Decision Record)? Documente Escolhas Técnicas

Quando um time técnico decide substituir um banco de dados relacional por uma solução colunar ou migrar uma aplicação inteira para uma arquitetura baseada em eventos, meses depois ninguém mais se lembra exatamente por que aquela escolha foi feita; é nesse cenário que entra o ADR (Architecture Decision Record).

O que é ADR (Architecture Decision Record)?

O ADR, ou Registro de Decisão Arquitetural, é um documento de texto curto e estruturado que captura uma decisão arquitetural significativa tomada em um projeto de software, juntamente com o contexto que motivou a mudança, as alternativas que foram descartadas e as consequências positivas e negativas decorrentes dessa escolha. Ele funciona como uma ata técnica imutável que registra a evolução estrutural da aplicação ao longo do tempo.

Estrutura e funcionamento de um Architecture Decision Record

A maioria dos times adota modelos padronizados e enxutos para escrever ADRs, mantendo-os em arquivos Markdown dentro do próprio repositório no Git. Uma estrutura típica de ADR inclui:

• Título e numeração: Um identificador sequencial curto que resume a escolha (ex.: "ADR 0012: Adoção do Kafka para mensageria de pedidos").
• Status: Indica se a decisão está proposta, aceita, rejeitada, substituída (deprecated) ou revogada por um novo registro.
• Contexto: Explica o problema de negócio ou desafio técnico encontrado, as forças em disputa (custo, desempenho, prazos, limitações da equipe) e o cenário no momento da análise.
• Decisão: Descreve detalhadamente a escolha adotada e o raciocínio aplicado para eleger essa solução.
• Consequências: Lista clara dos impactos operacionais, benefícios esperados e débitos assumidos com a decisão, evitando surpresas futuras.

Aplicação prática no cenário empresarial

Em empresas que passam por crescimento acelerado, aquisições de startups ou expansão de equipes, a rotatividade de desenvolvedores e arquitetos pode causar perda de histórico crítico. Uma grande rede de e-commerce brasileira, por exemplo, pode usar um ADR para formalizar a divisão de um sistema de checkout unificado em múltiplos microserviços independentes para suportar o pico da Black Friday.

Quando novos engenheiros entram na organização ou precisam planejar uma migração de sistema, a leitura dos ADRs históricos evita que discussões já resolvidas voltem à pauta e esclarece por que determinadas restrições foram implementadas originalmente.

ADRs versus ferramentas tradicionais de documentação

Enquanto a documentação de arquitetura tradicional costuma descrever o estado atual do sistema (como ele está desenhado hoje), o conjunto de ADRs conta a história de como o sistema chegou até ali. Eles operam em conjunto com ferramentas de controle de versão:

• Ao contrário de relatórios corporativos extensos em PDF, o ADR é conciso, focado em uma única questão e passa pelo mesmo fluxo de aprovação das alterações no código.
• Caso uma decisão se torne obsoleta devido ao avanço da tecnologia ou mudanças nas regras de negócio, o ADR antigo não é apagado; em vez disso, cria-se um novo registro que substitui formalmente o anterior.
• Essa transparência facilita a governança técnica e serve de subsídio para orientar processos de code review e auditorias de conformidade tecnológica.

Adotar ADRs é um passo decisivo para transformar conversas informais em memória técnica institucional, permitindo que a engenharia de software tome decisões maduras com total visibilidade sobre seu impacto no negócio.