Por Que Eu Escrevo ADRs Antes de Escrever Código
Código captura o que você construiu. Um ADR captura por que você construiu daquele jeito — e o porquê é a primeira coisa a desaparecer conforme o projeto envelhece.
Sem o contexto da decisão registrado, toda escolha arquitetural passada parece arbitrária para quem chega depois. Isso vale para um engenheiro novo no time e, cada vez mais, para um agente de IA tentando entender o codebase.
O problema não é de documentação
É de transmissão de contexto. Código é excelente para capturar o o quê e o como. É péssimo para capturar o por quê e o por que não fizemos diferente.
Em projetos que passam de seis meses, isso aparece de forma previsível. Alguém questiona uma decisão arquitetural. Ninguém lembra do raciocínio original. Acontece uma discussão de duas horas, e a conclusão é "vamos manter porque não sabemos quanto custaria mudar".
A versão alternativa: a discussão começa, alguém abre o ADR-006, lê o contexto em cinco minutos, e a decisão de manter ou mudar acontece com informação de verdade.
Para agentes de IA trabalhando no codebase o problema é ainda mais agudo. Um agente sem contexto de decisão vai propor "melhorias" que violam restrições que existem por boas razões — e você vai gastar seu tempo revertendo mudanças geradas por falta de contexto.
O formato
Uso o formato original de Michael Nygard, versionado no mesmo repositório Git do código:
# ADR-NNN: Título descritivo
## Status
Proposto | Aceito | Depreciado | Substituído por ADR-XXX
## Contexto
Por que esta decisão precisa ser tomada agora. Quais forças estão em jogo.
## Decisão
O que foi decidido, de forma afirmativa: "Vamos usar X."
## Consequências
O que muda por causa disso — o bom e o ruim.
O valor não está no documento. Está em forçar a articulação explícita do raciocínio antes de codar. Se você não consegue escrever o contexto e as alternativas, provavelmente não entendeu o problema bem o suficiente para decidir bem.
Quando escrever um
O critério é reversibilidade, e o rigor deve ser proporcional ao custo de desfazer a decisão.
Reversível, baixo custo de mudança — trocar o CI de GitHub Actions para CircleCI. Não precisa de ADR formal. Uma linha na mensagem de commit resolve.
Irreversível, ou caro de reverter — o esquema de isolamento de multi-tenancy, o ORM, o modelo de dados de tenant. Esses precisam de ADR.
A decisão de multi-tenancy é o exemplo mais claro. Mudar um esquema de isolamento de tenant em produção exigiria migrar os dados de todos os tenants ativos, coordenar downtime e revalidar o isolamento depois. O custo se mede em semanas. Documentar o contexto antes custou trinta minutos.
Essa assimetria é o argumento inteiro.
O que doze ADRs realmente cobriram
Para um produto de compliance, o conjunto cobriu o provedor de busca, o motor de classificação, persistência, agendamento de jobs, deduplicação de alertas repetidos, o modelo de multi-tenancy, autenticação e autorização, e a stack principal — entre outros.
O que chama atenção é o que não está na lista. Nenhum ADR para formatação de código. Nenhum para o framework de testes. Nenhum para o provedor de CI. Todos são baratos de mudar, então não mereceram a cerimônia.
O que eu aprendi
Escrever o ADR frequentemente mudou a decisão. Várias vezes comecei a documentar uma escolha que já tinha feito, cheguei na seção de alternativas consideradas e percebi que não conseguia articular por que a alternativa óbvia era pior. É o mecanismo funcionando — o documento é uma ferramenta de pensamento que por acaso deixa um artefato.
Mantenha o campo de status honesto. Um ADR marcado como Aceito que o codebase não segue mais é pior que nenhum ADR, porque engana ativamente. Quando a abordagem muda, marque a antiga como Substituído por ADR-XXX em vez de editar a história.
E escreva no momento da decisão, não depois. Um ADR retrospectivo reconstrói uma racionalização; um contemporâneo registra uma razão.