Uma decisão técnica pequena merece registro quando muda a forma de construir, operar, proteger ou manter um sistema. O documento não precisa ser longo. Ele precisa explicar qual problema existia, quais alternativas foram consideradas, o que foi escolhido e qual consequência o time aceitou.
Essa prática costuma aparecer como ADR, sigla para Architecture Decision Record. A documentação do Google Cloud descreve ADRs como registros que capturam opções disponíveis, requisitos principais e a decisão adotada. A Thoughtworks também defendeu os ADRs leves no Technology Radar, especialmente quando ficam em controle de versão junto do código.
Em termos práticos, decisão técnica documentada evita que o mesmo debate volte toda vez que uma pessoa nova entra no projeto ou quando uma escolha começa a doer meses depois. O objetivo não é transformar engenharia em ata de reunião. É preservar contexto suficiente para manutenção futura.
Quando registrar uma decisão técnica
A pergunta não é se a decisão parece grande. A pergunta é se a ausência de contexto pode custar caro depois. Escolher uma fila, trocar autenticação, fixar uma versão de banco, adotar feature flag, alterar estratégia de cache ou remover uma dependência são decisões que parecem pequenas no commit, mas afetam operação e manutenção.
Um bom gatilho é a existência de alternativas reais. Se havia dois ou três caminhos plausíveis e o time escolheu um por custo, prazo, risco ou simplicidade, vale registrar. Outro gatilho é recorrência: se a discussão já apareceu mais de uma vez, o registro evita repetir o mesmo ciclo.
Também vale documentar quando a escolha contraria uma preferência comum. Um time pode decidir não usar microserviços, não adotar uma biblioteca popular ou não migrar para uma ferramenta nova. Sem registro, a ausência parece descuido. Com registro, vira decisão revisável.
O formato precisa caber no fluxo
Um ADR útil pode ter uma página. Para uma decisão técnica pequena, cinco blocos já resolvem: contexto, opções, decisão, consequência e data. O contexto explica o problema. As opções mostram o que foi considerado. A decisão registra o caminho escolhido. A consequência diz o que fica melhor, pior ou limitado. A data ajuda a lembrar o momento da escolha.
Não precisa escrever tese. Uma decisão sobre cache pode dizer que o time escolheu cache local por simplicidade, rejeitou Redis por custo operacional e aceitou inconsistência curta entre instâncias. Isso basta para orientar quem encontrar o comportamento depois.
O local importa. Se a decisão afeta um serviço, guardar o ADR no mesmo repositório facilita revisão em pull request e mantém histórico junto do código. Se afeta várias equipes, pode haver uma cópia ou resumo em wiki, mas o registro precisa continuar fácil de encontrar.
Decisão pequena não é regra eterna
Um erro comum é tratar ADR como lei permanente. A documentação registra uma escolha em um contexto. Se o contexto muda, o time pode criar um novo ADR substituindo o anterior. Isso é melhor do que editar o passado até apagar por que a primeira escolha fez sentido.
Essa distinção ajuda em código legado. Ao manter um sistema antigo, é comum encontrar decisões que parecem estranhas. Sem histórico, a equipe só vê dívida técnica. Com histórico, pode descobrir restrição de infraestrutura, requisito de cliente, limite de biblioteca ou incidente anterior.
O post sobre manutenção de código legado segue a mesma linha: antes de mudar, entenda o comportamento existente. Um ADR pequeno não impede mudança. Ele reduz a chance de apagar contexto sem perceber.
Como evitar burocracia
O limite deve ser claro: nem todo commit precisa de ADR. Correção simples, renomeação local, ajuste visual pequeno ou refatoração sem mudança de contrato normalmente cabem na descrição do pull request. ADR entra quando há decisão que alguém precisará justificar ou revisar depois.
Também não vale criar processo pesado para aprovar cada registro. Em times pequenos, o ADR pode nascer no próprio pull request. O autor escreve o rascunho, a revisão discute os pontos principais e o arquivo entra junto da mudança. Se a decisão ainda está aberta, o documento pode ficar como proposta até o time fechar.
A linguagem deve ser direta. Troque "avaliou-se a possibilidade de adoção de mecanismo assíncrono" por "avaliamos fila assíncrona". Quem ler daqui a seis meses quer entender o motivo, não decifrar formalidade.
O que um bom registro responde
Uma decisão técnica bem escrita responde quatro perguntas cedo: qual problema existia, por que a solução escolhida foi suficiente, o que ficou fora e quando revisar. Esse último ponto evita acoplamento emocional. Se a decisão depende de volume, custo ou prazo, diga qual sinal indicaria revisão.
O post sobre arquitetura simples em serviços web reforça o mesmo princípio. Simplicidade não é ausência de decisão. É escolher menos peças e deixar claro por que elas bastam.
Para times pequenos, a medida de sucesso é simples: alguém novo consegue entender a escolha sem chamar três pessoas antigas? Se consegue, o registro cumpriu o papel. Uma decisão técnica pequena, bem documentada, economiza conversa repetida e deixa a próxima mudança mais segura.
