Todo time já viveu esta cena. Alguém novo olha a arquitetura e pergunta: “por que a gente usa isso aqui?”. A resposta é um silêncio, seguido de “acho que foi o fulano que decidiu, ele já saiu”.

O diagrama mostra a estrutura de hoje. Ele quase nunca explica por que ela é assim, que alternativas foram descartadas e que preço o time aceitou pagar. Quando esse conhecimento vive só na cabeça das pessoas, cada mudança vira arqueologia.

O que é um ADR

Um Registro de Decisão Arquitetural (ADR, do inglês Architecture Decision Record) é um documento curto que guarda uma decisão importante com seu contexto, as alternativas consideradas e as consequências. Ele é versionado junto do código ou da documentação da arquitetura, e cada decisão ganha o seu.

Arquitetura, nessa visão, não é o desenho que mostra onde cada tecnologia está. É o conjunto de decisões que protege o sistema contra os riscos que realmente importam. O ADR é a forma de deixar essas decisões visíveis.

Quando vale escrever um

Nem toda escolha merece um ADR. Trocar uma biblioteca fácil de substituir tem impacto bem diferente de definir o modelo de autorização ou dividir dados entre serviços. Uma regra prática: quanto maior o custo de voltar atrás e o impacto sobre a qualidade do sistema, mais cedo a decisão precisa ser registrada.

Candidatas típicas:

• construir, comprar, adaptar ou integrar uma plataforma;
• monólito modular ou microsserviços;
• comunicação síncrona ou assíncrona;
• consistência imediata ou eventual;
• banco compartilhado ou dados com dono por serviço;
• estratégia de autorização e de auditoria.

O modelo

Cinco seções bastam. Mais que isso, ninguém mantém.

A seção de Validade é a mais esquecida e uma das mais úteis. Ela diz em que condições a decisão deixa de fazer sentido, e evita que o time defenda uma escolha depois que o contexto mudou.

Um exemplo real

O caso abaixo foi adaptado de uma plataforma de eventos em tempo real (nomes e detalhes sensíveis foram generalizados). Ela recebia eventos de centenas de origens, sem padrão de formato nem de frequência, e processava cerca de 600 mensagens por segundo com serviços gerenciados do Azure: Event Hubs na ingestão, Stream Analytics no processamento e Functions nas etapas seguintes.

Resumido em formato de ADR:

ADR 007: Ingestão com Kafka e processamento com Flink, mantendo o SQL Server

Contexto. O volume cresceu e o encadeamento de serviços gerenciados passou a gerar custo alto e pouco previsível. Ficou difícil saber quanto custava cada evento processado. A organização já tinha infraestrutura, processos e conhecimento consolidados em SQL Server.

Decisão. Reestruturar a ingestão com Apache Kafka e o processamento contínuo com Apache Flink. Manter o SQL Server na persistência. Os eventos passam a carregar um link para a imagem, e não a imagem inteira em Base64.

Alternativas. Continuar com os serviços gerenciados, aceitando o custo. Trocar também o banco, o que aumentaria a superfície operacional sem benefício proporcional naquele contexto.

Consequências. Mais controle sobre capacidade e custo, com particionamento e paralelismo ajustados à carga real. Em troca, o time passa a responder por brokers, replicação, atraso de consumo, checkpoints e evolução de esquemas. O SQL Server precisa receber gravações de forma controlada para não virar o novo gargalo.

Validade. Revisar se o custo de operação assumido pelo time superar a economia, ou se o perfil de carga mudar de forma relevante.

Repare em duas coisas. Primeiro, o ADR não diz que Kafka é melhor que Event Hubs nem que SQL Server é o banco ideal para eventos. Diz por que aquela combinação fazia sentido naquele contexto. Segundo, ele registra o preço: o ganho financeiro não eliminou custos, transferiu parte deles para a operação e para o conhecimento do time.

Erros comuns com ADRs

• Escrever depois que todo mundo já esqueceu as alternativas.
• Registrar só a decisão, sem o contexto que a justificava.
• Listar apenas benefícios, como se a escolha não tivesse custo.
• Guardar em uma wiki que ninguém abre, longe do código.
• Editar o ADR antigo em vez de criar um novo que o substitui.

Para ir além

O capítulo 7 do livro Engenharia de Software: Fundamentos e Práticas trata a arquitetura como conjunto de decisões: drivers e cenários de qualidade, trade-offs, monólito modular contra microsserviços, Outbox e idempotência, FinOps e o caso completo dessa plataforma de eventos, com a tabela de antes e depois.

Veja o sumário e leia o começo do livro.