Documento de decisão técnica só serve para registrar o que você não escolheu

Todo time de engenharia com mais de dois anos de vida passa pelo mesmo constrangimento: alguém olha uma query esquisita no repositório, acha o código arcaico, reescreve tudo usando uma abstração elegante e derruba a produção duas semanas depois. O motivo daquele código feio existia. O problema é que o motivo estava guardado na cabeça de um desenvolvedor que mudou de emprego no ano anterior.

Quando isso acontece, a reação padrão da liderança costuma oscilar entre dois extremos igualmente disfuncionais. De um lado, estão os defensores do formalismo pesado, que tentam implantar processos burocráticos de Architecture Decision Record (ADR) com formulários de cinco páginas, matrizes ponderadas de decisão e cerimônias de aprovação prévia. Na outra ponta, estão os pragmáticos radicais, que defendem que qualquer documento apodrece no minuto seguinte ao commit e que o próprio código, somado aos testes de integração, deveria ser a única fonte de verdade aceitável.

Eu discordo das duas abordagens. A turma do código como documentação comete o erro ingênuo de achar que código expressa intenção negativa. O código mostra exatamente como o sistema funciona hoje, mas não diz absolutamente nada sobre as quatro alternativas que foram testadas e descartadas porque estouravam a memória do banco de dados. Já a turma dos templates complexos cria cemitérios de Markdown no repositório. Ninguém lê documentos de quatro páginas antes de abrir um pull request, e qualquer processo de documentação que dependa de disciplina heróica é derrotado pelo cansaço em menos de três meses.

Se você quer que um registro de decisão técnica sobreviva ao tempo e continue útil daqui a quatro anos, ele precisa cumprir uma única missão: impedir que o próximo desenvolvedor tome a mesma decisão errada que você quase tomou.

O vício da justificativa triunfal

A falha estrutural da maioria dos documentos de arquitetura é o viés retrospectivo. O autor escreve o texto depois que a decisão já foi tomada, no ápice do entusiasmo com a nova tecnologia ou com o novo padrão de projeto. O resultado é sempre um panfleto promocional disfarçado de análise técnica.

O texto gasta 80% do espaço listando as vantagens teóricas da ferramenta escolhida e 20% minimizando os riscos com frases vazias sobre flexibilidade futura. Isso não serve para nada. Daqui a três anos, quem estiver mantendo o sistema já saberá de cor todos os problemas operacionais que a sua escolha causou. O que essa pessoa não vai saber é o contexto de pressão, as restrições financeiras e os limites de infraestrutura que tornaram aquela escolha específica a única viável naquele momento.

Documento útil não tenta convencer ninguém de que a escolha foi brilhante. Ele registra o custo aceito e o contexto real de contorno.

## ADR 014: Processamento assíncrono via fila no PostgreSQL

## Status
Aceito (2024-03)

## Contexto
O volume de notificações por e-mail cresceu e começou a prender threads web do Puma.
Nossa infraestrutura roda em VPS próprias com recursos limitados de memória RAM.

## Decisão
Usar tabela no PostgreSQL com SKIP LOCKED em vez de subir Redis e Sidekiq.

## Alternativas descartadas
- Redis + Sidekiq: Adicionaria 300 MB de memória base e mais um processo para monitorar no systemd.
- Mensageria externa gerenciada: Custo em dólar e dependência de rede externa para fluxo interno.

## Condição de invalidação
Se a taxa de escrita na tabela de jobs ultrapassar 500 inserts por segundo e causar bloat no autovacuum.

Perceba a diferença de foco. O exemplo não tenta glorificar o uso do banco relacional para enfileiramento de tarefas. Ele deixa claro que a decisão foi pautada pelo consumo de memória em servidores dedicados e define com clareza o limite onde essa escolha deixará de funcionar.

Os três elementos que realmente importam

Para que um registro de trade-off não se torne lixo acumulado no repositório, eu eliminei quase todos os campos dos modelos tradicionais. Três itens são suficientes para manter a clareza técnica ao longo de anos:

O contexto de restrição precisa descrever o que estava doendo e quanto podíamos gastar para resolver a dor. Isso inclui restrições de equipe (ninguém no time conhecia Elixir na época), limites de infraestrutura (rodamos em servidores próprios sem elasticidade automática de nuvem pública) e prazos operacionais.

As alternativas descartadas precisam mostrar o teste prático, não a teoria. Em vez de escrever que a alternativa B não era viável, registre o motivo exato: a biblioteca concorrente exigia uma versão de Ruby que conflitaria com outras dependências antigas do projeto, ou o driver de conexão causava vazamento de descritores de arquivo sob carga contínua.

A condição de invalidação é a parte mais ignorada pelas equipes e, ao mesmo tempo, a mais valiosa. Toda decisão arquitetural possui um prazo de validade implícito. Quando você escreve sob quais condições aquela decisão deve ser jogada no lixo, você dá permissão explícita para o time do futuro refazer a estrutura sem sentir culpa ou medo de desrespeitar decisões históricas da liderança.

A ilusão da documentação centralizada

Outro erro clássico de gestão é criar um repositório isolado ou uma ferramenta externa de notas para concentrar as decisões técnicas da empresa. No instante em que o registro sai do repositório principal da aplicação, ele morre.

O desenvolvedor que está investigando uma lentidão no Active Record ou ajustando uma política de locks no PostgreSQL não vai abrir uma aba separada no navegador para procurar se alguém discutiu aquele índice em 2023. O registro precisa estar a dois cliques de distância da linha de código alterada.

Na prática, isso significa manter arquivos pequenos em Markdown dentro de um diretório na raiz do projeto (como docs/decisoes/), versionados pelo Git e revisados no mesmo pull request que introduz a mudança de comportamento no sistema. Se o código mudou a arquitetura mas o pull request não incluiu a nota correspondente explicando o descarte das alternativas, a revisão técnica não terminou.

A tabela abaixo sintetiza o contraste entre o modelo corporativo tradicional e a abordagem enxuta voltada para quem opera a infraestrutura no dia a dia:

Aceitar a precariedade das escolhas

Engenharia de software aplicada a negócios reais é a arte de escolher com qual dor de cabeça você prefere lidar amanhã. Não existem soluções perfeitas, apenas acordos operacionais temporários que viabilizam o produto enquanto o contexto permitir.

Quando você tenta blindar suas decisões através de documentos pomposos, você cria um monumento à vaidade técnica que envelhece mal. Quando você escreve de forma crua o que foi descartado, o dinheiro que você não podia queimar e o volume de tráfego que o sistema suporta antes de engasgar, você deixa um mapa de minas confiável para quem vier depois de você.

O valor de documentar um trade-off não está na posteridade da sua inteligência, mas na economia de tempo de quem vai ter que consertar o sistema de madrugada daqui a três anos. Se o seu texto economizar uma refação cega ou impedir que alguém suba uma dependência desnecessária em produção, ele cumpriu todo o papel que a engenharia precisava.