Context Matters: Evaluating Context Strategies for Automated ADR Generation Using LLMs

Resumo Técnico: Estratégias de Contexto para Geração Automatizada de Registros de Decisão de Arquitetura (ADRs) usando LLMs

1. O Problema

Os Registros de Decisão de Arquitetura (ADRs) são fundamentais para preservar o raciocínio por trás das decisões de design de software, facilitando a integração de novos membros da equipe e prevenindo a perda de conhecimento ("vaporização do conhecimento"). No entanto, a adoção prática de ADRs é inconsistente devido ao alto custo de esforço manual para sua criação e manutenção.

Embora os Modelos de Linguagem de Grande Escala (LLMs) ofereçam a promessa de automatizar essa tarefa, pesquisas anteriores trataram a geração de ADRs como uma tarefa isolada, ignorando uma propriedade fundamental da arquitetura de software: a dependência de caminho (path dependency). Decisões arquiteturais não são tomadas no vácuo; elas são construídas sobre decisões anteriores, restrições tecnológicas e compromissos (trade-offs) já aceitos. A questão central deste estudo é: como a estratégia de apresentação do contexto histórico (ADRs passados) influencia a qualidade da geração de novos ADRs por LLMs?

2. Metodologia

O estudo foi conduzido como uma avaliação empírica rigorosa, seguindo o seguinte desenho experimental:

• Corpo de Dados: Os autores curaram e validaram um conjunto de dados massivo composto por 4.500+ ADRs sequenciais extraídos de 750 repositórios de código aberto. O processo envolveu limpeza manual para garantir integridade cronológica, removendo ruídos e inconsistências estruturais.
• Modelos Avaliados: Foram testados quatro modelos de LLMs heterogêneos para cobrir diferentes escalas e arquiteturas:
  1. Gemini-2.5-Pro (Proprietário, SOTA).
  2. Qwen3-235B (Open-source, estado da arte).
  3. GLM-4.6 (Open-source, arquitetura aumentada por grafos).
  4. Gemma-3-4B (Open-source, leve, executável localmente).
• Estratégias de Contexto (Variável Independente): O estudo comparou cinco abordagens de prompting para gerar o $N$-ésimo ADR, dado apenas o título do mesmo:
  1. Baseline (Sem Contexto): Apenas o título, sem histórico.
  2. All-N: Todo o histórico de ADRs anteriores.
  3. First-K: Apenas os primeiros $K$ ADRs (contexto fundacional).
  4. Last-K: Apenas os últimos $K$ ADRs (contexto recente).
  5. RAFG (Retrieval-Augmented Few-shot Generation): Recuperação baseada em similaridade semântica (usando embeddings) dos $K$ ADRs mais relevantes, independentemente da ordem cronológica.
• Métricas de Avaliação:
  • Automáticas: BERTScore (similaridade semântica), BLEU, ROUGE e METEOR (precisão e recall de n-gramas e estrutura).
  • Humanas: Revisão manual de uma subamostra para avaliar coerência e formato.
  • Eficiência: Contagem de tokens utilizados.

3. Principais Contribuições

1. Corpus Validado: Criação de um dos maiores conjuntos de dados sequenciais de ADRs validados cronologicamente, permitindo experimentos de "próximo passo" realistas.
2. Análise de Engenharia de Contexto: Demonstração de que a estratégia de seleção de contexto é um fator mais crítico para a qualidade da geração do que a escala do modelo em si.
3. Diretrizes Práticas: Definição de configurações padrão (defaults) para ferramentas de automação de documentação de arquitetura.

4. Resultados Chave

• Impacto do Contexto (RQ1): A inclusão de histórico arquitetural melhora drasticamente a qualidade da geração em comparação com a linha de base sem contexto. Modelos sem contexto tendem a gerar textos excessivamente verbosos e genéricos, enquanto o contexto grounded (ancorado) produz ADRs mais concisos e alinhados com o raciocínio humano.
• Eficiência da Janela Recente (RQ2):
  • O uso de todo o histórico (All-N) não oferece benefícios significativos em relação a janelas menores e é computacionalmente ineficiente.
  • A estratégia Last-K (Últimos K) com K=3 a 5 registros atingiu o melhor equilíbrio entre qualidade e eficiência.
  • Para a maioria dos modelos, o desempenho com Last-K (3 ou 5) foi estatisticamente comparável ou superior ao All-N, indicando que a trajetória arquitetural recente é um preditor mais forte do que a história fundacional completa.
• Recuperação Semântica vs. Cronológica (RQ3):
  • A estratégia RAFG (baseada em recuperação semântica) performou de forma paritária com Last-K em métricas agregadas.
  • No entanto, o RAFG mostrou vantagem em cenários de preocupações transversais (cross-cutting) ou dependências não sequenciais, onde decisões antigas (mas semanticamente relevantes) são mais importantes que as recentes.
  • A estratégia First-K (apenas o início) geralmente performou pior que Last-K, sugerindo que decisões fundacionais são menos relevantes para decisões imediatas em projetos em evolução.

5. Significado e Implicações

• Engenharia de Contexto > Escala do Modelo: O estudo desafia a noção de que apenas modelos maiores geram melhores resultados. Modelos menores e locais (como o Gemma-3-4B), quando devidamente ancorados com o contexto correto (Last-K), produzem ADRs de qualidade competitiva.
• Otimização de Custos e Latência: Para a maioria das aplicações de automação de ADRs, não é necessário implementar sistemas complexos de RAG (Retrieval-Augmented Generation) ou carregar todo o histórico. Uma janela deslizante simples dos últimos 3-5 registros é suficiente e mais escalável.
• Higiene de Dados: A qualidade dos ADRs gerados depende da qualidade dos ADRs de referência. O estudo identificou que ADRs humanos que dependem de conteúdo externo (links para wikis, issues) penalizam a avaliação automática, pois o LLM gera um documento autocontido. Isso sugere que a automação pode incentivar práticas de documentação mais explícitas e autocontidas.
• Futuro da Pesquisa: Recomenda-se o desenvolvimento de estratégias híbridas (recência + semântica) e a criação de conjuntos de dados de referência mais limpos e completos para melhor avaliação.

Conclusão: A automação eficaz de ADRs depende menos do poder bruto do modelo e mais de uma engenharia de contexto inteligente. A estratégia recomendada para a maioria dos casos é o uso de uma janela de contexto recente (Last-K, 3-5 itens), reservando abordagens de recuperação semântica (RAFG) apenas para cenários arquiteturalmente complexos e não lineares.