Como registrar uma decisão de arquitetura para que outra equipe entenda o motivo

O que você vai levar deste guia

• Registre uma decisão significativa e a pergunta que ela resolve.
• Compare alternativas plausíveis pelos mesmos critérios.
• Declare consequências e condições de revisão sem reescrever a história.

Escolha uma pergunta que merece uma decisão registrada

Um registro de arquitetura deve responder a uma pergunta concreta, não apresentar uma coleção de preferências técnicas. “Como executar a geração de relatórios extensos sem bloquear o uso cotidiano?” é uma pergunta. “Usaremos tecnologia moderna” não identifica problema nem alternativa. Comece pelo efeito que a escolha precisa produzir e pelas restrições que tornam a decisão relevante. Isso ajuda a manter o documento curto o suficiente para ser lido e completo o suficiente para orientar.

No exemplo fictício da empresa Projeto Operacional, a equipe precisa decidir se relatórios extensos serão executados dentro da aplicação web ou por trabalhadores separados. Há volume crescente, uma equipe pequena e uma infraestrutura já existente. A escolha terá impacto em implantação, monitoramento e suporte. O registro deve preservar esses fatores, porque uma equipe futura pode olhar apenas a arquitetura final e presumir que foi escolhida por preferência de ferramenta.

A orientação da AWS sobre registros de decisão de arquitetura descreve um ADR como documento de uma escolha significativa sobre a arquitetura. O método deste tutorial aplica essa ideia a uma decisão delimitada, com comparação e evidências próprias do projeto fictício. Não é necessário criar um documento para cada linha de código; o valor aparece quando a razão da escolha seria difícil de recuperar apenas pela implementação.

Descreva o contexto sem transformar hipótese em fato

Registre o problema observado e a evidência disponível. Separe medições, relatos e suposições. Se a equipe observou lentidão em determinados horários, indique o recorte e a limitação da amostra. Se espera crescimento, descreva como cenário, não como certeza. Uma decisão pode ser razoável sob incerteza, mas o documento precisa mostrar o que era conhecido. Isso evita que previsões sejam lidas meses depois como requisitos confirmados.

Inclua restrições relevantes: capacidade da equipe, prazo, contratos de integração e requisitos de operação. Não liste tudo que existe no projeto. Uma restrição importa quando influencia a escolha. No exemplo, a equipe tem experiência com um tipo de trabalhador e precisa operar a solução sem plantão dedicado. Esses fatores podem favorecer uma alternativa mais simples, mesmo que outra tenha maior potencial de escala em um cenário ainda não observado.

Defina o que está fora da decisão. Escolher onde executar relatórios não precisa decidir toda a arquitetura de eventos ou a tecnologia de cada módulo. Limitar o escopo impede que a discussão se torne um projeto de substituição completa. Também ajuda a identificar decisões relacionadas que merecem registros próprios, com links e dependências, em vez de um documento enorme que mistura problemas diferentes.

Liste alternativas plausíveis de forma justa

Inclua opções que a equipe poderia realmente adotar, inclusive manter a solução atual com ajustes quando isso for viável. Não construa uma alternativa fraca apenas para justificar a preferida. Descreva cada opção no mesmo nível de detalhe e com as mesmas premissas de volume. Comparar uma solução cuidadosamente dimensionada com uma caricatura da outra produz aparência de análise sem oferecer evidência útil.

Na Projeto Operacional fictícia, as alternativas podem ser otimizar o processamento dentro da aplicação, mover relatórios para um trabalhador separado no ambiente atual ou adotar um serviço especializado. Cada uma tem custos de implementação e operação. A opção atual pode atender ao volume de curto prazo; o serviço especializado pode exigir integração e governança adicionais. O registro deve permitir entender por que essas diferenças importam para o problema delimitado.

Evite confundir produto específico com capacidade. Primeiro explique o mecanismo que a alternativa oferece; depois identifique a ferramenta considerada quando necessário. Isso torna a decisão menos dependente de nomes e ajuda a revisá-la se um fornecedor mudar. Ao mesmo tempo, não esconda características concretas que afetam a escolha, como limites, formas de implantação ou requisitos de acesso, verificando informações que possam mudar antes de usá-las como critério.

Defina critérios antes de escolher a favorita

Escolha critérios ligados ao contexto: isolamento de carga, esforço de operação, tempo de implantação, custo e capacidade de recuperar falhas. Explique como cada um será avaliado. Uma nota de um a cinco sem definição pode apenas representar preferência pessoal. Sempre que possível, use observações ou condições verificáveis, como necessidade de manter a interface responsiva durante um relatório ou capacidade de retomar uma tarefa interrompida.

Não atribua precisão indevida a números estimados. Se o custo depende de volume incerto, mostre cenários e premissas. Se o esforço é uma avaliação da equipe, identifique-o como estimativa. A comparação deve apoiar a decisão, não fingir que um cálculo elimina julgamento. Pesos podem ajudar em alguns casos, mas também podem esconder uma restrição obrigatória que não deveria ser compensada por vantagens em outros critérios.

Separe requisitos eliminatórios de preferências. Uma alternativa que não atende a uma condição indispensável pode sair da comparação, com motivo registrado. As restantes podem ser avaliadas por trade-offs. No exemplo fictício, impedir que relatórios extensos ocupem todos os recursos da interface pode ser uma condição necessária; conveniência de configuração é outro tipo de critério. Essa distinção evita escolher uma opção inadequada porque recebeu boas notas em aspectos secundários.

Reúna evidência proporcional à incerteza

Use um experimento pequeno para responder à dúvida mais importante, quando a decisão não puder ser feita apenas com informação existente. O experimento precisa ter entrada, medição e limite claros. Na empresa fictícia, pode executar um relatório representativo junto de tarefas interativas para observar contenção. Não é necessário construir todas as alternativas completas antes de decidir, mas é útil testar a premissa que sustenta a escolha quando seu erro teria custo alto.

Registre resultados e limitações. Um teste em volume reduzido não demonstra comportamento de escala ilimitada. Um protótipo sem autenticação ou observabilidade pode medir processamento, mas não o esforço total de operação. A evidência deve ser descrita pelo que realmente mostrou. Isso permite que a equipe futura reconheça quando o contexto ultrapassou a cobertura do experimento e precisa de nova avaliação.

Inclua referências verificadas para características técnicas e mantenha a análise do projeto separada delas. Documentação de fornecedor explica capacidades, mas não prova que a alternativa é adequada ao seu uso. A Tironi Tech pode conduzir essa análise e desenvolver experimentos focados para reduzir incertezas antes de comprometer uma implementação maior. O objetivo é obter informação que muda a decisão, não produzir um protótipo vistoso sem critério de leitura.

Escreva a decisão e suas consequências

Declare a escolha em uma frase direta, com escopo. Depois explique os motivos decisivos e as consequências aceitas. Não esconda custos para tornar o documento persuasivo. Se a alternativa reduz contenção e acrescenta um trabalhador para operar, ambos fazem parte da decisão. Uma equipe que conhece o custo pode planejar manutenção; uma equipe que só lê vantagens descobre obrigações depois e perde confiança no registro.

Na Projeto Operacional fictícia, a decisão pode ser separar a geração extensa em um trabalhador no ambiente atual, preservando relatórios pequenos no caminho existente por enquanto. As consequências incluem acompanhar fila, oferecer estado ao usuário e testar retomada. Essa formulação é mais útil que “adotar arquitetura assíncrona”, porque indica o recorte e o trabalho que decorre dele. Não use o ADR para substituir a lista de implementação, mas conecte os itens necessários.

Registre alternativas descartadas e por que não foram escolhidas neste contexto. Evite linguagem absoluta como “nunca usar”. Uma opção pode ser inadequada agora e adequada depois. Preserve o motivo temporal ou de capacidade. Isso ajuda a evitar discussões repetidas e também impede que a escolha atual vire uma regra universal sem fundamento. O documento deve mostrar julgamento situado, não uma declaração de superioridade técnica permanente.

Defina estado, responsáveis e condições de revisão

Um registro pode estar proposto, aceito, substituído ou encerrado, conforme o processo da equipe. O estado precisa ser visível para que uma ideia em discussão não seja tratada como orientação vigente. Identifique quem participou e quem responde por acompanhar as consequências. Não transforme isso em uma burocracia ampla sem necessidade; a finalidade é saber se a decisão existe, foi adotada e continua aplicável.

Escreva condições que justificam revisão. No exemplo, crescimento além de uma capacidade observada, aumento de espera ou mudança de equipe podem exigir reavaliar a solução. Evite uma revisão automática sem pergunta apenas porque passou um prazo arbitrário. Uma data pode ajudar a conferir premissas, mas os sinais concretos tornam a revisão mais útil. A equipe precisa saber o que observar para reconhecer que o contexto mudou.

Quando houver substituição, preserve a decisão anterior e registre a relação. Não edite silenciosamente o documento para parecer que a escolha nova sempre foi a intenção. A história explica por que o sistema contém certas estruturas e por que um custo foi aceito. Uma revisão honesta pode reconhecer que uma hipótese estava errada; esse aprendizado é mais valioso que um histórico reescrito para eliminar incerteza retrospectivamente.

Verifique se o registro ajuda alguém a agir

Peça a uma pessoa que não participou da discussão para ler e responder: qual problema foi resolvido, quais alternativas existiam e que consequência precisa ser implementada? Se ela só consegue repetir o nome da ferramenta, o documento está incompleto. Se precisa ler uma longa cronologia de reuniões para encontrar a decisão, reorganize. O leitor futuro precisa de contexto e razões, não de uma transcrição de toda a conversa.

Conecte o registro à documentação e ao código relevantes sem duplicar detalhes que mudam frequentemente. Um diagrama pode mostrar a estrutura atual, enquanto o ADR explica a escolha. Um procedimento operacional descreve como agir, enquanto a consequência do ADR justifica por que ele existe. Essa divisão reduz documentos contraditórios e facilita manutenção. Atualize referências quando a implementação final divergir da proposta aceita.

Finalize conferindo se a decisão foi realmente implementada e se as consequências têm responsáveis. Um ADR aceito, mas ignorado no código, precisa de revisão ou correção explícita. Acompanhe as premissas que motivaram a escolha e registre o aprendizado relevante. O resultado é uma memória técnica que ajuda a equipe a evoluir o sistema com contexto, sem repetir debates antigos nem preservar soluções apenas porque ninguém sabe por que foram criadas.

Perguntas frequentes

Toda alteração precisa de um ADR?

Não. Use o registro para escolhas com impacto duradouro, alternativas relevantes ou custo de mudança significativo. Pequenos detalhes podem permanecer na documentação e no código apropriados.

O ADR deve ser escrito apenas depois da implementação?

Pode começar como proposta e ser atualizado até a decisão. Depois, deve refletir o que foi realmente escolhido, mantendo estado e consequências claros.

Posso alterar uma decisão antiga quando ela deixou de valer?

Preserve a história e registre a substituição ou revisão com referência à anterior. Isso permite entender por que a escolha fazia sentido antes e o que mudou.

Dê clareza às escolhas técnicas do seu projeto

A Tironi Tech pode organizar alternativas, evidências e decisões de arquitetura para desenvolver software alinhado às restrições reais da sua empresa.

Artigos relacionados

• Como modernizar um sistema legado substituindo um módulo de cada vez
• Como cancelar uma tarefa assíncrona sem esconder efeitos que já aconteceram
• Como preparar um formulário para trabalhar offline e sincronizar depois

Fontes consultadas

• AWS — Architectural decision record process