Por Que ADRs Importam
Visão Geral
O argumento óbvio para ADRs — "para não esquecer por que decidimos" — é verdadeiro e é o menos interessante.
Os efeitos que mais compensam são outros três, e nenhum depende de alguém ler o ADR depois:
escrever muda a decisão forçar a justificativa expõe raciocínio frágil
o desacordo ganha um lugar discordar de um documento é diferente de discordar de uma pessoa
a decisão vira contestável com alternativas registradas, revisar é barato
O quarto efeito — não redescobrir a razão anos depois — é real e é bônus.
O Problema
Organizações perdem contexto continuamente, e a perda não aparece como evento:
uma pessoa sai o contexto que ela tinha sai junto
seis meses passam quem ficou lembra o quê, não o porquê
o sistema cresce decisões antigas viram restrições sem explicação
o time troca a memória institucional zera a cada rotação completa
A consequência composta é uma organização que não consegue revisar suas próprias decisões. Cada uma vira permanente por padrão — não porque esteja certa, mas porque ninguém sabe o suficiente para questioná-la.
E há o oposto, igualmente caro: decisões revisitadas repetidamente porque nada registra que já foram tomadas. A mesma discussão de escolha de banco de dados acontece três vezes em cinco anos, com as mesmas conclusões e o mesmo custo.
Conceitos Centrais
Erosão de contexto
O contexto de uma decisão se degrada em ritmo previsível:
no momento todos os envolvidos sabem
3 meses quem participou lembra o essencial
1 ano lembra que decidiu, não por quê
2 anos a maior parte dos envolvidos saiu ou esqueceu
5 anos a decisão é folclore — "sempre foi assim"
A última fase é a perigosa. Uma decisão que virou folclore é obedecida sem crítica e propagada para sistemas novos, muito depois de a razão ter deixado de existir.
O ADR não impede a erosão da memória. Ele torna a memória recuperável.
Escrever muda a decisão
O efeito mais subestimado: uma parcela relevante das decisões muda durante a redação do ADR.
ao escrever o contexto percebe-se que a restrição citada já não vale
ao listar alternativas percebe-se que a descartada é melhor
ao escrever consequências percebe-se que o custo não foi considerado
ao tentar justificar percebe-se que a razão era hábito
Isso significa que o ADR se paga antes de ser lido por alguém. É o argumento mais forte para escrever cedo — durante a decisão, não depois dela.
Ver alternativas, que é a seção onde esse efeito se concentra.
O desacordo ganha um lugar
Sem registro, discordar de uma decisão arquitetural é um ato social: significa contestar quem a tomou, num canal informal, sem base comum.
Com registro, a discordância tem endereço:
"o contexto mudou — a restrição do ADR-014 não vale mais"
"a alternativa B foi descartada por um motivo que hoje não se aplica"
"a consequência prevista não se materializou"
Isso despersonaliza o debate técnico, e é especialmente valioso para quem tem menos antiguidade: um argumento contra um documento é aceitável de qualquer pessoa; um argumento contra a decisão de alguém sênior depende de capital político.
Decisões passam a ter validade
Um ADR bem escrito registra as condições sob as quais a decisão vale. Isso transforma decisões permanentes em decisões condicionais:
"escolhemos o monólito porque somos 12 pessoas e um domínio"
→ quando formos 40 pessoas e três domínios, reavaliar
A revisão deixa de exigir coragem e passa a exigir só observação. Ver superação, onde essa mecânica é o tema.
Integração de pessoas fica mais barata
Quem chega recebe diagramas do que existe e, com ADRs, também o raciocínio.
A diferença prática é entre "este é o sistema, aceite" e "este é o sistema, e estas foram as escolhas" — a segunda produz alguém capaz de contribuir com julgamento, não só com execução.
E há um efeito de calibração: dez ADRs bem escritos expõem o raciocínio daquela organização — com as restrições reais dela — que nenhum material genérico carrega.
O que ADRs não resolvem
Vale delimitar, porque a promessa exagerada é a principal causa de abandono da prática:
não melhoram decisões ruins registram-nas melhor
não substituem conversa registram o desfecho dela
não garantem alinhamento um ADR ignorado continua ignorado
não documentam o sistema são histórico, não estado
não resolvem falta de tempo se ninguém tem 30 minutos, o problema é outro
Por Que Isso Importa
Porque o custo da ausência é invisível e contínuo. Ele não aparece em nenhum orçamento — aparece como lentidão, retrabalho e incidentes cuja causa é "ninguém sabia".
Porque decisões não revisáveis viram dívida. Uma restrição sem razão conhecida continua sendo respeitada indefinidamente. Sistemas acumulam essas restrições até que uma parte significativa do desenho seja resposta a condições que já não existem.
Porque o benefício não depende de leitura. O efeito de escrever — expor raciocínio frágil — acontece mesmo que o documento nunca seja aberto.
Porque melhora a qualidade do debate. Argumentos contra documentos são mais honestos e mais acessíveis que argumentos contra pessoas.
Porque o retorno é assimétrico. A maior parte dos ADRs não será lida; os poucos que forem, serão lidos no momento em que alguém está prestes a errar de forma cara.
Erros Comuns
Vender como documentação. Isso leva à expectativa de manutenção e à decepção.
Prometer que serão lidos. A maior parte não será, e tudo bem — o argumento não é esse.
Impor por processo. ADR obrigatório com aprovação vira teatro; a prática funciona quando é barata e voluntária.
Escrever depois da implementação. Perde-se o efeito de "escrever muda a decisão", que é o principal.
Registrar só sucessos. Um conjunto de ADRs em que nenhuma decisão deu errado não é confiável.
Deixar sem alternativas. Sem elas, o ADR é uma declaração, e não sustenta contestação.
Exemplo Real
Uma empresa de logística com 90 engenheiros mediu, por curiosidade, quanto custava não ter registro de decisão. O método foi rastrear, durante um trimestre, toda discussão arquitetural que já tivesse acontecido antes.
O levantamento encontrou:
discussões repetidas identificadas 17
horas-pessoa gastas nelas ~310
decisões que chegaram à mesma conclusão 13
que chegaram a conclusão diferente 4
As quatro que mudaram de conclusão eram o achado mais interessante: em três delas, ninguém sabia que a questão já tinha sido decidida, e a nova conclusão contradizia a antiga sem que nada tivesse mudado no contexto. Os sistemas passaram a ter abordagens divergentes para o mesmo problema.
Uma delas, concreta: a política de repetição de chamadas entre serviços foi decidida em 2022 (repetição com recuo exponencial e limite de três) e redecidida em 2024 (repetição imediata, até cinco vezes). Os dois padrões coexistiam. Durante um incidente de degradação, os serviços da segunda geração amplificaram a carga. Ver repetições.
A adoção de ADRs foi deliberadamente leve:
Sem aprovação. O autor decide escrever; não há comitê.
Sem obrigatoriedade formal. A regra é uma pergunta na revisão de desenho: "isto merece ADR?".
No repositório do sistema, revisado como código.
Índice único consultável, para responder "isto já foi decidido?" — o que atacava diretamente o problema medido.
Dezoito meses depois:
ADRs escritos 127
discussões encerradas por "já está no ADR-x" 22
decisões alteradas durante a escrita 19
ADRs superados 11
Os 22 encerramentos por referência cobriram, sozinhos, mais que o custo total de escrita.
E os 11 superados foram usados como argumento interno para sustentar a prática: eles mostravam decisões sendo revistas com base em mudança de contexto documentada, em vez de por opinião.
A lição registrada: a ausência de comitê foi decisiva. Uma tentativa anterior, com aprovação obrigatória, tinha produzido 6 ADRs em um ano — todos genéricos, todos escritos depois da implementação.
Conceitos Relacionados
- O Que É um ADR.
- Alternativas — onde o efeito de escrever se concentra.
- Superação — decisões com validade.
- Arquitetura como Decisões.
Exercício Prático
Identifique uma discussão arquitetural que seu time teve mais de uma vez.
Escreva o ADR que teria encerrado a segunda ocorrência. O tempo que ele levar é a medida do que a ausência custou.
Perguntas de Entrevista
- Por que um ADR se paga antes de ser lido?
- Como o registro muda a natureza do desacordo técnico?
- Que problemas ADRs explicitamente não resolvem?
Para Aprofundar
- Nygard, Michael. Documenting Architecture Decisions. 2011.
- Ford, Neal et al. Software Architecture: The Hard Parts. O'Reilly, 2021.
- Keeling, Michael. Design It!. Pragmatic Bookshelf, 2017.