CodeScout: Contextual Problem Statement Enhancement for Software Agents

O artigo apresenta o CodeScout, uma abordagem de refinamento de consultas que melhora em 20% a taxa de resolução de tarefas de desenvolvimento de software em agentes de IA ao transformar solicitações mal definidas em problemas estruturados através de uma pré-análise contextual do código, sem exigir modificações nos scaffolds existentes.

O essencial

Imagine que você é um detetive de software (um agente de IA) contratado para consertar um bug em um código complexo. O problema é que o cliente (o desenvolvedor humano) te entregou um bilhete muito vago: "O sistema está estranho, arrume isso!".

Sem um mapa claro, o que acontece? O detetive começa a revirar a casa inteira, abrindo gavetas aleatórias, testando teorias sem sentido e gastando horas tentando a mesma solução que não funciona. Ele se perde, fica confuso e, no final, não resolve o problema.

É exatamente esse o cenário que o CodeScout veio resolver.

O Que é o CodeScout?

Pense no CodeScout como um detetive sênior ou um arquivista experiente que trabalha antes do detetive principal começar o caso.

Em vez de deixar o agente de IA começar a trabalhar com um bilhete vago, o CodeScout pega esse bilhete, vai até a biblioteca de arquivos do projeto (o repositório de código), lê os documentos relevantes, entende o contexto e reescreve o bilhete para o agente.

Ele transforma um pedido vago em um plano de missão detalhado, que inclui:

• O que exatamente está errado (com detalhes técnicos).
• Como reproduzir o erro (passo a passo).
• Onde procurar (quais arquivos e funções são os prováveis culpados).
• Dicas de como consertar (sugestões inteligentes baseadas no que ele já viu).

A Analogia da "Caixa Preta" vs. "Mapa do Tesouro"

• Sem CodeScout: É como pedir para alguém encontrar uma agulha em um palheiro, mas você só diz: "Tem uma agulha aqui, ache-a!". A pessoa entra no palheiro, revira tudo, fica cansada e desiste.
• Com CodeScout: É como dar a mesma pessoa um mapa do tesouro que diz: "A agulha está escondida no terceiro fardo de palha, perto da janela, e você provavelmente vai precisar de uma lupa para vê-la". A pessoa vai direto ao ponto, economiza tempo e encontra a agulha rapidamente.

Como Funciona na Prática?

O processo do CodeScout tem três etapas simples, como se fosse uma equipe de investigação:

1. O Escoteiro (Scoping): Ele olha para o problema e para a estrutura do projeto e diz: "Ei, olhe aqui! Esses 5 arquivos parecem ser os mais importantes para este caso". Ele filtra o que é irrelevante.
2. O Analista (Analysis): Ele vai até esses arquivos, lê o código e diz: "Olha, aqui nesta função, o código está fazendo algo errado. Aparentemente, o desenvolvedor esqueceu de passar uma informação importante. Aqui está uma pista de como corrigir".
3. O Redator (Synthesis): Ele pega todas essas descobertas e escreve um novo relatório para o agente de IA. Esse novo relatório é rico em detalhes, tem dicas de onde olhar e evita que o agente perca tempo revirando o lugar errado.

Por Que Isso é Importante?

O papel mostra que, quando os agentes de IA recebem esses "bilhetes melhorados" (os problemas contextualizados), eles:

• Resolvem mais bugs: A taxa de sucesso aumentou em cerca de 20%.
• Gastam menos energia: Eles não precisam dar 20 passos para achar o que poderiam achar em 6.
• Não ficam "teimosos": Em vez de tentar a mesma solução errada repetidamente, eles seguem as dicas inteligentes do CodeScout.

A Grande Lição

A descoberta mais interessante é que não precisamos tornar o agente de IA mais inteligente para ele resolver problemas difíceis. Em vez disso, precisamos apenas melhorar a qualidade da pergunta que fazemos a ele.

É como se você tivesse um aluno muito inteligente, mas que não sabe estudar porque o professor deu uma pergunta confusa. O CodeScout não muda o aluno; ele apenas reescreve a pergunta para que o aluno possa usar todo o seu potencial.

Em resumo: O CodeScout é a ponte entre a intenção humana (que muitas vezes é vaga) e a execução da máquina (que precisa de precisão), garantindo que a IA não perca tempo procurando a agulha no palheiro, mas sim saiba exatamente onde ela está.

Resumo técnico

1. O Problema

As ferramentas de assistência de código baseadas em IA (agentes de software) frequentemente falham não devido à falta de capacidade de raciocínio dos modelos de linguagem (LLMs), mas devido à qualidade deficiente das solicitações de entrada (enunciados de problemas).

• Solicitações Subespecificadas: Desenvolvedores humanos tendem a fornecer descrições concisas e dependentes de contexto, omitindo passos de reprodução, detalhes técnicos ou expectativas claras, assumindo um conhecimento compartilhado do código que o agente não possui.
• Padrões de Falha: Análises recentes mostram que agentes falham em solicitações mal definidas através de dois comportamentos principais:
  1. Sobre-exploração (Over-exploration): O agente fica sobrecarregado pelo contexto, explorando caminhos irrelevantes sem chegar à raiz do problema.
  2. Comportamento Teimoso: O agente aplica repetidamente a mesma correção sem testes adequados ou evolução, sem entender a intenção do usuário ou a estrutura do código.
• Consequência: Isso leva a trajetórias de execução longas, não convergentes e a resultados subótimos, onde o agente gasta muitos recursos (tokens e tempo) sem resolver o bug.

2. Metodologia: CodeScout

O CodeScout é uma abordagem de refinamento de consultas contextuais que transforma solicitações vagas de usuários em enunciados de problemas abrangentes e acionáveis. A inovação central é realizar uma pré-exploração estruturada do repositório de código antes da execução do agente, sem modificar a arquitetura subjacente do agente.

O pipeline do CodeScout opera em três estágios principais:

1. Construção do Grafo de Conhecimento do Repositório:

   • O sistema analisa o repositório para construir um grafo direcionado $G(R)$ que representa a estrutura do código e as relações semânticas (classes, funções, imports, herança) usando uma árvore de sintaxe abstrata (AST).

2. Delimitação de Contexto de Alto Nível (High Level Scoping):

   • Um agente LLM analisa o enunciado original do problema e o grafo do repositório para identificar alvos de exploração relevantes (arquivos, classes, funções).
   • O objetivo é selecionar até 15 entidades mais prováveis de conterem o bug, baseando-se em menções diretas, padrões de depuração e relações estruturais.

3. Análise de Contexto Granular e Síntese do Problema:

   • Para cada alvo selecionado, o sistema recupera o código e realiza uma análise estruturada para extrair:
     • Avaliação do papel do código no problema.
     • Dicas de localização da correção (com estimativas de confiança).
     • Insights técnicos e hipóteses alternativas.
   • Filtragem: Apenas insights com alta relevância são mantidos.
   • Síntese: O sistema gera um Enunciado de Problema Augmentado (Paug) que inclui:
     • Descrição do problema enriquecida com insights técnicos.
     • Passos de reprodução detalhados.
     • Comportamento esperado.
     • Dicas de Exploração: Arquivos e classes específicos a examinar.
     • Dicas de Correção: Locais de alta confiança e sugestões de implementação.

3. Principais Contribuições

1. CodeScout como Framework de Refinamento: Uma abordagem sistemática que melhora a qualidade da entrada para agentes de software através de análise consciente do repositório, demonstrando uma melhoria de 20% nas taxas de resolução no benchmark SWEBench-Verified.
2. Validação Empírica Robusta: O método foi testado em múltiplos scaffolds de agentes (SWE-agent, OpenHands, Mini-SWE-Agent) e modelos LLM (DeepSeek R1, GPT-5-mini, Qwen3 Coder), mostrando ganhos consistentes de desempenho.
3. Análise de Trajetória e Custo: O estudo revela que o refinamento contextual reduz trajetórias não convergentes. Além disso, demonstra uma dinâmica de custo-eficiência: modelos menores podem ser usados para realizar a pré-exploração e melhorar o desempenho de modelos maiores, ou modelos fortes podem "elevar o piso" de desempenho de agentes mais fracos.

4. Resultados Experimentais

A avaliação foi realizada no conjunto de dados SWEBench-Verified:

• Melhoria na Taxa de Resolução: O CodeScout resolveu até 27 problemas adicionais em comparação com a linha de base padrão (sem augmentação).
• Ganhos Relativos:
  • DeepSeek R1: +9.6% (11 problemas a mais).
  • GPT-5-mini: +7.7% (15 problemas a mais).
  • Qwen3 Coder: +13.1% (24 problemas a mais).
• Precisão de Localização: O CodeScout melhorou a capacidade dos agentes de localizar os arquivos e funções corretos para a correção, especialmente em modelos com capacidades de raciocínio agêntico mais fracas.
• Eficiência de Trajetória:
  • Casos de sucesso: Um problema que exigia 21 passos de exploração cega foi resolvido em apenas 6 passos com o enunciado aprimorado.
  • Redução de ruído: As trajetórias tornaram-se mais focadas, com menos chamadas de ferramentas genéricas (como ls ou grep aleatórios) e mais ações direcionadas.
• Análise de Custo: Embora o processo de augmentação adicione um custo inicial (tokens e chamadas de API), o custo por problema resolvido diminui para a maioria dos modelos, pois evita o desperdício de tokens em explorações longas e infrutíferas.

5. Significância e Conclusão

O trabalho do CodeScout muda o paradigma de como os agentes de IA interagem com o código:

• Do "Agir" para o "Olhar": Em vez de esperar que o agente "pule" diretamente para a solução, o CodeScout força uma fase de compreensão estruturada antes da execução.
• Suplemento, não Substituição: A abordagem funciona como um pré-processador plug-and-play que melhora agentes existentes sem exigir reengenharia de seus scaffolds internos.
• Importância da Formulação do Problema: Os resultados sugerem que investir em computação para a compreensão prévia do problema é tão crucial quanto o aumento da capacidade dos modelos de linguagem. A qualidade da especificação do problema é um gargalo crítico que, quando resolvido, libera o potencial real dos agentes de IA em engenharia de software.

Em suma, o CodeScout demonstra que a refinamento contextual sistemático é uma direção promissora e eficaz para tornar a assistência de código por IA mais confiável, eficiente e capaz de resolver problemas complexos em repositórios reais.