Evaluating Large Language Models for Detecting Architectural Decision Violations

Resumo Técnico: Avaliação de LLMs para Detecção de Violações de Decisões Arquiteturais

1. O Problema

A manutenção da qualidade de software depende da integridade das Decisões de Arquitetura (ADRs - Architectural Decision Records). Quando essas decisões são violadas (por erro ou negligência), ocorre a degradação arquitetural, aumentando a complexidade e o custo de manutenção.

O problema central é que a verificação de conformidade com ADRs é tradicionalmente um processo manual, propenso a erros e difícil de automatizar, pois as decisões costumam estar documentadas em linguagem natural (Markdown) e não em código executável. Ferramentas tradicionais de análise estática falham ao tentar capturar o conhecimento arquitetural implícito e semântico contido nessas documentações.

2. Metodologia

Os autores propuseram um estudo empírico em larga escala utilizando um pipeline de múltiplos modelos de linguagem (LLMs) para automatizar essa detecção.

• Dataset: Foram analisados 980 ADRs extraídos de 109 repositórios do GitHub. Os projetos foram filtrados para garantir relevância (projetos com mais de 28.696 linhas de código e mais de 1.184 commits).
• Pipeline de Modelos (Multi-model Pipeline):
  • LRM (Large Reasoning Model): O modelo Marco-o1 atuou como o detector primário, responsável por extrair informações e julgar a conformidade.
  • Validadores (V1, V2, V3): Três modelos (Mistral-Nemo, Qwen3 e Llama-3.1) atuaram de forma independente para validar o raciocínio do LRM.
• Técnicas de Processamento:
  • RAG (Retrieval-Augmented Generation): Para lidar com o limite de contexto, utilizaram um banco de dados vetorial (FAISS) com o modelo all-MiniLM-L6-v2 para recuperar os trechos de código mais relevantes para cada decisão.
  • Prompting: Utilizaram Chain of Thought (CoT) e few-shot learning para guiar o raciocínio dos modelos.
• Classificação de Julgamento: Os modelos deveriam classificar cada decisão em três categorias:
  1. Compliant (C): Código segue a decisão.
  2. Not Compliant (NC): Código viola explicitamente a decisão.
  3. Code is Insufficient to Answer (CIA): A decisão não pode ser avaliada apenas pelo código (ex: decisões organizacionais).
• Validação Humana: Uma amostra de 305 casos foi revisada por três especialistas humanos para estabelecer o ground truth (verdade fundamental).

3. Principais Contribuições

1. Avaliação de Larga Escala: Um dos primeiros estudos a testar a eficácia de LLMs especificamente na detecção de violações de ADR em centenas de projetos de código aberto.
2. Pipeline de Validação Robusto: Introdução de um método que combina detecção via RAG, validação cruzada entre múltiplos LLMs e revisão por especialistas humanos.
3. Taxonomia de Falhas: Identificação sistemática de quais tipos de decisões arquiteturais os modelos têm dificuldade em processar e quais são os padrões de erro cometidos.

4. Resultados

• Concordância (RQ1): Os modelos demonstraram uma concordância substancial (Fleiss’ Kappa de 0,724). A concordância foi muito maior em casos de conformidade (C) do que em casos de violação (NC) ou insuficiência (CIA).
• Acurácia (RQ2): Os modelos apresentaram alto desempenho. O Marco-o1 (LRM) obteve a maior acurácia (91,1%), seguido pelo Qwen3 (90,4%). Todos os modelos mantiveram acurácia acima de 80%.
  • O desempenho foi excelente para decisões "Compliant".
  • O desempenho foi mais baixo para a categoria "CIA", indicando dificuldade dos modelos em reconhecer quando a informação é insuficiente.
• Limitações e Falhas (RQ3):
  • Tipos de ADR difíceis: Decisões relacionadas a Infraestrutura e Implantação (42,39% dos erros) foram as mais problemáticas, pois exigem conhecimento de ferramentas como Docker, Kubernetes e CI/CD.
  • Categorias de Erro: Os erros principais foram Misinterpretação Semântica e Lógica (44,57%) e Incapacidade de Inferir Contexto Implícito (28,26%).

5. Significância

O estudo conclui que os LLMs são ferramentas poderosas para apoiar arquitetos na verificação de conformidade, especialmente para decisões que possuem uma representação direta no código-fonte. Eles podem automatizar revisões rotineiras e servir como um "sistema de alerta precoce".

No entanto, os LLMs ainda não substituem o especialista humano. Eles falham em decisões que dependem de contexto externo, infraestrutura complexa ou intenções subjetivas. A recomendação dos autores é o uso de fluxos de trabalho híbridos, onde o LLM atua como um assistente de triagem, mas a decisão final sobre violações arquiteturais complexas permanece sob supervisão humana.