Registros de decisão de arquitetura que alguém realmente lê

Todo time que audito tem uma de duas coisas: nenhum registro de decisão de arquitetura, ou uma pasta com quarenta ADRs que ninguém abre desde o dia em que foram mergeados. A segunda é só ligeiramente melhor que a primeira, porque cria a ilusão de que as decisões estão documentadas.

Um ADR justifica sua existência quando um engenheiro novo, daqui a dezoito meses, está prestes a desfazer uma decisão e encontra o registro antes de fazer isso. Esse é o único caso de uso que importa. Tudo no formato deveria servir a ele.

Por que a maioria dos ADRs morre

Morrem porque são escritos para o leitor errado. O ADR típico é escrito para justificar a decisão para as pessoas que estavam na sala naquela semana. Usa o vocabulário delas, assume o contexto delas e pula as alternativas que eram 'obviamente' erradas. Dezoito meses depois, nenhuma dessas pessoas está na sala, o vocabulário mudou e a alternativa obviamente errada é justamente a que o engenheiro novo está prestes a escolher.

Morrem também porque são longos demais. Um documento de três páginas com uma seção de 'Contexto' que reconta o produto inteiro não vai ser lido sob pressão. E ADRs são sempre lidos sob pressão, durante um incidente ou um refactor apressado, nunca numa terça-feira tranquila.

E morrem porque não têm validade. Uma decisão tomada quando o sistema tinha mil usuários é apresentada com a mesma autoridade de uma tomada mês passado. O leitor não consegue dizer se ela ainda se aplica.

O formato que sobrevive

Mantenho ADRs em uma tela. Título como frase completa afirmando a decisão, não o assunto: 'Pedidos ficam no Postgres, não no event store' em vez de 'Armazenamento de pedidos'. Depois, cinco seções curtas.

A decisão, em duas ou três frases, escrita de forma que possa ser citada. As forças, ou seja, as três ou quatro restrições que fizeram dessa a escolha certa: um número, um prazo, um tamanho de time, uma regra de compliance. As alternativas rejeitadas, uma linha cada, com o motivo específico pelo qual cada uma perdeu. Não 'MongoDB foi considerado', mas 'MongoDB foi rejeitado porque precisamos de transações multi-linha para reconciliar estornos'. As consequências que você aceita, ou seja, o que fica mais difícil por causa dessa escolha. E as condições para revisitar: 'se o volume de pedidos passar de dez mil por minuto' ou 'se adicionarmos uma segunda região'.

Essa última seção é a que quase ninguém escreve e a que torna o registro inteiro útil. Ela transforma o ADR de justificativa em instrumento. O leitor do futuro não precisa adivinhar se a decisão ainda vale. Ele confere as condições.

A disciplina em volta do formato

O formato é metade. A outra metade é onde os ADRs vivem e como são linkados. Eles pertencem ao repositório, ao lado do código, em Markdown puro, numerados sequencialmente. Não numa wiki, não numa ferramenta de documentos que exige um login que o engenheiro novo ainda não tem.

Todo ADR é referenciado a partir do código que ele governa. Um comentário no topo do módulo: 'Veja ADR-014 para entender por que isto não usa o cache compartilhado'. Esse é o caminho de recuperação. Ninguém navega numa pasta de ADRs. As pessoas chegam no código primeiro, e o código precisa apontar para o registro.

ADRs substituídos nunca são apagados. Recebem um cabeçalho de uma linha, 'Substituído pelo ADR-031', e ficam no lugar. A história de por que uma decisão mudou costuma valer mais do que a decisão em si, porque mostra quais forças se moveram.

E ADRs são escritos antes de a decisão ser implementada, não depois. Escrever a seção de alternativas com honestidade, enquanto as alternativas ainda são possíveis, é o que torna o registro confiável. Um ADR escrito depois do fato é um press release.

O que procuro numa revisão

Quando audito um sistema, leio a pasta de ADRs antes do código. Se a pasta está vazia, sei que toda decisão importante está na cabeça de alguém. Se está cheia mas nenhum registro tem uma seção de 'revisitar quando', sei que as decisões foram escritas para encerrar uma discussão, não para informar uma futura. Se o código nunca as referencia, sei que não fazem parte do sistema em funcionamento.

O bom sinal é pequeno e específico: um registro de dois anos atrás que alguém atualizou no trimestre passado com uma nota dizendo que a condição foi atingida e aqui está a decisão seguinte. Esse é um time que trata arquitetura como algo vivo e com memória. É raro. Vale a pena construir.