Evals de PR que seguram agentes de código no CI

Evals de PR para agentes de código são verificações criadas para julgar uma mudança gerada por IA antes do revisor humano. Elas juntam testes, rubricas, análise do diff, evidência de execução e regras de bloqueio. O objetivo não é provar que o agente é inteligente. É provar que aquele PR específico merece atenção humana.

Em 2026, o GitHub afirmou que o Copilot code review já processou mais de 60 milhões de revisões e que mais de uma em cada cinco revisões de código no GitHub envolve um agente (GitHub, "Agent pull requests are everywhere. Here's how to review them", 2026). Esse volume muda a disciplina: revisão manual sem eval vira fila.

Resumo prático

• PR de agente precisa chegar com prova, não com confiança textual.
• Evals bons combinam teste determinístico, rubrica e evidência de execução.
• Subagentes ajudam quando revisam sinais separados e retornam síntese curta.
• O CI deve bloquear risco repetível antes de chamar o revisor.

Por que evals de PR viraram prioridade?

Em 2026, a GitLab relatou que 85% concordam que a IA deslocou o gargalo da escrita para revisão e validação de código (GitLab, "AI Accountability Report", 2026). Evals de PR viraram prioridade porque agentes aceleram criação de diff, mas o custo de confiança ainda fica no humano.

O erro é tratar todo PR de agente como se fosse um PR humano com autor disponível para defender cada escolha. Um agente pode escrever uma explicação convincente e ainda assim ter tocado arquivo errado, ignorado regressão ou removido teste sem motivo. A narrativa não basta.

O eval resolve outra pergunta: quais sinais mínimos tornam este PR revisável? Para backend, pode ser teste de contrato, tipo, lint, migração reversível e análise de permissão. Para DevOps, pode ser plano de rollback, escopo de infraestrutura e verificação de segredo. Para frontend, pode ser teste visual, acessibilidade e estado vazio.

Esse recorte complementa o texto sobre harness de agentes de código para PRs confiáveis. O harness define o fluxo. O eval define a medição. Sem os dois, o time só move o gargalo para uma fila de revisão maior.

Um eval de PR para agentes de código transforma revisão em triagem baseada em evidência. Se o PR não mostra teste, escopo e risco, ele não está pronto. Se mostra, o revisor gasta atenção no que importa: arquitetura, produto, segurança e trade-offs que automação não decide.

O que um eval precisa medir antes do merge?

Em 2026, a GitLab também afirmou que 82% veem código gerado por IA como risco de uma nova forma de dívida técnica (GitLab, "AI Accountability Report", 2026). Por isso, um eval de PR deve medir reprodução, escopo, regressão e rastreabilidade, não apenas se a suíte ficou verde.

O primeiro sinal é reprodução. Se o PR corrige bug, o eval deve exigir um teste que falhava antes ou um artefato que mostre a falha original. Sem isso, o agente pode ter apenas alterado sintoma. Para feature, o equivalente é um contrato de comportamento com caso feliz e caso negativo.

O segundo sinal é escopo. Evals precisam comparar o diff com a tarefa. Um agente que muda autenticação para corrigir layout merece bloqueio. Um agente que altera lockfile sem dependência nova merece explicação. Um agente que remove teste para passar CI merece falha automática.

O terceiro sinal é risco. Mudanças em autenticação, pagamento, dados pessoais, filas, jobs, migrações e infraestrutura devem elevar o nível do gate. Não precisa tratar todo PR como incidente. Precisa reconhecer que alguns diretórios carregam mais dano potencial.

Experiência prática: quando eu reviso PRs gerados por agente, o melhor sinal não é o tamanho do texto. É a relação entre hipótese e prova. Se a hipótese diz "corrigir expiração de sessão", eu quero ver teste de sessão, arquivo tocado e saída do comando. O resto é detalhe.

Como transformar isso em um gate de CI?

Em 2026, a GitLab disse que apenas 28% afirmam ter ferramentas de ciclo de desenvolvimento totalmente integradas com dados e fluxos compartilhados (GitLab, "AI Accountability Report", 2026). Um gate de CI para agente precisa ser simples o bastante para entrar no fluxo existente.

Comece com um arquivo de política. Ele pode viver em AGENTS.md, CLAUDE.md ou .github/agent-evals.yml. O nome importa menos que a função: registrar comandos obrigatórios, áreas sensíveis, formato de evidência e condição de bloqueio. Em junho de 2026, o GitHub tornou AGENTS.md disponível para orientar feedback do Copilot code review (GitHub Changelog, "Copilot code review: AGENTS.md support and UI improvements", 2026).

Depois, crie um verificador pequeno. Ele não precisa usar IA no primeiro dia. Um script Node, Python ou Bash pode validar que o PR tem corpo com comandos, que arquivos sensíveis disparam label, que teste obrigatório rodou e que nenhum arquivo proibido mudou. O gate começa determinístico.

Em seguida, adicione uma rubrica para o que teste não cobre. A rubrica pode pontuar clareza do PR, relação com requisito, risco residual e adequação arquitetural. Use IA como juiz apenas quando o critério for semântico. Ainda assim, trate o resultado como sinal, não como verdade final.

eval_de_pr:
  comandos_obrigatorios:
    - "npm run lint"
    - "npm run test -- --runInBand"
    - "npm run typecheck"
  areas_sensiveis:
    - "src/auth/**"
    - "infra/**"
    - "migrations/**"
  exige_revisor_humano:
    - "auth"
    - "dados pessoais"
    - "rollback"
  bloqueia_se:
    - "sem teste novo para bug"
    - "diff fora do escopo"
    - "comando obrigatorio ausente"

Para loops longos com Claude Code e Codex, custo de contexto também vira parte do gate. Eu uso o RemoteCode para levar Claude Code e Codex mais longe em fluxos agentic como ferramenta do próprio autor quando o trabalho precisa atravessar sessões, subagentes e evidências sem carregar todo o histórico no prompt principal.

Onde subagentes entram sem virar ruído?

Em 2026, a documentação do Codex afirma que subagentes ajudam em tarefas altamente paralelas, como exploração de codebase ou implementação de plano com várias etapas (OpenAI Developers, "Subagents", 2026). Em evals de PR, subagentes entram melhor como revisores especializados, não como vários autores mexendo no mesmo diff.

Um subagente pode ler segurança. Outro pode checar testes. Outro pode olhar impacto em tipos TypeScript. Outro pode comparar a especificação com o diff. O agente principal não precisa receber cada log. Precisa receber síntese com achado, arquivo, severidade, confiança e próxima ação.

A documentação do Claude Code descreve subagentes como assistentes especializados que trabalham em contexto próprio e retornam apenas um resumo, preservando a conversa principal (Claude Code Docs, "Create custom subagents", 2026). Essa é a regra central para PRs: fan-out de leitura, merge de decisão.

Evite subagentes que escrevem no mesmo módulo ao mesmo tempo. Isso mistura autoria, aumenta conflito e dificulta explicar por que uma decisão venceu. Se o trabalho exige várias mudanças, divida por fronteira real: serviço, pacote, rota, schema ou job. O eval final deve consolidar.

Uma boa saída de subagente cabe em poucas linhas:

area: seguranca
status: bloquear
arquivo: src/auth/session.service.ts
motivo: renovacao aceita token expirado sem checar revoked_at
prova: teste auth/session-renewal.spec.ts falha no caso negativo
acao: exigir teste de revogacao antes do merge

Essa forma evita o pior dos dois mundos: muitos agentes falando e ninguém decidindo. Subagente bom reduz contexto. Subagente ruim vira reunião assíncrona entre modelos.

Como desenhar um loop que melhora sozinho?

Em 2026, a OpenAI recomenda dar ao Codex um sistema de avaliação com scripts e artefatos revisáveis para que ele melhore uma tarefa até a pontuação ficar boa o bastante (OpenAI Developers, "Iterate on difficult problems", 2026). O loop melhora sozinho quando a falha vira dado estruturado, não quando o agente tenta de novo no escuro.

O ciclo começa com hipótese. O agente declara qual comportamento vai mudar, que arquivo pretende tocar e como pretende provar. Depois aplica o patch. Em seguida, o CI roda evals. Se falhar, a próxima tentativa recebe diagnóstico compacto: comando, falha, arquivo provável e restrição preservada.

OpenAI descreveu, no caso de agentes tributários, um ciclo em que problemas de produção viram achados, evals sob medida e tarefas de engenharia com validação contra evals direcionados e de regressão (OpenAI, "Building self-improving tax agents with Codex", 2026). Para software, o mesmo padrão transforma incidentes, bugs e revisões em casos de teste reutilizáveis.

Não aceite loop infinito como autonomia. Defina limite de tentativas e uma regra de parada. Se duas tentativas falham pelo mesmo motivo, o agente deve abrir bloqueio. Se a falha muda, ele pode iterar. Se o eval está errado, o agente pode propor ajuste, mas não deve editar o gate sem revisão.

O ponto mais importante: eval também precisa de manutenção. Quando um revisor humano encontra falha que o gate deixou passar, registre o padrão. Se ele for repetível, transforme em teste, rubrica ou regra de escopo. O sistema fica melhor quando cada erro caro vira uma checagem barata.

Qual é o mínimo viável para começar nesta semana?

Em 2026, a GitLab apontou que 91% das organizações provavelmente investirão em ferramentas de governança de código com IA nos próximos 12 meses (GitLab, "AI Accountability Report", 2026). O mínimo viável não precisa esperar plataforma nova: comece com uma política pequena, um checker e um template de PR.

Primeiro, escreva uma seção no AGENTS.md com comandos obrigatórios e formato de entrega. Inclua "o que mudou", "por que mudou", "como foi verificado" e "risco residual". Isso já melhora Claude Code, Codex, Copilot e qualquer agente que leia instruções do repositório.

Segundo, crie um job de CI chamado agent-pr-eval. Ele roda comandos existentes e valida o corpo do PR. Se a base já tem testes end-to-end com Playwright, adicione só o subset relevante. Se tem tipos de testes no desenvolvimento de software, escolha a menor combinação que prova a mudança.

Terceiro, marque áreas sensíveis. Autenticação, autorização, cobrança, dados pessoais, migrações e infraestrutura não devem passar com autoaprovação. Esse gate conversa com práticas de arquitetura de serviços em TypeScript, porque limites de módulo tornam evals mais objetivos.

Quarto, registre falsos negativos. Toda vez que um revisor encontrar erro que o CI não pegou, faça uma pergunta: isso vira teste, rubrica, regra de escopo ou checklist humano? Se não virar nada, a organização continuará pagando o mesmo custo de revisão.

Perguntas frequentes sobre evals de PR

Em 2026, a GitLab afirmou que 80% concordam que suas organizações adotaram ferramentas de IA mais rápido do que desenvolveram políticas para governá-las (GitLab, "AI Accountability Report", 2026). As dúvidas abaixo ajudam a transformar política em rotina.

Eval de PR substitui revisão de código humana?

Não. Em 2026, a GitLab relatou que 85% veem o gargalo em revisão e validação, não apenas escrita de código (GitLab, "AI Accountability Report", 2026). O eval remove ruído repetível; o humano decide arquitetura, intenção de produto e risco que exige julgamento.

Todo PR de agente precisa de IA julgando a rubrica?

Não. Em 2026, a OpenAI recomenda scripts e artefatos revisáveis como base do loop de avaliação (OpenAI Developers, "Iterate on difficult problems", 2026). Comece com checagens determinísticas. Use juiz de IA só para critérios semânticos, como coerência entre requisito e diff.

AGENTS.md é obrigatório para evals?

Não, mas ficou mais útil. Em 2026, o GitHub anunciou que o Copilot code review usa instruções relevantes de AGENTS.md no repositório (GitHub Changelog, "Copilot code review: AGENTS.md support and UI improvements", 2026). O arquivo vira contrato compartilhado entre agentes e revisores.

Qual métrica mostra que o eval melhorou?

Use retrabalho de revisão. Em 2026, o GitHub relatou mais de 60 milhões de revisões processadas pelo Copilot code review (GitHub, "Agent pull requests are everywhere. Here's how to review them", 2026). Se o eval reduz comentários repetidos, PRs fora de escopo e falhas pós-merge, ele está funcionando.

Fechamento

Em 2026, a OpenAI escreveu que, com mais throughput de código, o gargalo passou a ser a capacidade humana de QA (OpenAI, "Harness engineering: leveraging Codex in an agent-first world", 2026). Evals de PR são a resposta prática: não deixam a IA decidir sozinha, mas obrigam cada mudança a chegar com prova.

Comece pequeno. Um template de PR, três comandos obrigatórios, uma lista de áreas sensíveis e uma regra de bloqueio já mudam a qualidade da revisão. Depois acrescente subagentes, rubricas semânticas e loops de melhoria. Agente bom não é o que escreve mais código. É o que entrega um PR que o time consegue verificar.

Fontes consultadas

• GitHub, "Agent pull requests are everywhere. Here's how to review them", recuperado em 2026-07-01, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
• GitLab, "AI Accountability Report", recuperado em 2026-07-01, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
• GitHub Changelog, "Copilot code review: AGENTS.md support and UI improvements", recuperado em 2026-07-01, https://github.blog/changelog/2026-06-18-copilot-code-review-agents-md-support-and-ui-improvements/
• OpenAI Developers, "Subagents", recuperado em 2026-07-01, https://developers.openai.com/codex/subagents
• Claude Code Docs, "Create custom subagents", recuperado em 2026-07-01, https://code.claude.com/docs/en/sub-agents
• OpenAI Developers, "Iterate on difficult problems", recuperado em 2026-07-01, https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems
• OpenAI, "Building self-improving tax agents with Codex", recuperado em 2026-07-01, https://openai.com/index/building-self-improving-tax-agents-with-codex/
• OpenAI, "Harness engineering: leveraging Codex in an agent-first world", recuperado em 2026-07-01, https://openai.com/index/harness-engineering/