Quanta Estrutura Estática os Agentes de Código Precisam? Um Estudo sobre Ancoragem Determinística

Resumo

Agentes de código baseados em LLM navegam em repositórios por meio de busca por palavras-chave, mas ignoram as relações estruturais — como grafos de chamada, hierarquias de herança e dependências de configuração — que definem como o software realmente funciona. Isso torna a navegação do agente estocástica e difícil de reproduzir entre execuções. Investigamos se a análise estática leve pode fornecer âncoras determinísticas para esses agentes: fatos estruturais estáveis injetados como comentários em texto simples que restringem a exploração probabilística e tornam a navegação mais previsível. Partindo de uma linha de base forte, o Codex da OpenAI, injetamos sistematicamente granularidades variadas de anotações estruturais e medimos seus efeitos sobre a localização, o comportamento da trajetória e a estabilidade entre execuções. Nosso estudo identifica o que chamamos de efeito de ancoragem determinística: a estrutura estática ajuda menos por tornar os agentes "mais inteligentes" e mais por disciplinar e tornar reprodutível sua navegação. Três observações sustentam esse achado: (1) A ancoragem funciona: a topologia leve de chamada/herança melhora a localização ao nível de função (+2,2 p.p. Func@5) e encurta as trajetórias (-1,6 rodadas de interação); (2) A ancoragem é sensível à escala: a granularidade e a direcionalidade ótimas dependem das características do repositório, onde semânticas mais densas apresentam retornos decrescentes e projetos com muitos hubs se beneficiam de links apenas inversos que expõem "quem me chama" sem arestas diretas; (3) A ancoragem estabiliza: as tags elevam a taxa de seguimento de links de 0,15–0,18 para 0,21–0,24, reduzem aproximadamente pela metade a variância entre execuções e melhoram a confiabilidade de execução única (Pass@1 +3,4 p.p.) em repositórios de médio porte, ao custo de aproximadamente 10% mais tokens de entrada. Essas observações sugerem diretrizes práticas: usar topologia leve como padrão em projetos médios, podar arestas diretas em repositórios grandes e reservar tags densas para casos de dependência implícita.

English

LLM-based code agents navigate repositories through keyword search but miss the structural relationships, such as call graphs, inheritance hierarchies, and configuration dependencies, that define how software actually works. This makes agent navigation stochastic and difficult to reproduce across runs. We investigate whether lightweight static analysis can provide deterministic anchors for these agents: stable structural facts injected as plain-text comments that constrain probabilistic exploration and make navigation more predictable. Starting from a strong baseline, Codex from OpenAI, we systematically inject varying granularities of structural annotations and measure their effects on localization, trajectory behavior, and run-to-run stability. Our study identifies what we call the deterministic anchoring effect: static structure helps less by making agents "smarter" and more by making their navigation disciplined and reproducible. Three observations support this finding: (1) Anchoring works: lightweight call/inheritance topology improves function-level localization (+2.2pp Func@5) and shortens trajectories (-1.6 interaction rounds); (2) Anchoring is scale-sensitive: the optimal granularity and directionality depend on repository characteristics, where denser semantics show diminishing returns and hub-heavy projects benefit from inverse-only links that expose "who-calls-me" without forward edges; (3) Anchoring stabilizes: tags raise link-following rate from 0.15-0.18 to 0.21-0.24, roughly halve run-to-run variance, and improve single-run reliability (Pass@1 +3.4 pp) on medium-scale repositories, at the cost of roughly 10% more input tokens. These observations suggest practical guidelines: default to lightweight topology on medium projects, prune forward edges in large repositories, and reserve dense tags for implicit-dependency cases.