💻 computer science

One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption

Este artigo avalia empiricamente cinco modelos de Registro de Decisão Arquitetural (ADR) por meio de triagem por especialistas e um experimento controlado para demonstrar que o modelo de Nygard oferece compreensão e usabilidade gerais superiores, fornecendo aos profissionais um guia baseado em evidências para selecionar o formato de documentação mais eficaz.

Autores originais: Fernando Nogueira, Nabson Silva, Tayana Conte

Publicado 2026-05-01

📖 4 min de leitura☕ Leitura rápida

CC BY 4.0

Autores originais: Fernando Nogueira, Nabson Silva, Tayana Conte

Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine que você está construindo um castelo de Lego massivo e complexo. Você e sua equipe tomam centenas de decisões minúsculas ao longo do caminho: "Essa torre deve ser vermelha ou azul?" "Usamos os tijolos redondos ou os quadrados?" "Por que decidimos colocar o fosso aqui?"

Se você não anotar essas decisões, dois anos depois, quando um novo construtor se juntar à equipe, ele não terá ideia de por que o castelo tem a aparência que tem. Ele pode mudar uma torre vermelha para azul, sem perceber que ela era vermelha para combinar com o pôr do sol na história. Essa perda do "porquê" é o que o artigo chama de vaporização do conhecimento—o vapor invisível de ideias esquecidas que deixa seu projeto confuso e bagunçado.

Para evitar isso, equipes de software usam algo chamado ADR (Registro de Decisão Arquitetural). Pense em um ADR como uma pequena entrada de diário para uma escolha específica de construção. Mas aqui está o problema: existem muitos "modelos de diário" diferentes disponíveis. Alguns são como um simples cartão postal com três linhas de texto; outros são como um contrato legal de 20 páginas com caixas de seleção para cada detalhe possível.

A grande pergunta que este artigo faz é: "Existe um modelo perfeito que se encaixa em todas as situações, ou precisamos de modelos diferentes para trabalhos diferentes?"

O Experimento: Um Degustação de Modelos

Os pesquisadores não apenas adivinharam; eles realizaram uma degustação científica.

Passo 1: Os Juízes Especialistas
Primeiro, dois arquitetos especialistas (os autores do artigo) analisaram cinco modelos populares. Eles agiram como críticos gastronômicos, avaliando-os em três aspectos:

Compreensão: É fácil de ler e entender?
Usabilidade: É rápido e fácil de preencher?
Adoção: Você realmente gostaria de usar isso no seu trabalho diário?

Eles reduziram o campo às duas opções "mais saborosas":

Modelo de Nygard: O "Cartão Postal". É curto, simples e vai direto ao ponto.
MADR: O "Relatório Detalhado". É estruturado, tem mais seções e obriga você a pensar sobre prós, contras e alternativas.

Passo 2: Os Cozinheiros Estudantes
Em seguida, eles trouxeram 33 estudantes de engenharia de software (atuando como construtores juniores). Os estudantes foram divididos em dois grupos e receberam dois "desafios de construção" diferentes (como decidir como conectar a um serviço externo ou qual banco de dados usar).

Grupo A usou o modelo de Nygard para o primeiro desafio e o modelo MADR para o segundo.
Grupo B fez exatamente o oposto.

Esse desenho "cruzado" garantiu que todos testassem ambos os estilos, para que os resultados não fossem apenas sobre quem era melhor em escrever, mas sobre qual modelo era realmente mais fácil de usar.

Os Resultados: Depende da Sua Situação

O estudo descobriu que não existe "tamanho único". O melhor modelo depende inteiramente do seu contexto.

1. O Vencedor da "Corrida Rápida": Nygard
Quando os estudantes precisavam escrever rapidamente, ou quando o projeto era pequeno e ágil, eles adoraram o Nygard.

A Analogia: É como pedir um café rápido. Você entra, diz "Cappuccino", paga e vai embora.
Por que venceu: Foi mais rápido de preencher, menos confuso e pareceu menos "lição de casa". Os estudantes sentiram que era "direto ao ponto". Se você está com pressa ou trabalhando em um projeto pequeno, este é o seu modelo de escolha.

2. O Vencedor da "Imersão Profunda": MADR
Quando os estudantes tinham mais tempo, ou quando a decisão parecia muito importante e complexa, eles preferiram o MADR.

A Analogia: É como uma refeição completa com um cardápio detalhado. Você precisa preencher mais campos, mas isso obriga você a pensar por que está escolhendo a sopa em vez da salada.
Por que venceu: Reduziu a ambiguidade. Como tinha mais seções (como "Prós", "Contras" e "Alternativas"), tornou o raciocínio mais claro e menos aberto a interpretações erradas. Foi melhor para projetos grandes e críticos onde você não pode se dar ao luxo de ser vago.

O Veredito

O artigo conclui que escolher um modelo não se trata de escolher o "melhor" em geral. Trata-se de escolher a ferramenta certa para o trabalho:

Use o "Cartão Postal" (Nygard) quando você estiver se movendo rápido, o projeto for pequeno, ou você apenas precisar capturar a decisão rapidamente sem se perder em detalhes.
Use o "Relatório Detalhado" (MADR) quando a decisão for crítica, o projeto for enorme, ou você precisar garantir que todos entendam o raciocínio profundo por trás da escolha.

A principal lição é simples: Não force um modelo complexo e detalhado em uma tarefa rápida e pequena, e não use um pequeno cartão postal para uma decisão massiva e vital. Combine o modelo ao tamanho e à urgência do seu projeto.

1. Declaração do Problema

Decisões de Design Arquitetural (ADDs) são críticas para a manutenibilidade de software, a integração de desenvolvedores e a prevenção da "vaporização do conhecimento" (a perda de conhecimento arquitetônico embutido). Embora os Registros de Decisão Arquitetural (ADRs) sejam amplamente utilizados para documentar essas decisões, a indústria carece de evidências empíricas para orientar a seleção de modelos específicos de ADR.

A Lacuna: A seleção atual de modelos é frequentemente impulsionada por preferências ad hoc, experiência pessoal ou convenções da comunidade, em vez de dados sistemáticos.
O Desafio: Existe um trade-off entre a completude da documentação (capturar a justificativa completa) e a sobrecarga da documentação (tempo e carga cognitiva). Não está claro quais modelos equilibram melhor a compreensão, a usabilidade e a facilidade de adoção em diferentes contextos.
Objetivo: Comparar empiricamente modelos proeminentes de ADR para determinar qual melhor apoia a documentação eficaz e identificar os fatores que influenciam a preferência pelo modelo.

2. Metodologia

O estudo empregou um design de avaliação em duas etapas, combinando análise de especialistas com um experimento controlado, utilizando o método DESMET Feature Analysis (FA).

Fase 1: Análise de Recursos Baseada em Especialistas (Triagem)

Participantes: Dois especialistas do domínio (autores com mais de 4 anos de experiência industrial).
Candidatos: Cinco modelos amplamente utilizados foram avaliados:
1. Tyree/Akerman
2. ADR de Nygard
3. arc42
4. Declarações Y
5. MADR (Markdown ADR)
Critérios de Avaliação (DESMET FA): Os modelos foram pontuados em três Conjuntos de Recursos (FS):
- FS1: Compreensão Estrutural: Capacidade de identificar campos-chave (Decisão, Contexto, Consequências).
- FS2: Eficiência e Usabilidade: Tempo para completar, frequência de consulta a ajuda e objetividade percebida.
- FS3: Potencial de Adoção: Probabilidade de recomendar o modelo.
Resultado: Nygard e MADR alcançaram as Maiores Pontuações Gerais e foram selecionados para o experimento controlado.

Fase 2: Experimento Controlado

Participantes: 33 estudantes de graduação em Engenharia de Software (atuando como proxies para desenvolvedores juniores).
Design: Um design cruzado para mitigar efeitos de aprendizado e fadiga.
- Tratamentos: Nygard vs. MADR.
- Tarefas: Dois cenários de decisão arquitetural (comunicação de API e seleção de banco de dados).
- Procedimento: O Grupo A usou Nygard na Tarefa 1 e MADR na Tarefa 2; o Grupo B fez o inverso. Um intervalo de uma semana separou as tarefas.
Coleta de Dados:
- Quantitativa: Tempo gasto, número de consultas, precisão na identificação de campos, objetividade percebida (escala Likert) e pontuação de recomendação (0–10).
- Qualitativa: Formulários de feedback pós-experimento analisados via Teoria Fundamentada (codificação aberta e axial).
Análise Estatística: Teste de Soma de Postos de Wilcoxon (devido à distribuição não normal) e cálculo do tamanho do efeito (Delta de Cliff).

3. Contribuições Principais

Comparação Empírica: O primeiro estudo a fornecer evidências quantitativas e qualitativas comparando modelos amplamente utilizados de ADR (Nygard vs. MADR) com base em compreensão, usabilidade e adoção.
Guia de Decisão Contextual: Um framework sugerindo que nenhum modelo único é o "melhor"; a seleção depende das restrições do projeto (tempo, escala e criticidade).
Aplicação Metodológica: Demonstra a aplicação do método DESMET FA em um processo de duas etapas (triagem por especialistas seguida de validação por estudantes) para avaliar artefatos de engenharia de software.
Artefatos Abertos: Todos os instrumentos, dados brutos e resultados estão publicamente disponíveis para replicação.

4. Resultados

Achados Quantitativos (RQ1)

Desempenho Geral: O modelo de Nygard superou significativamente o MADR na Pontuação Geral ( $p = 0.002$ $p = 0.002$ ).
- Pontuação Mediana de Nygard: ~0,8
- Pontuação Mediana de MADR: ~0,7
Tamanho do Efeito: O Delta de Cliff ( $\delta$ ) foi de 0,6364 (grande tamanho do efeito), e a Probabilidade de Superioridade foi de 81,8%, indicando uma alta probabilidade de que Nygard produza melhores resultados em termos de compreensão, usabilidade e adoção para os cenários testados.
Triagem por Especialistas: Ambos os modelos obtiveram as maiores pontuações na fase de especialistas, mas a estrutura enxuta de Nygard lhe deu uma vantagem nas métricas de eficiência.

Achados Qualitativos (RQ2)

Três fatores principais influenciaram a preferência dos participantes:

Granularidade Estrutural:
- MADR: Preferido para reduzir ambiguidades e garantir a completude da justificativa. Seus campos detalhados forçam uma explicação minuciosa, mas aumentam a carga cognitiva.
- Nygard: Preferido por objetividade e clareza. Sua estrutura mínima evita "desordem" e torna o documento mais fácil de escanear e preencher.
Restrições Temporais:
- Ciclos Curtos: Equipes com prazos apertados preferiram Nygard devido à baixa sobrecarga e velocidade.
- Ciclos Mais Longos: Equipes com mais tempo preferiram MADR por sua profundidade estruturada.
Escala do Projeto e Criticidade:
- Projetos Grandes/Alto Risco: MADR foi favorecido para apresentações à liderança e sistemas complexos que exigem documentação exaustiva.
- Projetos Pequenos/Ágeis: Nygard foi favorecido para manter a agilidade e minimizar o fardo da documentação.

5. Significado e Conclusão

O estudo conclui que "Um Tamanho Não Serve para Todos". A escolha de um modelo de ADR é um trade-off estratégico entre expressividade (MADR) e eficiência (Nygard).

Para Praticantes: As equipes não devem adotar um modelo cegamente.
- Use Nygard para ambientes ágeis e de ritmo acelerado, projetos pequenos ou tarefas diárias onde velocidade e clareza são primordiais.
- Use MADR para sistemas de grande escala, decisões de alto risco ou contextos onde justificativa rigorosa e rastreabilidade são necessárias para prevenir a perda de conhecimento.
Para Pesquisadores: O estudo valida o uso do método DESMET FA para avaliação de modelos e destaca a necessidade de mais pesquisas sobre geração automatizada de ADR (por exemplo, usando LLMs) com base nessas esquemas estruturais.

Este trabalho fornece uma estratégia baseada em evidências para minimizar a sobrecarga da documentação enquanto maximiza a retenção de conhecimento arquitetônico, abordando diretamente a necessidade da indústria de documentação sistemática de decisões.