Governança
Modelos e provedores mudam a cada poucos meses, e a razão por trás de uma escolha some antes do código. Um registro curto por decisão a preserva.
5 de nov. de 2026 · 4 min de leitura
O diagrama e as fontes estão em inglês.
Seis meses depois do início de um projeto de agentes, alguém pergunta por que as tarefas de suporte vão para um modelo de nível médio, ou por que as aprovações ficam no gateway de ferramentas e não no agente. O código mostra o que foi construído. Não mostra o que foi considerado. É essa a lacuna que um registro de decisão de arquitetura, ou ADR, preenche.
Michael Nygard propôs o formato em 2011: um documento curto por decisão importante, com título, status, contexto, decisão e consequências. Os registros são numerados em sequência, e um número nunca é reaproveitado.
Se uma decisão for revertida, mantenha o registro antigo e marque-o como substituído, com uma indicação do substituto. As alternativas rejeitadas costumam ser a parte mais útil para um leitor futuro, porque impedem que a equipe refaça a mesma discussão.
Exemplo, inventado para ilustrar: ADR-007, Encaminhar a classificação a um modelo pequeno. Status: aceita. Contexto: a classificação domina o volume e não precisa de raciocínio profundo. Decisão: vamos enviar a classificação ao menor nível e escalar quando a confiança for baixa. Alternativas rejeitadas: um modelo grande para tudo, por causa do custo. Consequências: precisamos manter um conjunto de avaliação para detectar regressões quando o modelo pequeno mudar.
Conte para a gente sobre um processo. Mostramos como um agente poderia resolvê-lo e o que medir para saber que está funcionando.