Resumo Técnico: Code2UML – LLMs Agentes com Engenharia de Contexto para Visualização Escalável de Software

Declaração do Problema

A documentação de software, particularmente diagramas UML atualizados, é frequentemente negligenciada devido ao alto custo e à natureza propensa a erros da criação manual. Embora os Modelos de Linguagem de Grande Escala (LLMs) ofereçam potencial para automatizar essa tarefa, eles enfrentam uma barreira fundamental de escalabilidade quando aplicados a bases de código do mundo real. As representações intermediárias (IR) de projetos de médio a grande porte frequentemente excedem as janelas de contexto efetivas até mesmo dos LLMs mais avançados. Abordagens ingênuas que tentam alimentar representações inteiras de bases de código em uma única invocação de LLM resultam em saídas truncadas, relações alucinadas e falha em capturar estruturas arquitetonicamente significativas. Além disso, a diversidade de tipos de diagramas UML (por exemplo, classe, sequência, implantação) requer regras de notação distintas e requisitos de informação, tornando as abordagens de geração "tamanho único" insuficientes.

Metodologia

O artigo apresenta o Code2UML, uma arquitetura agente projetada para gerar diagramas UML diretamente de repositórios de código fonte, respeitando as restrições de contexto dos LLMs. O sistema é construído sobre o Claude Agent SDK (utilizando Claude Sonnet 4.6) e opera através de um pipeline de quatro etapas:

1. Geração e Normalização de IR: Código fonte em Java, Python, JavaScript e PHP é analisado usando Tree-sitter para gerar uma Representação Intermediária (IR) JSON agnóstica à linguagem. Uma etapa de pós-processamento determinístico normaliza construções específicas de linguagem (por exemplo, modificadores de acesso, herança) em um esquema uniforme.
2. Engenharia de Contexto (Geração de Visão de IR): Para abordar os limites de contexto, o sistema emprega uma camada de compactação de IR determinística e ponderada por importância. Esta transformação puramente em Python converte IRs de projetos completos em visões específicas de diagramas garantidas para caber dentro das restrições de tokens (60 KB para caminho único, 100 KB para caminho profundo).
   • Mecanismo: Classifica elementos com base em pontuações de importância específicas ao tipo de diagrama (por exemplo, contagem de métodos, presença de herança) e aplica redução iterativa. Se o tamanho alvo for excedido, o orçamento de elementos é reduzido à metade.
   • Eficiência: Este processo não requer chamadas de LLM e é concluído em milissegundos.
3. Arquitetura Multi-Agente: O sistema utiliza uma hierarquia de cinco agentes especializados, cada um abordando uma subtarefa cognitiva distinta:
   • PlannerAgent: Decompõe o projeto em escopos lógicos (fluxos de trabalho/módulos) com base no tamanho do projeto.
   • AnalyzerAgent: Lê arquivos de código fonte específicos identificados pelo planejador para extrair contexto de alto sinal (cadeias de chamada, relações) para cada escopo. Múltiplos agentes são executados em paralelo.
   • DiagramAgent: Gera o código PlantUML final com base na visão de IR compactada (para visões arquitetônicas) ou no contexto enriquecido (para diagramas comportamentais/estruturais detalhados).
   • CorrectorAgent: Valida e corrige erros de sintaxe em arquivos .puml gerados usando conjuntos de regras específicos ao tipo de diagrama.
   • DependencyAnalyzerAgent: Analisa o código fonte de bibliotecas de terceiros independentemente.
4. Estratégia de Orquestração: O sistema utiliza uma estratégia de roteamento de dois níveis:
   • Caminho SINGLE: Para visões arquitetônicas (Componente, Implantação, Contexto do Sistema), invocando um único DiagramAgent.
   • Caminho DEEP: Para diagramas detalhados (Classe, Sequência, Atividade, Caso de Uso), invocando um pipeline de três fases (Planejador → Analisador → Diagrama) com correção em pipeline.

Contribuições Principais

O artigo reivindica três contribuições primárias:

1. Engenharia de Contexto Determinística: Uma abordagem inovadora que otimiza a carga de dados em vez de apenas o texto do prompt. Transforma IRs grandes em visões compactas e específicas de diagrama sem chamadas de LLM, garantindo que elementos arquitetonicamente significativos sobrevivam a taxas de compressão agressivas. Diferentemente da Geração Aumentada por Recuperação (RAG), isso opera sobre IRs estruturadas com pontuação determinística.
2. Hierarquia Multi-Agente Especializada: Um framework de cinco agentes que substitui abordagens baseadas em prompts monolíticos. Esta separação de preocupações permite a otimização independente de planejamento, análise, geração e validação, espelhando princípios estabelecidos de engenharia de software.
3. Avaliação Empírica Abrangente: Uma avaliação rigorosa em 12 repositórios de código aberto (abrangendo 4 linguagens e 2 ordens de grandeza em tamanho, de 31 a 4.578 entidades IR) e 7 tipos de diagramas UML, resultando em 84 observações avaliadas em cinco métricas automatizadas.

Resultados

O sistema foi avaliado em cinco métricas automatizadas: Validade Sintática, Recall de Entidade, Precisão de Relação, Qualidade Estrutural e Índice de Complexidade Estrutural (SCI).

• Validade Sintática: O sistema alcançou uma validade média de 91,5%. Diagramas de Componente e Implantação atingiram 100% de validade. Diagramas de Contexto do Sistema tiveram a menor validade (58,3%) devido a complexidades nos estereótipos do modelo C4.
• Precisão de Relação: A precisão média foi de 0,858, indicando que a vasta maioria das relações geradas conecta entidades realmente declaradas no código fonte, com alucinação mínima.
• Qualidade Estrutural: A pontuação média de qualidade foi de 81,7/100. Crucialmente, as pontuações de qualidade permaneceram estáveis através dos tamanhos de projeto (variando de 77,5 a 83,6), demonstrando que a camada de engenharia de contexto mantém com sucesso a qualidade do diagrama independentemente da escala.
• Recall de Entidade: O recall médio foi de 0,313. Isso é interpretado como uma priorização arquitetônica deliberada e não como uma falha; o sistema foca em estruturas significativas em vez de cobertura exaustiva. Diagramas de classe alcançaram o maior recall (0,445), enquanto diagramas de caso de uso foram os mais baixos (0,165), consistente com sua natureza abstrata.
• Consistência Cross-Linguagem: O desempenho foi altamente consistente entre Java, JavaScript, PHP e Python, com pontuações de qualidade variando apenas 0,6 pontos entre as linguagens.
• Escalabilidade: A análise de sensibilidade confirmou que a qualidade não se degrada conforme as contagens de entidades IR aumentam de 31 para 4.578.

Significado e Reivindicações

O artigo postula que o Code2UML aborda uma limitação crítica nas ferramentas atuais de engenharia de software baseadas em LLM: a incapacidade de processar e documentar de forma confiável bases de código de grande escala dentro das restrições de janela de contexto.

• Mudança Metodológica: O trabalho demonstra que combinar engenharia de contexto determinística com uma hierarquia de agentes especializados permite a geração de UML escalável, precisa e sintaticamente válida. Esta abordagem é apresentada como uma evolução necessária além de prompts monolíticos ou RAG simples para tarefas complexas em nível de repositório.
• Utilidade Prática: Ao produzir diagramas que são arquitetonicamente coerentes e sintaticamente válidos em múltiplas linguagens, o sistema contribui para melhorar a documentação de software automatizada e a compreensão arquitetônica.
• Limitações Modestas: Os autores reconhecem que métricas automatizadas não capturam a utilidade humana subjetiva. Eles notam que diagramas de Contexto do Sistema requerem extensões adicionais de conjuntos de regras para construções do modelo C4 e que a avaliação atual, embora ampla, é limitada a repositórios de código aberto. O sistema prioriza "significância arquitetônica sobre cobertura exaustiva", o que é uma escolha de design e não um defeito.

Em conclusão, o Code2UML apresenta um framework viável para escalar a visualização de software baseada em LLM, provando que, com a engenharia de contexto adequada e especialização de agentes, os LLMs podem lidar efetivamente com a complexidade de repositórios de software do mundo real.