O que é um ADR: a parte que importa é a alternativa que você descartou

Toda equipe técnica conhece esta cena. Alguém abre um arquivo, olha uma escolha estranha e pergunta: "por que isso está assim?". Ninguém sabe. Quem decidiu não está mais no projeto, ou está e não lembra. A discussão recomeça do zero, com as mesmas opções, os mesmos argumentos e o mesmo tempo gasto.

Seis meses depois, a mesma conversa acontece de novo.

O ADR existe para encerrar esse ciclo. E a parte dele que faz isso não é a decisão. É o que você decidiu não fazer.

O que é um ADR, em uma frase

ADR é a sigla de Architecture Decision Record, ou Registro de Decisão de Arquitetura. É um documento curto, um por decisão, que registra o contexto em que a escolha foi feita, o que foi escolhido, o que foi descartado e com qual motivo, e o que muda daqui para frente.

Repare no tamanho: um por decisão. ADR não é um documento grande que cresce. É um acervo de arquivos pequenos que se acumulam, cada um respondendo uma pergunta e só uma.

As 4 seções, e nada além delas

O formato clássico tem quatro partes. A tentação de acrescentar mais é grande e quase sempre piora o documento, porque ADR longo não é lido:

Quatro seções, meia página. Se o seu ADR passou de duas páginas, provavelmente ele está tentando ser uma especificação de implementação, que é outro documento.

A seção que paga o documento inteiro

De todas as quatro, a que evita mais retrabalho é Alternativas descartadas. E é justamente a que mais se pula.

Isso não é opinião. Auditamos o nosso próprio acervo de decisões antes de escrever este artigo: de 279 registros de decisão, apenas 57 têm a seção de alternativas descartadas preenchida. Vinte por cento. Nos outros 222, a escolha está registrada e o raciocínio que a produziu não está.

A consequência é previsível. Quando alguém pergunta "por que não usamos a opção B?", um registro com decisão e sem alternativas não responde. Ele só prova que a opção A foi escolhida, o que já era visível no código. A pergunta que custa tempo é sempre a negativa, e é ela que fica sem resposta.

Como escrever essa seção em uma linha por opção: nome da alternativa, seguido do motivo concreto da rejeição. Não "não era a melhor". Algo como "descartada: exige manter dois sistemas de checkout em paralelo" ou "descartada: o dono reportou que não funciona na prática".

Um motivo concreto tem uma propriedade valiosa: ele pode expirar. Se a alternativa caiu porque a biblioteca não existia, e um ano depois ela existe, o registro te avisa que a decisão vale ser revisitada. Um motivo vago nunca expira, e por isso nunca é reaberto.

Um ADR completo, do começo ao fim

Exemplo real, deste blog, escrito no formato de quatro seções:

Contexto. Dois artigos disputavam a mesma palavra-chave, um com 1.834 palavras e um com 324. O grafo de links internos estava partido: seis artigos apontavam para o curto, três para o longo, e os dois não linkavam um para o outro. O Google escolheria um dos dois, provavelmente o mais fraco, porque era o que recebia mais links.

Decisão. Manter os dois publicados, com papéis declarados e links bidirecionais. O curto passa a ser a nota doutrinária e aponta para o aprofundamento; o longo passa a ser a aplicação e aponta para a nota.

Alternativas descartadas.

• Redirecionar o curto para o longo (301). Descartada: o artigo curto é uma das 14 peças de um acervo em que cada peça cobre um conceito. Remover uma abre um buraco visível no cluster.
• Fundir os dois em um artigo só. Descartada: o curto atende uma intenção de busca diferente, de quem quer a definição rápida. Fundir entrega um texto longo para quem queria três parágrafos.
• Não fazer nada. Descartada: os dois continuariam competindo, e o mais fraco seguiria acumulando os links internos.

Consequência. As duas URLs continuam indexadas e passam a se reforçar. Em troca, existe agora uma obrigação nova: se o acervo de copy for reestruturado, essa hierarquia precisa ser revisitada junto, ou os links passam a apontar para um papel que não existe mais.

Note que a consequência declara um custo aceito, não só um ganho. ADR que só lista benefício não é registro de decisão, é comunicado.

ADR não se edita. Se supersede

Esta é a regra que mais gente quebra, e ela é o que separa um acervo de decisões de uma pasta de documentos desatualizados.

Quando uma decisão muda, você não volta no arquivo antigo e reescreve. Você escreve um registro novo, que referencia o anterior, e marca o antigo como superado. O motivo é direto: o valor do acervo está em mostrar como o pensamento evoluiu. Se você edita o passado, perde exatamente a informação que faria alguém entender por que o caminho mudou.

Na prática, isso significa uma pasta de arquivados. No nosso acervo são 30 registros superados, movidos para fora da pasta ativa mas preservados, não apagados. Quem quiser entender uma reviravolta consegue ler as duas versões em ordem.

É a mesma lógica de testar rápido e refinar depois: a decisão errada não é o problema. O problema é não ter registro de por que ela pareceu certa na hora.

O que um ADR não é

A diferença de tempo verbal resume tudo. O PRD e o SDD olham para frente e são substituídos quando a entrega acontece. O ADR olha para trás e nunca é substituído, só superado por outro ADR.

Por isso ADR também não é documentação de arquitetura. Documentação descreve o sistema como ele é hoje, e é atualizada. ADR descreve uma escolha no momento em que ela foi feita, e é congelada.

Quando não escrever um ADR

Registrar decisão demais é tão ruim quanto registrar de menos, porque um acervo cheio de trivialidade deixa de ser consultado. Não escreva ADR quando:

• A decisão é reversível em minutos e não deixa rastro. Nome de variável, ordem de campos numa tela.
• Não havia alternativa real. Se só existia um caminho, não houve decisão, houve constatação.
• A escolha já está documentada como padrão em outro lugar. Aponte para o padrão em vez de duplicá-lo.

A régua prática: escreva ADR quando a decisão é caro de reverter ou quando ela vai gerar a pergunta "por que não fizemos diferente?". Se nenhuma das duas se aplica, o registro é ruído.

Como começar hoje

Não precisa de ferramenta, template complexo ou aprovação. Precisa de uma pasta e de um hábito:

1. Crie uma pasta decisions/ no repositório ou no seu sistema de notas.
2. Nomeie cada arquivo com a data na frente: 2026-09-01-slug-da-decisao.md. A data ordena o acervo sozinha.
3. Escreva as quatro seções. Meia página. Se não couber, o escopo da decisão está grande demais e são duas decisões.
4. Na próxima decisão que gerar discussão, escreva antes de executar. Escrever expõe quando a escolha ainda não está madura.
5. Quando uma decisão cair, mova o arquivo para archive/ e escreva o registro novo referenciando o antigo.

O acervo vale mais que qualquer registro isolado

Nenhum ADR isolado justifica o esforço. Um arquivo de meia página explicando uma escolha antiga parece trivial no dia em que é escrito.

O valor aparece na escala. Um acervo com centenas de decisões, cada uma com o contexto e as alternativas que foram descartadas, é o que permite entender um sistema que ninguém consegue mais ter inteiro na cabeça. É a diferença entre um código que precisa ser arqueologicamente decifrado e um código cujas escolhas têm endereço.

Comece pela seção que quase todos pulam. Se você só escrever uma coisa em cada registro, escreva as alternativas que você descartou e por quê.

Este artigo fecha o trio de documentos que antecedem o código: o PRD trava o problema, o SDD trava a execução e o ADR guarda o porquê. Para as ferramentas que sustentam esse fluxo, o stack completo da eBuz tem as 31 peças agrupadas por função.