Sumário Técnico: Avaliando AGENTS.md

Declaração do Problema

A indústria de engenharia de software adotou rapidamente agentes de codificação, com uma recomendação predominante de desenvolvedores de modelos e agentes para adaptar esses agentes a repositórios específicos usando arquivos de contexto (ex: AGENTS.md ou CLAUDE.md). Esses arquivos geralmente contêm visões gerais de repositório, instruções de ferramentas e guias de estilo destinados a melhorar a navegação, a execução de builds e a resolução de tarefas. Apesar da ampla adoção — relatada em mais de 60.000 repositórios de código aberto — e do forte incentivo da indústria, não há uma investigação rigorosa e em larga escala sobre se esses arquivos de contexto realmente melhoram o desempenho dos agentes de codificação em tarefas do mundo real. Benchmarks anteriores como o SWE-bench carecem de arquivos de contexto, e os repositórios populares usados nesses benchmarks frequentemente não representam as bases de código onde os arquivos de contexto são realmente implantados.

Metodologia

Para abordar essa lacuna, os autores conduziram uma avaliação abrangente em dois cenários complementares:

1. Novo Benchmark (CTXBENCH): Os autores construíram um novo benchmark composto por 138 instâncias derivadas de problemas reais do GitHub em 12 repositórios de nicho baseados em Python que já contêm arquivos de contexto commitados por desenvolvedores. Diferente do SWE-bench, que depende de repositórios populares, o CTXBENCH visa repositórios onde o uso de arquivos de contexto é uma prática ativa. A geração do conjunto de dados envolveu:

   • Filtragem de repositórios com AGENTS.md ou CLAUDE.md e pelo menos 400 Pull Requests (PRs).
   • Seleção de PRs que introduzem comportamentos determinísticos e testáveis.
   • Uso de agentes de LLM para gerar descrições de tarefas padronizadas e novos testes unitários onde os PRs originais careciam deles, garantindo que os testes passem no código corrigido, mas falhem no código base.
   • Validação de que os arquivos de contexto fornecidos pelos desenvolvedores são distintos dos gerados por LLM (mais curtos, com pontuações de detecção de IA menores).

2. Configuração Experimental: O estudo avaliou quatro agentes de codificação (CLAUDE CODE, CODEX, QWEN CODE) pareados com vários modelos (SONNET-4.5, GPT-5.2, GPT-5.1 Mini, QWEN3-30B-CODER) em dois conjuntos de dados:

   • SWE-BENCH Lite: 300 tarefas de repositórios populares sem arquivos de contexto de desenvolvedores.
   • CTXBENCH: 138 tarefas de repositórios com arquivos de contexto de desenvolvedores.

3. Condições de Avaliação: Para cada tarefa, os agentes foram testados em três configurações:

   • None (Nenhum): Nenhum arquivo de contexto fornecido.
   • LLM: Um arquivo de contexto gerado automaticamente pelo comando de inicialização recomendado pelo agente.
   • DEV: O arquivo de contexto real commitado pelo desenvolvedor (disponível apenas para o CTXBENCH).

4. Métricas: O desempenho foi medido pela taxa de sucesso (porcentagem de tarefas onde o patch gerado passa em todos os testes), o número de etapas de interação e o custo total de inferência. A análise de rastreamento foi realizada para entender mudanças comportamentais, incluindo frequência de uso de ferramentas e consumo de tokens de raciocínio.

Principais Contribuições

1. CTXBENCH: Um novo benchmark especificamente projetado para avaliar o impacto de arquivos de contexto ativamente usados e fornecidos por desenvolvedores em agentes de codificação, apresentando 138 instâncias de 12 repositórios.
2. Avaliação Abrangente: Um estudo extensivo através de múltiplos modelos e agentes tanto no SWE-BENCH quanto no CTXBENCH, revelando que os arquivos de contexto não melhoram significativamente as taxas de sucesso das tarefas.
3. Análise Comportamental: Uma investigação detalhada dos rastros dos agentes demonstrando que, embora os agentes sigam estritamente as instruções nos arquivos de contexto (levando a um aumento no teste e exploração), esses arquivos falham em servir como visões gerais eficazes do repositório e aumentam os custos operacionais.

Resultados

O estudo produz várias descobertas contraintuitivas em relação à eficácia dos arquivos de contexto:

• Sem Ganho de Desempenho: Fornecer arquivos de contexto não melhora, em geral, as taxas de sucesso das tarefas.
  • No SWE-BENCH, arquivos gerados por LLM resultaram em uma diminuição marginal e estatisticamente insignificante nas taxas de sucesso (média de -0,5%).
  • No CTXBENCH, arquivos gerados por LLM também não mostraram melhoria significativa (média de -2%).
  • Arquivos commitados por desenvolvedores mostraram uma melhoria marginal de 2,4% em média sobre a configuração "None", mas isso não foi estatisticamente significativo ($p=0,21$). No entanto, arquivos de desenvolvedores superaram significativamente os arquivos gerados por LLM ($p=0,038$).
• Aumento de Custo e Etapas: Arquivos de contexto consistentemente aumentam o custo e a complexidade da resolução de tarefas.
  • Arquivos gerados por LLM aumentaram os custos de inferência em mais de 20% em média em ambos os benchmarks.
  • Arquivos commitados por desenvolvedores aumentaram os custos em até 19%.
  • O número de etapas de interação aumentou significativamente em todas as configurações com arquivos de contexto.
• Mecanismos Comportamentais:
  • Seguimento de Instruções: Agentes seguem estritamente as instruções nos arquivos de contexto. Quando ferramentas específicas (ex: uv, pytest) são mencionadas, seu uso aumenta dramaticamente. Isso leva a testes mais minuciosos, exploração de arquivos e uso de ferramentas específicas do repositório.
  • Visões Gerais Ineficazes: Apesar das recomendações para incluir visões gerais do codebase, essas seções não ajudam os agentes a localizar arquivos relevantes mais rapidamente. Na verdade, os agentes frequentemente gastam etapas extras procurando e relendo arquivos de contexto que já estão em sua janela de contexto.
  • Sobrecarga de Raciocínio: A presença de arquivos de contexto aumenta o número de tokens de raciocínio usados por modelos adaptativos (ex: +22% para GPT-5.2 com arquivos gerados por LLM), sugerindo que as instruções adicionais tornam a tarefa cognitivamente mais difícil sem fornecer a informação necessária.
• Redundância: Arquivos de contexto frequentemente atuam como documentação redundante. Quando a documentação existente (READMEs, pastas de docs) é removida, arquivos gerados por LLM na verdade melhoram o desempenho, sugerindo que seu principal valor em configurações padrão é a redundância, não o insight único.

Significância e Conclusão

O artigo conclui que a prática atual da indústria de gerar automaticamente ou incluir amplamente arquivos de contexto como o AGENTS.md não é sustentada por evidências empíricas para melhorar o desempenho de agentes de codificação. Embora os agentes sigam as instruções contidas nesses arquivos, levando a uma exploração mais minuciosa (e custosa), os arquivos geralmente falham em fornecer visões gerais de repositório eficazes que acelerem a resolução de tarefas.

Os autores argumentam que os arquivos de contexto devem ser reservados para especificar práticas de codificação não padronizadas ou convenções específicas que já não estejam presentes no README do repositório. Eles recomendam que os desenvolvedores avaliem rigorosamente qualquer tentativa de usar arquivos de contexto antes da implantação, em vez de confiar na geração automática ou em recomendações amplas. Este trabalho destaca uma lacuna entre as recomendações dos desenvolvedores de agentes e os resultados observados, motivando pesquisas futuras sobre a geração de orientações princípios, concisas e relevantes para tarefas para agentes de codificação.