ADRs: como registrar decisões sem criar burocracia

Arquitetura é uma sequência de decisões. O diagrama mostra onde chegamos; o ADR explica por que escolhemos esse caminho e quais consequências aceitamos.

O que é um ADR

ADR é a sigla para Architecture Decision Record, ou Registro de Decisão Arquitetural. É um documento pequeno, normalmente escrito em Markdown e guardado junto da documentação ou do código.

Seu objetivo não é descrever o sistema inteiro. Ele registra uma decisão relevante: o contexto, as opções consideradas, a escolha e suas consequências. Uma coleção desses registros forma um histórico que ajuda pessoas novas, revisões técnicas e futuras mudanças.

Quando vale registrar

Nem toda escolha precisa de ADR. Use o registro quando a decisão:

• muda a estrutura do sistema ou a relação entre componentes;
• afeta segurança, disponibilidade, desempenho, custo ou operação;
• cria uma dependência difícil ou cara de reverter;
• define contratos, integrações, padrões ou tecnologias compartilhadas;
• teve alternativas razoáveis e pode voltar a ser discutida no futuro.

A escolha da cor de um botão não precisa de ADR. A decisão de processar pagamentos de forma síncrona, adotar um banco por serviço ou centralizar identidade provavelmente precisa.

Um modelo mínimo que cabe em uma página

Se o texto precisa de vinte páginas, talvez haja mais de uma decisão misturada. Separe os assuntos e conecte os registros por links.

Exemplo: comunicação entre pedido e estoque

Contexto

O fechamento do pedido chama o estoque diretamente. Em períodos de pico, uma lentidão no estoque interrompe vendas. O negócio aceita que a reserva seja confirmada alguns segundos depois, mas não aceita perder pedidos.

Opções

Manter a chamada síncrona com mais capacidade; usar uma fila gerenciada; ou gravar o pedido e executar uma rotina periódica.

Decisão

Publicar um evento em fila após persistir o pedido. O estoque processará a mensagem de forma idempotente, e a experiência mostrará o estado “confirmação em andamento”.

Consequências

A venda deixa de depender da resposta imediata do estoque e absorve melhor os picos. Em troca, a equipe passa a lidar com consistência eventual, mensagens repetidas, observabilidade da fila e tratamento explícito de falhas.

Esse exemplo não tenta provar que filas são sempre melhores. Ele deixa claro por que essa troca foi aceita para esse cenário.

Como adotar sem virar cerimônia

1. Comece com uma decisão real. Não tente documentar todo o passado.
2. Use um template curto. Contexto, opções, decisão e consequências são suficientes para começar.
3. Escreva antes da decisão fechar. O documento ajuda a organizar a conversa, não apenas a registrar o resultado.
4. Revise com as pessoas afetadas. Uma leitura assíncrona ou conversa de 15 minutos costuma bastar.
5. Não apague a história. Se a escolha mudar, crie um novo ADR e marque o anterior como substituído.