Code Isn't Memory: A Structural Codebase Index Inside a Coding Agent

Resumo Técnico: Código não é Memória: Um Índice Estrutural de Base de Código dentro de um Agente de Codificação

Problema
Agentes de codificação intercalam cada vez mais Modelos de Linguagem de Grande Escala (LLMs) com mecanismos de recuperação sobre repositórios de trabalho para resolver tarefas de engenharia de software. No entanto, o impacto de estratégias de recuperação específicas — particularmente índices estruturais de base de código (combinando dados semânticos, léxicos e de grafo de chamadas) — permanece incerto. Avaliações anteriores confundem o desempenho da recuperação com engenharia de prompt, superfícies de ferramentas ou loops de controle ao comparar harnesses de agentes inteiros. Além disso, o alto custo de construção e operação de índices estruturais levanta uma questão crítica de implantação: o ganho de desempenho justifica o gasto, ou um simples "grep agêntico" é suficiente? Os benchmarks existentes também enfrentam desafios de integridade, incluindo vazamento de solução no texto da issue e memorização do modelo, exigindo protocolos de auditoria rigorosos.

Metodologia
Os autores conduziram um estudo de ablação causal dentro de um harness de agente de codificação fixo (SuperCoder) usando um único modelo fixo (Claude Opus 4.7) através de três sementes aleatórias. O estudo comparou três braços experimentais em 91 instâncias do SWE-PolyBench Verified e SWE-bench Pro:

1. SC-ON: O harness SuperCoder com um índice estrutural de base de código habilitado. Este índice inclui um índice vetorial (semântico), um índice de grafo (definições/arestas de chamada) e um índice léxico (BM25). Ele é construído uma vez por repositório e atualizado incrementalmente via diffs de árvore Merkle.
2. SC-OFF: O mesmo harness SuperCoder com as duas ferramentas de motor de contexto (codebase_search e codebase_graph) removidas do esquema de ferramentas. Todos os outros componentes (prompts, modelo, sandbox, demais ferramentas) permaneceram idênticos.
3. OpenCode: Um harness de código aberto independente usando grep agêntico (ripgrep) e leituras de arquivos como seu principal mecanismo de recuperação, servindo como um comparador entre harnesses.

Controles Experimentais Chave e Medidas de Integridade:

• Isolamento Causal: Ao alternar apenas as ferramentas do motor dentro do mesmo harness, o estudo isola o efeito do índice estrutural de outras variáveis.
• Auditoria de Vazamento: Um protocolo rigoroso de "falha fechada" (fail-closed) foi empregado. Isso incluiu a limpeza de git pré-execução para remover commits de correção de ouro (gold-fix) e descendentes, e uma auditoria pós-execução para detectar vazamento residual (ex: git show em commits históricos que tocavam arquivos de ouro). 26 células foram excluídas com base em um livro de exclusão público.
• Métricas de Localização: O estudo introduziu a View B para pontuação de localização. Diferente da "View A" (que conta todos os caminhos vistos, incluindo listas de resultados do motor), a View B conta apenas os camhos que o agente alcançou ativamente via grep, read ou edit. Isso evita inflar as pontuações de agentes que apenas recebem uma lista de candidatos sem interagir com eles.
• Análise Estatística: Os resultados foram analisados usando testes de postos sinalizados de Wilcoxon pareados nos valores de pass@1 por instância, calculados pela média entre as sementes.

Resultos Chave
O estudo relata melhorias estatisticamente significativas na localização e resolução quando o índice estrutural está ativo, sem incorrer em uma penalidade de custo por célula.

• Localização (View B acc@5):

  • SC-ON: 84,5%
  • SC-OFF: 44,3%
  • Delta: +39,6 pontos percentuais (pp) ($p < 0,0001$).
  • OpenCode: 75,3% (SC-ON supera OpenCode por +8,1 pp, $p=0,080$).
  • Observação: O índice melhora drasticamente a capacidade do agente de apresentar os arquivos corretos precocemente na trajetória, particularmente no topo do ranking (77,4% das células tinham o arquivo de ouro no rank 1 para SC-ON vs. 33,3% para SC-OFF).

• Resolução (Resolve %):

  • SC-ON: 50,4%
  • SC-OFF: 41,9%
  • Delta: +7,9 pp ($p = 0,003$).
  • OpenCode: 45,3% (SC-ON vs. OpenCode: $p = 0,087$).

• Custo e Esforço:

  • Custo por Célula: Diferença estatisticamente nula entre SC-ON e SC-OFF ($p = 0,73$).
  • Esforço: O SC-ON exigiu significativamente menos turnos (28,3 vs. 36,2, $p < 0,0001$) e menos tokens (10,1k vs. 11,1k, $p = 0,027$) para convergir.
  • Custo por Solução ($/solved): O SC-ON alcançou o menor custo em $2,30, comparado a $2,84 para SC-OFF e $2,92 para OpenCode.

• Heterogeneidade: Os benefícios do índice estrutural foram mais pronunciados em mudanças de múltiplos arquivos (3+ arquivos), onde a lacuna de localização entre SC-ON e SC-OFF atingiu 46,4 pp. Isso se alinha à intuição de que a alcançabilidade via grafo de chamadas é mais valiosa do que um simples grep quando as mudanças abrangem múltiplos arquivos.

Significância e Alegações
O artigo afirma fornecer a primeira ablação causal, controlada por modelo e auditada contra vazamentos de um índice estrutural de base de código dentro de um harness de agente de codificação. Suas principais contribuições são:

1. Evidência Causal: Demonstra que um índice estrutural melhora causalmente tanto a localização de arquivos quanto a resolução de tarefas, independentemente de engenharia de prompt ou mudanças de modelo.
2. Eficiência de Custo: Refuta a suposição de que índices estruturais são caros demais para operar. O estudo mostra que, embora o índice não reduza o custo por célula individual, ele reduz significativamente o custo por tarefa resolvida ao melhorar a taxa de sucesso e reduzir o número de turnos necessários.
3. Orientação de Implantação: Os autores concluem que a questão de implantação não é "o índice é muito caro?", mas sim "a carga de trabalho inclui mudanças em múltiplos arquivos onde o ranking estrutural compensa?".
4. Reprodutibilidade: Os autores liberam o livro de exclusão, os scripts de auditoria de vazamento, os extratores de localização (suportando tanto View A quanto View B) e o banco de dados completo de resultados para garantir que cada número relatado seja reproduzível.

O artigo mantém um tom modesto em relação às comparações entre diferentes harnesses (SC-ON vs. OpenCode), observando que, embora o SC-ON tenda favoravelmente, a significância estatística é marginal ($p \approx 0,08$). A alegação mais forte e robusta permanece a ablação causal dentro do mesmo harness (SC-ON vs. SC-OFF).