Resumo Técnico: Code-QA-Bench

Declaração do Problema

As atuais benchmarks para agentes de codificação com IA, como HumanEval, MBPP e SWE-Bench, focam principalmente na geração de código ou na resolução de problemas. Embora eficazes para medir a geração de correções, elas não avaliam adequadamente a compreensão de código—a capacidade de entender bases de código existentes, rastrear o fluxo de controle, localizar funcionalidades e explicar comportamentos. Existe uma lacuna crítica em distinguir o raciocínio genuíno sobre código do recuperação de documentação ou da memorização de pré-treinamento. As benchmarks existentes de QA em nível de repositório frequentemente avaliam agentes em repositórios com toda a documentação intacta, tornando difícil determinar se um agente está lendo o código ou simplesmente recuperando informações de seus dados de treinamento ou da documentação fornecida.

Metodologia

O Code-QA-Bench introduz um framework totalmente automatizado projetado para sintetizar benchmarks de QA em nível de repositório que isolam a compreensão de código da documentação e da memorização. O framework opera sobre quatro princípios fundamentais:

1. Design Experimental de Três Condições

Para quantificar as contribuições específicas do acesso ao código, da documentação e da memorização, cada tarefa é avaliada sob três condições distintas:

• Sem consulta (Closed-book): O agente recebe apenas a pergunta, sem acesso ao repositório. Isso mede conhecimento prévio e memorização.
• Apenas código (Code-only): O agente tem acesso ao repositório com todo o conteúdo em linguagem natural removido (docstrings, comentários, READMEs e arquivos de documentação). Isso mede o raciocínio puramente estrutural sobre o código.
• Documentado (Documented): O agente tem acesso ao repositório completo, incluindo toda a documentação. Isso mede o raciocínio sobre código ampliado pela documentação.

Métricas-chave são derivadas das diferenças entre essas condições:

• Apenas código - Sem consulta: A contribuição genuína da leitura de código além da memorização.
• Documentado - Apenas código: A utilidade da documentação para a compreensão de código.

2. Remoção de Documentação (Controle em Nível de Ambiente)

Para forçar o raciocínio estrutural sobre o código, o framework cria uma versão "apenas código" de cada repositório removendo programaticamente:

• Docstrings: Identificadas via AST e removidas (com pass inserido para manter a sintaxe).
• Comentários: Comentários de linha inteira e inline são removidos ou truncados.
• Arquivos de Documentação: Diretórios como docs/, doc/ e arquivos como README*, *.md e *.rst são excluídos.
  Crucialmente, o código executável, importações, anotações de tipo e literais de string são preservados, garantindo que os sinais semânticos provenientes dos identificadores permaneçam.

3. Geração de Tarefas com Resposta Primeiro

Ao contrário de abordagens anteriores que geram perguntas primeiro, o Code-QA-Bench emprega um pipeline de resposta primeiro:

1. Seleção de Blocos: Blocos de documentação são extraídos e pontuados com base na qualidade do conteúdo, referências a código e sinais estruturais.
2. Geração de Resposta Dourada (Gold Answer): Um agente equipado com ferramentas explora o código-fonte (usando read_file, list_directory, search_code) para produzir uma "resposta dourada" verificada. O agente é obrigado a rastrear pelo menos um nível mais fundo do que a documentação e incluir fatos não presentes no texto.
3. Verificação: Uma "auditoria apenas código" garante que a resposta dourada não contenha alegações que só possam ser recuperadas da documentação. Se uma alegação depender de documentação, ela é removida ou reescrita.
4. Derivação da Pergunta: Uma pergunta em linguagem natural é derivada da resposta dourada verificada, garantindo que a tarefa esteja fundamentada na estrutura real do código.

4. Conjunto de Tarefas Duplo

O benchmark gera dois conjuntos de tarefas distintos:

• Tarefas Deriváveis do Código (528 tarefas): As respostas douradas são verificadas como recuperáveis apenas da estrutura do código. Essas tarefas validam o design (esperando-se Apenas código ≈ Documentado).
• Tarefas Dependentes de Doc (100 tarefas): As respostas douradas são geradas apenas a partir da documentação, exigindo intencionalmente a documentação para responder completamente. Essas tarefas quantificam a utilidade da documentação (esperando-se Documentado > Apenas código).

5. Avaliação

As tarefas são pontuadas por um juiz LLM (GPT-5.4) em uma escala de 0 a 5 em três eixos:

• Precisão: Corretude das alegações factuais.
• Completude: Cobertura dos pontos-chave na rubrica.
• Especificidade: Referência a arquivos, funções ou padrões de código específicos.
  A pontuação final é a média normalizada desses três eixos.

Resultados Principais

Os experimentos foram conduzidos em quatro modelos de fronteira (Claude Opus 4.6, DeepSeek-V4-Pro, Kimi-K2.6, Gemini-3.1-Pro) em 10 repositórios Python do SWE-Bench.

1. O Acesso ao Código é o Fator Dominante

O acesso à base de código proporciona um ganho substancial de desempenho sobre a memorização. O ganho médio de Apenas código sobre Sem consulta é de +0,23, que é três vezes maior que o ganho fornecido pela documentação. Isso confirma que a leitura de código contribui significativamente mais para a compreensão do que o conhecimento prévio sozinho.

2. A Documentação Proporciona Utilidade Modesta e Mensurável

Para tarefas dependentes de doc, o acesso à documentação produz uma melhoria consistente e estatisticamente significativa (Documentado - Apenas código = +0,071, p < 0,003). Isso sugere que, embora a estrutura do código permita que os agentes inferam grande parte da resposta, a documentação fornece detalhes críticos (racional de design, casos de borda) que melhoram a completude e a precisão.

3. Validação do Design Experimental

Nas tarefas deriváveis do código, a lacuna de desempenho entre as condições Apenas código e Documentado é negligenciável (∆ ≈ +0,007) e estatisticamente insignificante para a maioria dos modelos. Isso valida a metodologia: o framework isola com sucesso tarefas onde a documentação é desnecessária, provando que os benefícios observados em tarefas dependentes de doc são utilidade genuína e não artefatos da configuração de avaliação.

4. Insights Específicos por Modelo

• Memorização: Os modelos pontuam entre 0,56 e 0,68 na condição sem consulta, indicando memorização significativa de bibliotecas bem conhecidas durante o pré-treinamento.
• Raciocínio vs. Recuperação: O DeepSeek-V4-Pro apresentou a maior lacuna entre apenas código e sem consulta (+0,450), sugerindo uma forte dependência de exploração ativa de código em vez de recuperação paramétrica.
• Análise por Categoria: Contrariando a hipótese de que perguntas do tipo "Por que" mostrariam a maior lacuna de documentação, perguntas do tipo "Onde" (localização de funcionalidades) mostraram o delta mais significativo em tarefas deriváveis do código, sugerindo que a documentação atua como um índice de navegação.

Significado e Alegações

O artigo afirma que o Code-QA-Bench proporciona uma mudança metodológica necessária na avaliação de agentes de codificação com IA ao:

1. Separar Compreensão de Memorização: Oferece uma maneira quantitativa de medir o quanto um agente depende da leitura de código versus a recuperação de dados de treinamento ou documentação.
2. Controle em Nível de Ambiente: Ao remover a documentação em nível de repositório em vez de filtrar perguntas, força os agentes a se engajarem com a estrutura do código, abordando o problema de "contaminação" em benchmarks existentes.
3. Automatizado e Reprodutível: O pipeline é totalmente automatizado, agnóstico a repositórios e aplicável a qualquer repositório Python bem documentado, permitindo atualizações contínuas do benchmark à medida que os modelos melhoram.
4. Valor Diagnóstico: O design de três condições fornece sinais diagnósticos (por exemplo, saturação de especificidade, níveis de memorização) que benchmarks de geração pura perdem, oferecendo uma visão mais matizada das capacidades de um agente.

Os autores concluem que, embora modelos de fronteira sejam leitores estruturais de código fortes, o benefício modesto, porém consistente, da documentação destaca a importância contínua de bases de código bem documentadas para agentes de IA. O framework é de código aberto e serve tanto como ferramenta de avaliação quanto como fonte de dados de treinamento verificados.