🤖 machine learning

Probe-and-Refine Tuning of Repository Guidance for Coding Agents

Este artigo introduz o "probe-and-refine tuning", um método que otimiza iterativamente arquivos de orientação de repositório (AGENTS.md) usando sondas sintéticas de correção de bugs para melhorar significativamente o desempenho de agentes de codificação no SWE-bench Verified ao expandir a cobertura de patches avaliáveis em vez de aumentar a precisão por patch.

Autores originais: Asa Shepard, Jeannie Albrecht

Publicado 2026-06-19

📖 5 min de leitura🧠 Leitura aprofundada

CC BY 4.0

Autores originais: Asa Shepard, Jeannie Albrecht

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 nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine que você contrata um aprendiz brilhante, mas inexperiente, para consertar uma biblioteca enorme e antiga (o repositório de código). O aprendiz é inteligente o suficiente para ler livros e consertar páginas rasgadas, mas ele não conhece as regras secretas da biblioteca: qual prateleira guarda os mapas raros, como pedir ajuda ao bibliotecário sem acordar os gatos adormecidos ou quais escadas são seguras para subir.

Sem esse "conhecimento local", o aprendiz vaga sem rumo, sobe a escada errada ou tenta consertar um livro na seção errada, muitas vezes quebrando coisas no processo.

Este artigo apresenta um método chamado "Probe-and-Refine Tuning" (Ajuste por Sondagem e Refinamento) para resolver este problema. Veja como funciona, usando analogias simples:

O Problema: O Manual "Tamanho Único"

Engenheiros costumam escrever uma "folha de dicas" (como um arquivo AGENTS.md) para seus agentes de codificação de IA.

O Jeito Antigo (Conhecimento Estático): Eles pedem a uma IA inteligente para escrever um manual genérico: "Sempre verifique o índice antes de consertar" ou "Procure pelo ponto de entrada principal". Isso é como dar ao aprendiz um mapa de todas as bibliotecas do mundo. É útil, mas não diz a ele onde o estoque secreto daquela biblioteca específica está escondido.
O Resultado: O aprendiz até se sai bem, mas ainda se perde com frequência.

A Solução: O Treinador de "Tentativa e Erro"

Os autores criaram um novo processo chamado Probe-and-Refine. Em vez de apenas escrever um manual uma única vez, eles tratam o manual como um documento vivo que é treinado através dos erros.

Pense nisso como um treinador treinando um novo jogador:

As Sondagens (Os Exercícios): O treinador gera 10 problemas falsos, inventados, específicos para esta biblioteca (sondas).
A Tentativa: O aprendiz tenta resolver esses problemas falsos usando o manual atual.
O Diagnóstico: O treinador observa a tentativa. "Ah, você tentou consertar o encanamento na cozinha, mas os canos estão, na verdade, no porão. E você esqueceu de verificar as plantas primeiro."
O Refinamento: O treinador atualiza o manual imediatamente com uma regra específica: "Para esta biblioteca, o encanamento fica no porão e sempre verifique as plantas primeiro."
Repetir: Eles fazem isso de 3 a 5 vezes. O manual evolui de um guia genérico para um guia de "especialista interno" hiperespecífico.

Crucialmente, todo esse processo de treinamento acontece sem que o agente realmente conserte bugs reais. É um loop de simulação onde a IA escreve o manual, testa-o em problemas falsos e corrige o manual com base nos resultados.

O Que Eles Descobriram

Os pesquisadores testaram isso em um famoso benchmark de codificação (SWE-bench) com quatro execuções diferentes. Aqui está o que aconteceu:

Sem Guia: O aprendiz resolveu 25,5% dos problemas.
Guia Genérico: O aprendiz resolveu 28,3% dos problemas.
Guia Probe-and-Refine: O aprendiz resolveu 33,0% dos problemas.

O Grande Segredo: Trata-se de Encontrar a Porta Certa, Não de Consertar Melhor
Você pode pensar que o manual melhorado tornou o aprendiz mais inteligente ou melhor em consertar coisas. Não foi isso.

Quando o aprendiz realmente consertava algo, a qualidade do conserto era exatamente a mesma (cerca de 59% de taxa de sucesso) independentemente de qual manual usava.
A verdadeira magia foi a "Cobertura". O manual melhorado ajudou o aprendiz a encontrar o arquivo certo para consertar com muito mais frequência.
- Analogia: O manual genérico fez o aprendiz bater em 100 portas, mas apenas 40 eram as certas. O manual refinado fez o aprendiz bater em 100 portas, e 56 delas eram as certas. Uma vez que ele encontrava a porta certa, sua habilidade de consertar a fechadura era a mesma.

A Armadilha do "Orçamento de Passos" (Step Budget)

O artigo também descobriu que o guia só funciona se você der tempo suficiente ao aprendiz.

Se você der ao aprendiz apenas 25 passos para resolver um problema, o manual sofisticado não ajuda. Ele não tem tempo para seguir as instruções complexas.
Se você der a ele 200 passos, o manual sofisticado brilha. Ele indica um fluxo de trabalho (Reproduzir -> Rastrear -> Consertar) que leva tempo, mas funciona. Sem o manual, eles apenas se apressam e falham.
Analogia: Se você disser a alguém: "Pegue uma rota panorâmica para evitar o trânsito", mas der apenas 5 minutos para chegar ao trabalho, a pessoa apenas se perderá. Você precisa dar tempo suficiente para que ela possa realmente fazer a rota panorâmica.

O Aviso de "Descompasso de Modelo" (Model Mismatch)

A descoberta mais surpreendente foi que este guia não é universal.

Eles tentaram usar o guia treinado em um modelo de IA (Qwen) com um modelo diferente e ligeiramente mais fraco (Nemotron).
Resultado: O segundo modelo travou. Ele ficou tão confuso com as instruções específicas que parou de funcionar completamente.
Analogia: É como dar um manual de corrida de alta velocidade para um motorista em um carro antigo e lento. As instruções são complexas demais para o carro, e o motorista congela. O guia deve ser "ajustado" especificamente para o cére (modelo) que irá lê-lo.

Resumo

Este artigo prova que a forma como você escreve as instruções importa mais do que apenas ter instruções.
Ao usar um loop simples de "criar um problema falso, tentar resolvê-lo e corrigir as instruções com base na falha", você pode transformar um guia genérico em um manual de especialista especializado. Isso não torna a IA mais inteligente em consertar código; apenas impede que ela procure no lugar errado, permitindo que ela use todo o seu potencial para resolver mais problemas.

Resumo Técnico: Ajuste de Probe-and-Refine para Orientação de Repositórios em Agentes de Codificação

Declaração do Problema

Agentes de codificação baseados em LLM frequentemente falham em resolver tarefas de engenharia de software não por falta de capacidade de raciocínio, mas porque carecem de conhecimento operacional de alto nível sobre um repositório de código específico. Esse conhecimento implícito — como limites de subsistemas, fluxos de execução de testes e padrões históricos de depuração — raramente é documentado no próprio código. Embora engenheiros mantenham arquivos de contexto (ex: AGENTS.md) para fornecer essa informação, a literatura recente apresenta evidências conflitantes sobre sua eficácia: alguns estudos sugerem que eles melhoram a eficiência, enquanto outros indicam que podem reduzir as taxas de resolução se a orientação for genérica ou contraproducente. O problema central é que permanece incerto se a falha reside no conceito de orientação em si ou em como essa orientação é produzida. Os métodos atuais dependem frequentemente de geração de passo único por LLM, o que resulta em conselhos genéricos em vez das estratégias operacionais específicas e informadas por falhas exigidas pelos agentes.

Metodologia

O artigo introduz o Probe-and-Refine Tuning, um procedimento leve projetado para diagnosticar e corrigir iterativamente o arquivo de orientação de um repositório usando sondas sintéticas de correção de bugs. O procedimento é distinto dos loops de agentes padrão, pois depende inteiramente de chamadas de LLM de passo único (single-shot), sem uso de ferramentas ou aprendizado por reforço durante a fase de ajuste.

O Loop de Ajuste

O processo transforma uma base de conhecimento estática e genérica em uma orientação operacional especializada através de 3 a 5 iterações:

Gerar Sondas (Probes): O sistema gera um lote de 10 tarefas sintéticas de correção de bugs a partir da base de código do repositório, visando diversos subsistemas.
Tentar Correção: Para cada sonda, uma chamada de LLM de passo único tenta gerar um patch utilizando o artefato de orientação atual.
Julgar Tentativa: Uma chamada separada de passo único avalia a solução tentada contra comportamentos esperados (ex: correções fortes, parciais ou ausentes) e propõe edições específicas à orientação onde as deficiências foram identificadas.
Agregar e Aplicar: Uma chamada final agrega os diagnósticos de todas as sondas e propõe um conjunto consolidado de edições. Essas edições são aplicadas mecanicamente (inserindo, modificando ou fortalecendo seções) ao arquivo de orientação, limitado a 3.000 caracteres.

O loop termina precocemente se a orientação estabilizar (sem mudanças entre iterações consecutivas). O artefato resultante é então usado para guiar um agente de codificação padrão do tipo ReAct durante a fase de avaliação no SWE-bench Verified.

Configuração Experimental

Os autores avaliaram três condições em 500 instâncias do SWE-bench Verified através de quatro ensaios independentes usando o modelo Qwen3.5-35B-A3B:

Sem Contexto (No Context): O agente opera sem orientação específica do repositório.
Base de Conhecimento Estática (Static KB): O agente utiliza uma base de conhecimento de duas camadas contendo dados estruturais (analisados via tree-sitter) e melhores práticas genéricas e agnósticas ao repositório.
Probe-and-Refine: O agente utiliza a orientação produzida pelo procedimento de ajuste iterativo descrito acima.

Um experimento secundário substituiu o modelo pelo NVIDIA-Nemotron-3-Nano-30B-A3B para testar a generalização entre modelos, e uma varredura de orçamento de passos (25, 50, 100, 200 passos) foi realizada para analisar a interação entre a orientação e o orçamento do agente.

Resultados Principais

Ganhos de Desempenho

Em quatro ensaios, o Probe-and-Refine alcançou uma taxa média de resolução de 33,0%, superando significativamente a Static KB (28,3%) e a linha de base No Context (25,5%). A melhoria foi estatisticamente significativa ( $p < 0,001$ ) para ambos os contrastes. O procedimento também gerou 31 resoluções consistentemente únicas (resolvidas em $\ge$ 3 de 4 ensaios) que nenhuma das outras condições conseguiu resolver.

Mecanismo: Cobertura vs. Precisão

O artigo decompõe o ganho de desempenho para determinar como a orientação ajuda:

Cobertura: O principal motor da melhoria é a cobertura de avaliação. A orientação do Probe-and-Refine permitiu que o agente produzisse patches bem formados e avaliáveis para 56,2% das instâncias, comparado a 41,7% da linha de base sem orientação (uma diferença de 14,5 pontos percentuais).
Precisão: A correção dos patches, condicional ao fato de serem avaliáveis, permaneceu estatisticamente constante em todas as condições ( $\sim$ 59%, $p = 0,119$ ).
Conclusão: A orientação não melhora a qualidade das alterações de código que o agente faz; em vez disso, ela ajuda o agente a chegar ao arquivo correto e produzir um patch que o harness de avaliação possa aceitar. A orientação efetivamente reduz a taxa de patches malformados ou patches que travam a suíte de testes antes que as asserções possam ser verificadas.

Orçamento de Passos e Fluxo de Trabalho

O estudo descobriu que a orientação atua como um moderador para a utilidade do orçamento de passos.

Agentes sem orientação: Saturam rapidamente; aumentar o orçamento de passos de 25 para 200 passos não melhorou sua taxa de resolução, pois carecem de um plano estruturado para converter passos extras em melhores patches.
Agentes Probe-and-Refine: Utilizam orçamentos maiores de forma produtiva. O fluxo de trabalho prescrito "reproduzir-rastrear-corrigir" exige mais passos para completar. Consequentemente, a condição probe-and-refine mostrou ganhos significativos em orçamentos maiores (100 e 200 passos) onde a orientação simples (Static KB) estagnou.

Generalização entre Modelos

Ao ser aplicado ao modelo Nemotron, os resultados destacaram uma dependência de ajuste ao modelo (model-fit dependency) crítica:

Falha de Ajuste: O loop de ajuste degradou no Nemotron porque o modelo não conseguiu gerar uma saída suficientemente diagnóstica para a etapa de "Juiz" (Judge), fazendo com que o loop travasse.
Transferência Negativa: A orientação ajustada no Qwen, quando aplicada ao Nemotron, colapsou ativamente o desempenho do agente (13,2% de taxa de resolução vs. 27,0% para a própria linha de base do Nemotron). A orientação detalhada e prescritiva fez com que o Nemotron entrasse em "conformidade por análise" (escrevendo prosa sobre o que faria) em vez de executar comandos, desencadeando um efeito cascata de falhas de fallback.
Constância de Precisão: Mesmo no colapso entre modelos, a precisão dos poucos patches que foram produzidos permaneceu constante, reforçando que a falha foi inteiramente na cobertura (o agente falhando em produzir um patch), e não na qualidade do patch em si.

Significância e Alegações

O artigo afirma que a qualidade da instrução é uma variável de primeira ordem na confiabilidade do agente de codificação, comparável em magnitude à capacidade do modelo ou às escolhas de orçamento de passos.

O Conhecimento Operacional é Aprendível: Os autores demonstram que o conhecimento operacional (quais arquivos abrigam quais subsistemas, como executar testes) pode ser destilado de falhas sintéticas em um artefato de texto compacto sem loops de agentes complexos ou uso de ferramentas.
O Gargalo é a Orientação, Não o Raciocínio: Os resultados sugerem que, para muitas instâncias "difíceis", a falha do agente não é falta de poder de raciocínio, mas uma falha em localizar o problema no arquivo correto. A orientação atua como um auxílio de localização, permitindo que o agente navegue pela estrutura do repositório de forma eficaz.
Calibração Específica do Modelo: A orientação não é conhecimento transferível de repositório; é uma calibração comportamental específica do modelo. A orientação ajustada para os modos de falha de um modelo pode prejudicar ativamente um modelo diferente com um perfil comportamental distinto.
Reconciliação de Divergências Anteriores: O artigo reconcilia as divergências da literatura sobre arquivos AGENTS.md ao mostrar que a eficácia da orientação depende de como ela é produzida (refinamento iterativo vs. geração de passo único) e do orçamento de passos disponível. A orientação estática e genérica pode ser neutra ou prejudicial, enquanto a orientação específica de fluxo de trabalho e iterativamente refinada é benéfica, desde que o orçamento permita a conclusão do fluxo de trabalho.

Os autores concluem que, para profissionais, investir em orientação refinada iterativamente é valioso para repositórios com altos volumes de problemas, desde que a orientação seja ajustada no modelo específico que irá consumi-la e o orçamento de passos seja suficiente para acomodar o fluxo de trabalho prescrito.