🤖 machine learning

What Context Does a Coding Agent Actually Need to Act?

Este artigo demonstra que, para agentes de codificação que editam código, o contexto essencial é estritamente limitado aos arquivos específicos sendo modificados, uma vez que resumos em linguagem natural e o conteúdo circundante dos arquivos contribuem de forma negligenciável para a resolução de problemas em comparação ao próprio código-fonte, revelando também um nível de ruído significativo nos resultados de benchmarks causado pela inferência não determinística de API.

Autores originais: Brian Sam-Bodden

Publicado 2026-07-14✓ Author reviewed ⓘ

📖 5 min de leitura🧠 Leitura aprofundada

CC BY 4.0

Autores originais: Brian Sam-Bodden

Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine que você está tentando consertar uma torneira com vazamento em um arranha-céu enorme de 100 andares. Você não precisa ler as plantas de todo o edifício, o cardápio da cafeteria ou os registros de segurança para encontrar a chave inglesa. Você só precisa saber exatamente qual cano está pingando e ver a área imediata ao redor dele.

Essa é a lição surpreendente deste novo estudo sobre "agentes de codificação" — os bots de IA que escrevem e corrigem software. Por muito tempo, o mundo da tecnologia assumiu que esses bots precisavam engolir o código inteiro de um projeto (às vezes milhões de linhas) em seu "cérebro" para fazer o trabalho. O pensamento era: "Mais contexto é sempre melhor."

Mas este artigo diz: Pare de entupir o cérebro. Acontece que, para o ato real de corrigir um código, a IA precisa de quase nada além das linhas específicas que ela está prestes a alterar.

O "Encontrar" vs. O "Agir"

Os pesquisadores dividiram o problema em duas partes:

O Encontrar: Localizar o código quebrado.
O Agir: Realmente consertar o código uma vez que você o encontrou.

Para testar isso, eles usaram um "mapa mágico" (um oráculo) para dizer à IA exatamente onde o código quebrado estava. Isso significava que a IA não precisava adivinhar onde procurar; ela só precisava focar em como consertar. Eles então deram à IA diferentes "visões" desse código para ver o que funcionava melhor.

A Grande Decepção: Resumos Não Funcionam

Uma ideia popular era: "Vamos apenas dar à IA um resumo em linguagem natural do código, como uma sinopse de um livro."

O Teste: Eles pediram à IA para responder perguntas complicadas sobre como o código se comporta, usando ou o código-fonte completo ou um resumo escrito por uma IA superinteligente (um "modelo de fronteira").
O Resultado: O código-fonte completo acertou 27 de 45 perguntas. Os resumos? Acertaram apenas 4 de 45.
A Reviravolta: Não importava se o resumo foi escrito pela IA mais inteligente do mundo ou por um modelo minúsculo e básico. Ambos falharam igualmente. O problema não era o escritor; o problema era o formato. Um resumo simplesmente não consegue carregar os detalhes "comportamentais" específicos necessários para corrigir um erro. É como tentar consertar o motor de um carro lendo um folheto turístico sobre o carro; o folheto é legal, mas não diz qual parafuso está solto.

O "Esqueleto" vs. O "Corpo Inteiro"

Em seguida, eles testaram se a IA precisava do código completo e "carnudo" ou apenas do "esqueleto" (a estrutura, como nomes de funções e assinaturas).

A Configuração: Eles pegaram 70 problemas de codificação do mundo real. Para alguns, deram à IA os arquivos completos. Para outros, deram apenas o "esqueleto" (diagramas UML e assinaturas) ou uma versão "manter/descartar" (mantendo apenas as partes essenciais e deletando o resto).
O Resultado: As versões "esqueleto" e "manter/descartar" resolveram tantos problemas quanto os arquivos completos. Na verdade, o método "manter/descartar" resolveu um pouco mais (25 de 70) do que os arquivos completos (19 de 70), embora a diferença fosse pequena o suficiente para ser apenas sorte.
O Custo: Aqui está o detalhe crucial. Resolver um problema com os arquivos completos custou à IA 94.000 tokens (uma unidade de texto). Resolver o mesmo problema com o método comprimido "manter/descartar" custou apenas 19.000 tokens. Esse é um valor de economia massivo — cerca de 3 a 3,7 vezes mais barato — sem perda de desempenho.

O Aviso do "Ruído"

Os pesquisadores também descobriram algo estranho e importante: mesmo quando executavam exatamente o mesmo teste com as mesmas configurações, a IA às vezes dava respostas diferentes. Cerca de 9% das vezes, o resultado mudava entre as execuções. Isso significa que, se você vir uma diferença minúscula entre dois métodos (como uma melhoria de 2%), pode ser apenas ruído aleatório, não um avanço real.

A Conclusão

O artigo conclui que, para a tarefa específica de corrigir código, menos é mais.

O que funciona: Dar à IA as linhas exatas de código que ela precisa editar, destiladas até seus elementos essenciais.
O que não funciona: Inundar a IA com resumos, históricos de arquivos completos ou diagramas estruturais complexos.
O Veredito: O "sinal" vive no próprio código, não na história que contamos sobre o código. Ao cortar o excesso, podemos corrigir erros por uma fração do custo, sem precisar ler a biblioteca inteira para consertar uma única torneira com vazamento.

Os autores são muito cuidadosos ao dizer que isso se aplica a correções de "tentativa única" (onde a IA tenta uma vez e não tem a chance de reler ou pedir ajuda). Mas para esse momento específico e de alto risco de edição, os dados são claros: você não precisa da biblioteca inteira; você só precisa da página certa.

Resumo Técnico: Qual Contexto um Agente de Codificação Realmente Precisa para Agir?

Declaração do Problema

Os agentes de codificação modernos possuem janelas de contexto grandes o suficiente para conter repositórios inteiros de código, mas evidências sugerem que grande parte deste contexto não é utilizado. Embora a geração aumentada por recuperação (RAG) e o escalonamento sofisticado sejam frequentemente empregados para gerenciar o contexto, benchmarks como o ContextBench indicam que esses sistemas complexos mal superam baselines triviais. A questão central abordada não é quanto contexto um agente pode conter, mas sim qual o contexto mínimo necessário para que um agente edite o código com sucesso e em qual representação.

Os autores distinguem dois subproblemas frequentemente confundidos no design de agentes:

Encontrar (Find): Localizar as funções ou arquivos específicos onde o trabalho deve ocorrer.
Agir (Act): Dado o local, possuir informações suficientes para realizar a edição corretamente.

Este estudo isola a fase de Agir (Act). Ao manter a localização fixa (usando um oráculo para fornecer os arquivos exatos de "ouro" a serem editados), os autores variam apenas a representação desse código para determinar o contexto mínimo necessário para a resolução.

Metodologia

Instrumento Experimental: `resolve@cost`

Os autores construíram um instrumento auditado para medir as taxas de resolução em relação aos custos de contexto.

Dataset: 70 instâncias de múltiplos arquivos do SWE-bench Verified (após excluir uma instância onde o patch de ouro falhou em sua própria validação de ambiente).
Localização por Oráculo: Para isolar os efeitos de representação dos erros de recuperação, cada "braço" experimental (condição) recebe exatamente o mesmo conjunto de arquivos de ouro a serem editados. A única variável é como o conteúdo desses arquivos é renderizado.
Agente: Uma execução de disparo único (single-shot) do Claude Sonnet 4.6 (Temperatura 0, max 8000 tokens). O agente produz blocos SEARCH/REPLACE, que são convertidos em diffs unificados por um construtor determinístico (difflib) e verificados via um harness Docker.
Validação:
- Portão de Expressibilidade: Antes de qualquer chamada do agente, verifica-se que cada linha deletada ou âncora inserida no patch de ouro está presente verbatim na representação do contexto para cada braço.
- Determinismo: Os patches são construídos deterministicamente para evitar confusões decorrentes de geração de diff não reproduzível.
- Pré-registro: Hipóteses e protocolos foram congelados antes da coleta de dados.

Braços de Representação

O estudo compara três representações primárias para os arquivos alterados de ouro:

oracle_full: Os arquivos de origem completos e não modificados.
oracle_tier: Uma representação estruturada onde o código fora do locus é renderizado como esqueletos UML (estruturas de classe) e assinaturas de métodos, enquanto o locus da mudança permanece completo.
oracle_keep_drop: Uma abordagem binária onde o código fora do locus é totalmente deletado, deixando apenas as funções/classes específicas sendo editadas.

Sondas Comportamentais (A Fronteira "Find/Act")

Para testar se representações comprimidas carregam sinal acionável, os autores usaram sondas comportamentais:

Configuração: 15 classes retidas de seaborn, pylint e pytest. Três sondas (perguntas comportamentais) foram criadas a partir de arquivos de teste para cada classe.
Tarefa: O agente (Sonnet 4.6) lê uma representação (Fonte Completa, Resumo de Fronteira, Resumo de Modelo 3B ou Assinaturas) e responde à sonda.
Julgamento: Um juiz independente (GPT-4o-mini) gradua as respostas.
Controle: Um sumarizador de fronteira (Sonnet 4.6) e um modelo pequeno (Qwen-3B) geraram resumos para garantir que a falha de "sumarização" não fosse devido à baixa qualidade da sumarização.

Principais Resultados

1. O Contexto de "Agir" é Extremamente Mínimo

A hipótese registrada ( $H_2$ ) previa que camadas estruturadas (esqueletos UML/assinaturas) resolveriam mais problemas do que uma abordagem simples de manter/deletar (keep/drop). Esta hipótese falhou.

Taxas de Resolução:
- oracle_keep_drop: 25/70 resolvidos (35,7%)
- oracle_tier: 23/70 resolvidos (32,9%)
- oracle_full: 19/70 resolvidos (27,1%)
Significância Estatística: A diferença entre as camadas estruturadas e o keep/drop é nula (McNemar $p=0,75$ ). Renderizar o código circundante como esqueletos UML não fornece nenhum benefício mensurável sobre a exclusão direta quando a localização é perfeita.
Eficiência de Custo: Contextos comprimidos resolvem problemas com 3–3,7× menos tokens do que arquivos completos.
- Custo por resolução: ~19K tokens (keep/drop) vs. ~94K tokens (arquivos completos).

2. Resumos em Linguagem Natural Falham em Carregar Sinal Acionável

As sondas comportamentais revelaram um abismo massivo em informação acionável entre o código fonte e os resumos.

Precisão: A fonte completa respondeu 60% (27/45) das sondas comportamentais. Resumos em linguagem natural (tanto de modelos de fronteira quanto de 3B) responderam apenas ~9% (4/45).
Representação vs. Sumarizador: A lacuna é inerente à classe de representação, não à qualidade do sumarizador. Sumarizadores de fronteira performaram identicamente aos sumarizadores de modelos 3B.
Assinaturas: Assinaturas de métodos + docstrings performaram ligeiramente melhor que resumos em prosa (6/45), mas ainda assim falharam em igualar o código fonte.
Conclusão: Resumos em linguagem natural não respondem às perguntas comportamentais que o código fonte responde; o "sinal" reside na estrutura do código, não em narrativas.

3. Não-Determinismo de Execução para Execução

Uma descoberta metodológica crítica diz respeito à estabilidade da inferência de LLM em Temperatura 0.

Observação: Reexecutar o braço keep/drop com protocolos byte a byte idênticos (mesmo modelo, mesmos prompts, T=0) resultou em ~9% das ocorrências de resultados mudando (25/70 resolvidos originalmente vs. 23/70 na reexecução).
Implicação: Este nível de ruído (~9%) limita a interpretação de pequenos tamanhos de efeito. Diferenças de 1–2 instâncias (como a hipótese registrada $H_2$ ) são estatisticamente indistinguíveis do ruído de inferência.

Contribuições e Significância

O artigo reivindica quatro contribuições principais:

Um Instrumento Auditado: Um framework resolve@cost com verificação de expressibilidade por instância, construção de patch determinística e hipóteses pré-registradas, garantindo que cada número seja rastreável até os artefatos brutos.
Um Resultado Nulo Poderoso: Evidência de que camadas de representação estruturada (UML/esqueletos) não carregam nenhum sinal de resolução adicional sobre o keep/drop binário sob localização de oráculo. Isso desafia a suposição de que "mais estrutura" equivale a "melhor agir".
Uma Fronteira Find/Act Descircularizada: Demonstração de que o código fonte carrega aproximadamente 7× o sinal acionável de resumos em linguagem natural. Crucialmente, um sumarizador de fronteira não consegue fechar essa lacuna, indicando que a limitação é o formato da representação, não a capacidade do sumarizador.
Cautela Metodológica: A quantificação de um nível de ruído de ~9% na inferência de API de disparo único, T=0. Isso sugere que muitos pequenos tamanhos de efeito relatados na literatura do SWE-bench (incluindo os próprios resultados nulos deste artigo) podem ser artefatos de não-determinismo, em vez de sinal real.

Escopo e Limitações

Os autores afirmam explicitamente que suas conclusões se aplicam a agentes de disparo único sem loops de feedback de execução. Eles reconhecem que agentes de múltiplos turnos podem recuperar o contexto comprimido ao ler mais; contudo, no regime de disparo único, o passo de "encontrar" (find) deve ser perfeito (oráculo) e o contexto de "agir" (act) deve ser mínimo. O estudo não afirma que resumos são inúteis para navegação (encontrar código), apenas que são insuficientes para agir (editar código) quando comparados ao próprio código fonte.

O artigo conclui que, para a tarefa específica de editar código dado o local correto, o contexto mínimo necessário é o próprio código sendo editado, e o contexto circundante (mesmo em formas estruturadas) adiciona valor negligenciável enquanto incorre em custos significativos de tokens.