SWE-Adept: An LLM-Based Agentic Framework for Deep Codebase Analysis and Structured Issue Resolution

O artigo apresenta o SWE-Adept, um framework baseado em agentes de LLM que supera os desafios da engenharia de software em nível de repositório ao combinar uma busca em profundidade dirigida por agentes para localização precisa de código com um processo de resolução estruturado e controlado por versão, alcançando taxas de resolução de problemas superiores às abordagens anteriores.

O essencial

Imagine que você tem um livro de receitas gigante, com milhares de páginas, e alguém te diz: "Tem um erro nesta receita de bolo, mas não sabemos onde exatamente está o problema, e precisamos consertá-lo sem estragar o resto do livro".

Fazer isso manualmente é difícil. Fazer uma Inteligência Artificial (IA) fazer isso sozinha é ainda mais difícil, porque a IA pode se perder nas milhares de páginas ou tentar consertar coisas erradas e criar mais bagunça.

O artigo "SWE-Adept" apresenta uma nova maneira de usar IAs para resolver esses problemas de programação. Eles criaram um sistema com dois "funcionários" inteligentes (agentes) que trabalham juntos, cada um com uma função específica, como se fosse uma equipe de detetives e mecânicos.

Aqui está a explicação simples, usando analogias do dia a dia:

1. O Problema: A Biblioteca Infinita

Os códigos de programas modernos são como bibliotecas gigantescas. Quando um bug (erro) aparece, a IA precisa:

1. Encontrar o livro e a página exata onde o erro está (Localização).
2. Consertar o texto sem apagar o resto do livro e garantindo que a história faça sentido (Resolução).

IAs comuns costumam se perder tentando ler tudo de uma vez ou fazem consertos aleatórios que pioram a situação.

2. A Solução: A Dupla Dinâmica (SWE-Adept)

O SWE-Adept divide o trabalho em dois agentes especializados:

🕵️‍♂️ Agente 1: O Detetive (Localização)

Este agente não lê o livro inteiro. Ele usa uma técnica inteligente chamada "Busca em Profundidade Dirigida".

• A Analogia: Imagine que você precisa achar uma palavra específica em um dicionário gigante. Em vez de ler página por página, você vai direto à letra "A", depois ao "B", e assim por diante, ignorando as seções que não têm nada a ver com o que você procura.
• Como funciona: O Detetive olha para o erro descrito, identifica palavras-chave (como nomes de funções ou arquivos) e navega apenas pelas conexões relevantes. Ele usa uma "lista de verificação" para não se perder.
• O Truque: Ele faz uma filtragem em duas etapas. Primeiro, ele olha apenas o "sumário" ou o esqueleto do código (muito leve) para escolher os melhores candidatos. Só depois, quando já está quase certo, ele lê o texto completo. Isso economiza a "memória" da IA e evita confusão.

🔧 Agente 2: O Mecânico (Resolução)

Depois que o Detetive aponta onde está o problema, o Mecânico entra em ação.

• O Problema Antigo: IAs antigas tentavam consertar o código de uma vez só, ou faziam várias tentativas bagunçadas, sem saber o que funcionou ou o que falhou. Era como tentar consertar um carro sem anotar quais peças você tirou; se algo der errado, você não sabe como voltar ao estado original.
• A Solução do Mecânico: O SWE-Adept usa um sistema de "Checkpoints" (Pontos de Salvação), como em um jogo de vídeo game.
  • Planejamento: Antes de mexer em algo, o Mecânico cria um plano (uma lista de tarefas).
  • Salvamento: A cada pequena mudança que ele faz, ele salva o estado do código em um "ponto de salvamento" (usando uma ferramenta chamada Git, que é como um controle de versão).
  • Ramificação (Branching): Se o Mecânico acha que há duas formas de resolver o problema, ele cria duas "realidades paralelas" (ramos). Ele testa uma. Se der errado, ele volta ao último ponto de salvamento e tenta o outro ramo. Nada é perdido.
  • Memória Compartilhada: Tudo o que ele faz é registrado em uma "memória de trabalho" organizada. Ele sabe exatamente qual passo funcionou e qual falhou.

3. O Resultado: Menos Erros, Mais Sucesso

Os autores testaram esse sistema em problemas reais de programação (usando bancos de dados chamados SWE-Bench).

• O que aconteceu: O SWE-Adept foi muito melhor do que os sistemas anteriores. Ele encontrou os erros com mais precisão e conseguiu consertá-los sem criar novos problemas.
• A Melhoria: Eles conseguiram aumentar a taxa de sucesso em até 4,7%. Parece pouco, mas em programação, onde um erro pode quebrar um sistema inteiro, isso é uma vitória enorme.

Resumo Final

O SWE-Adept é como ter uma equipe onde:

1. Um Detetive usa um mapa inteligente para achar o problema rapidamente, sem ler tudo à toa.
2. Um Mecânico conserta o problema com um plano, salvando cada passo para poder voltar atrás se errar, garantindo que o conserto final seja perfeito.

Isso torna a Inteligência Artificial muito mais confiável para trabalhar com códigos complexos do mundo real, agindo como um engenheiro de software sênior, e não apenas como um iniciante que tenta a sorte.

Resumo técnico

Resumo Técnico: SWE-Adept

1. O Problema

Embora os Grandes Modelos de Linguagem (LLMs) demonstrem desempenho robusto em tarefas de programação isoladas (funções ou arquivos únicos), eles ainda enfrentam dificuldades significativas na engenharia de software em nível de repositório (SWE). Os principais desafios identificados são:

• Localização de Problemas Complexa: Repositórios de código reais são vastos (médias de >3.000 arquivos) e possuem dependências cruzadas densas. Localizar a raiz de um erro exige navegar por essas dependências sem exceder o limite de contexto do LLM. Métodos anteriores frequentemente injetam informações irrelevantes no contexto ou usam travessias cegas (como busca em largura), degradando a precisão.
• Resolução de Problemas Não Estruturada: A correção de bugs raramente é uma edição única ("one-shot"). Requer iteração, validação baseada em testes e gerenciamento de estado. Abordagens anteriores muitas vezes operam em loops de "pensar e editar" desorganizados, sem planejamento explícito ou mecanismos de checkpointing (pontos de salvamento). Isso torna difícil reverter edições falhas ou explorar soluções alternativas de forma sistemática, levando a estados de trabalho confusos.

2. Metodologia: O Framework SWE-Adept

O SWE-Adept é um framework baseado em agentes LLM que divide o processo de resolução de problemas em dois agentes especializados operando em janelas de contexto separadas, integrados por uma memória de trabalho compartilhada.

A. Representação do Códigobase e Indexação

• Indexação de Nível de Definição: O repositório é segmentado em unidades de código finas (classes e funções) usando o tree-sitter.
• Árvore de Estrutura de Código: É construída uma árvore onde os nós são unidades de código e as arestas representam relações de "contém" ou "invoca". Diferente de grafos globais monolíticos, o SWE-Adept armazena listas de adjacência leves dentro dos metadados de cada unidade para eficiência na recuperação.

B. Agente de Localização de Problemas (Issue Localization Agent)
Este agente é responsável por navegar no repositório e identificar os arquivos e funções relevantes para o erro.

• Travessia Dirigida por Agente (Agentic Traversal): Em vez de uma expansão cega, o agente realiza uma Busca em Profundidade (DFS) dirigida. Ele usa ferramentas de busca para obter apenas informações estruturais leves (esqueletos de código, metadados de localização) e decide recursivamente qual caminho de dependência explorar.
• Filtragem em Duas Etapas:
  1. Pré-filtragem: Usa heurísticas baseadas em esqueletos de código e metadados para descartar caminhos irrelevantes, economizando tokens.
  2. Refinamento: Carrega o conteúdo completo apenas para os candidatos finalistas para uma análise profunda e reclassificação.

C. Agente de Resolução de Problemas (Issue Resolution Agent)
Este agente implementa as correções com base nas localizações fornecidas.

• Planejamento Adaptativo e Hipóteses: O agente formula hipóteses de correção (soluções alternativas). Para cada hipótese, ele cria uma lista de tarefas (to-do list) dinâmica que se expande conforme o feedback dos testes revela casos de borda não cobertos.
• Controle de Versão Baseado em Checkpoints (Tool-Memory Interface):
  • O agente utiliza duas famílias de ferramentas CLI: hypothesis_plan (para gerenciar hipóteses e tarefas) e hypothesis_git (para controle de versão).
  • Memória de Trabalho: Um repositório compartilhado armazena checkpoints de estado do código (hashes Git e mensagens de commit) indexados por etapas semânticas (ex: "após corrigir a função X").
  • Ramificação e Reversão: O agente pode criar branches separadas para testar hipóteses concorrentes. Se uma hipótese falha em etapas posteriores, ele pode reverter com precisão para um checkpoint anterior (usando referências semânticas, não hashes brutos) e tentar uma nova direção, mantendo o histórico limpo.

3. Principais Contribuições

1. Framework Dual-Agent: Separação clara entre localização e resolução, permitindo gerenciamento de contexto otimizado para cada tarefa.
2. Travessia DFS Dirigida por Agente: Uma estratégia de navegação que minimiza o ruído no contexto, explorando dependências de forma seletiva e eficiente.
3. Interface Ferramenta-Memória para Controle de Versão: Um mecanismo inovador onde o agente gerencia checkpoints de código via uma memória estruturada, permitindo operações de controle de versão confiáveis (ramificação, reversão, comparação) em cenários de longo prazo, superando a fragilidade de comandos Git brutos executados diretamente pelo LLM.

4. Resultados Experimentais

O framework foi avaliado nos benchmarks SWE-Bench Lite e SWE-Bench Pro, utilizando modelos LLM proprietários (GPT-5.2 e Claude-Sonnet-4.5).

• Localização de Problemas: O SWE-Adept superou consistentemente as abordagens anteriores (como SWE-agent, RepoGraph, OrcaLoca).
  • Melhorou a precisão de localização em nível de função (Func Acc@5) em até 5,4% no SWE-Bench Lite e 4,0% no SWE-Bench Pro em comparação com a melhor base.
  • Consumiu menos tokens que abordagens baseadas em grafos devido ao gerenciamento eficiente de contexto.
• Resolução de Problemas (End-to-End):
  • Aumentou a taxa de resolução final em até 4,7% no SWE-Bench Pro.
  • No SWE-Bench Lite, alcançou taxas de resolução de 71,3% (Claude) e 59,0% (GPT), superando significativamente os baselines.
• Análise de Falhas: A ablação mostrou que a combinação de localização precisa e resolução estruturada é crucial. O uso de comandos Git brutos (sem a camada de abstração e memória do SWE-Adept) resultou em desempenho inferior em tarefas complexas devido a erros de rastreamento de estado.

5. Significado e Impacto

O SWE-Adept representa um avanço significativo na automação de engenharia de software. Ao introduzir gerenciamento sistemático de estado e navegação contextual inteligente, ele resolve duas das maiores limitações dos agentes de IA atuais: a alucinação de contexto em repositórios grandes e a incapacidade de recuperar-se de erros de edição em loops longos.

A arquitetura proposta demonstra que a separação de preocupações (localização vs. resolução) e o uso de memória estruturada para controle de versão permitem que LLMs operem de forma mais confiável em tarefas de engenharia de software de longo prazo, aproximando-se da capacidade de um desenvolvedor humano experiente em depuração e manutenção de código.