Definição curta

Documento curto que registra uma decisão de arquitetura de software: o contexto que a tornou necessária, as opções consideradas, a opção escolhida e as consequências aceitas. Abreviado como ADR.

Definição detalhada

A prática vem dos times de desenvolvimento e ali já está bastante consolidada. Sua razão de ser é temporal: vários meses ou vários anos depois, alguém que não estava lá precisa conseguir entender por que uma escolha técnica foi feita — por que uma fila foi introduzida para tratar certas mensagens de forma assíncrona, que opções foram descartadas, o que a escolha permite e o que ela restringe.

Nos artigos deste blog, o termo aparece como referência de origem, e não por si mesmo: ele serve para situar o Product Decision Record, que retoma a estrutura deslocando o objeto do componente técnico para a regra de produto. A diferença de natureza está no que é registrado — um ADR fixa uma escolha de construção do sistema, um PDR fixa uma regra aplicável a situações futuras.

O ADR tem uma propriedade que o vocabulário de produto retoma mal: ele documenta com frequência frentes de trabalho sem valor de negócio visível. Um mês de trabalho numa tecnologia de fila não entrega nada ao usuário final e pode, ainda assim, eliminar um gargalo, absorver dez a trinta vezes a carga só com a adição de servidores, e liberar a venda de novos acessos a clientes.

Uso no domínio

O termo aparece nas discussões sobre a memória técnica de um time, sobre a justificativa de frentes de trabalho sem entrega funcional, e como ponto de comparação sempre que se propõe um dispositivo equivalente do lado do produto.

Sinônimos e variantes

"Decisão de arquitetura", "ADR", "diário de arquitetura". O plural "os ADR" designa correntemente tanto o registro inteiro quanto suas entradas.

Não confundir com

• Product Decision Record — Product Decision Record — mesma forma documental aplicada a uma regra de decisão de produto transversal; ele não compromete nenhuma escolha de construção.
• Documentação de arquitetura — descrição do estado do sistema tal como ele é; o ADR descreve um momento de escolha e não é atualizado quando o sistema evolui.
• Especificação técnica — descrição do que precisa ser feito e como; ela decorre de uma decisão de arquitetura, mas não a justifica.

Exemplos

"Uma aplicação sofre um aumento de carga. […] O time decide então implementar uma tecnologia de fila para tratar certas mensagens de forma assíncrona." — a situação típica que o ADR registra.

"Por que ela foi tomada? Que opções foram descartadas? Que consequências são aceitas? O que isso permite? O que isso restringe?" — as perguntas às quais a entrada responde.

Ambiguidades / debates

O uso corrente hesita quanto à imutabilidade: alguns times mantêm seus ADR como documentos congelados e marcam as substituições, outros os atualizam como uma documentação viva. O sentido adotado aqui segue a primeira prática, que é também a que o PDR retoma.