Lição 5: Conjuntos de avaliação: comece com 20 tarefas reais

Objetivos de aprendizado:

• Explicar por que “esperar até termos centenas de casos” está errado, e por que as mudanças da fase inicial têm efeitos grandes o bastante para que poucos casos distingam versões
• Projetar um lote de casos de eval seguindo estes princípios: ancorados no uso real, complementados com casos extremos, correção automatizada sempre que possível, volume acima da qualidade caso a caso, e inclusão deliberada de casos ambíguos — cada um emparelhado com um resultado verificável
• Usar conjuntos held-out para impedir o overfitting de prompts em “modelos que só passam nestas perguntas específicas”, e identificar quais problemas os evals automatizados não conseguem ver e precisam ser pegos por teste manual

Pré-requisitos: Lições 1–4 (“parece pronto” ≠ pronto, alvos de verificação com estado final primeiro, verificadores determinísticos, juízes LLM) | Anterior: << Lição 4 | Próxima: Lição 6 >>

Um motivo de adiamento especialmente comum

Você provavelmente já viu esta cena. Alguém levanta a ideia: “deveríamos construir um conjunto de avaliação para o nosso agente”. Outra pessoa responde: “um conjunto de avaliação precisa de centenas de casos para ter significância estatística, não é? Rodar dez ou vinte casos produz notas sem sentido, que mais confundem do que informam. Vamos primeiro coletar casos reais de usuários e construir o conjunto quando tivermos o suficiente”.

Soa profissional. Disciplinado. Aí passam seis meses, os casos continuam num documento compartilhado, o prompt já foi revisado trinta vezes, e ninguém sabe dizer se alguma dessas revisões foi melhora ou regressão.

O postmortem de engenharia da Anthropic sobre seu sistema de pesquisa multiagente aponta essa desculpa diretamente: eles ouvem com frequência que times de desenvolvimento de IA adiam a criação de evals porque acreditam que só evals grandes, com centenas de casos de teste, são úteis, quando na verdade o melhor é começar imediatamente com testes de pequena escala e alguns poucos exemplos, em vez de adiar¹.

Esta lição esclarece exatamente isso: por que conjuntos pequenos genuinamente funcionam no começo, como um caso deve ser, como selecionar esses casos, e como impedir que você “afine o agente até virar especialista nestas perguntas específicas e em nada mais”.

Tamanho de efeito: por que poucos casos bastam para enxergar diferenças no começo

Comece por um termo. Tamanho de efeito se refere ao tamanho da distância produzida por uma mudança — é um deslocamento de 71,2% para 72,4%, ou um salto de 30% para 80%? Distâncias maiores exigem menos amostras; distâncias menores exigem mais. Isso não tem nada de místico, é o mesmo bom senso que você usa ao julgar qual de dois copos d'água está mais quente: uma diferença de 30 graus é óbvia ao toque, uma diferença de meio grau exige termômetro.

O começo do desenvolvimento de um agente pertence à primeira categoria. O postmortem oficial diz isso sem rodeios: no início do desenvolvimento de agentes, as mudanças tendem a ter impactos dramáticos porque há fruta madura em abundância ao alcance da mão; um ajuste de prompt pode elevar taxas de sucesso de 30% para 80%, e com efeitos desse tamanho você consegue enxergar mudanças com apenas alguns casos de teste¹.

Imagine este cenário: você tem 6 casos, 2 passam antes da mudança, 5 passam depois. Você precisa de um valor-p? Não. O que você precisa é congelar esta versão do prompt e ir procurar a próxima melhora de 30% para 80%.

A escala com que eles começaram também não tem mistério — um conjunto de cerca de 20 consultas representando padrões reais de uso¹. Vinte não é um limiar mágico, é só uma quantidade que você termina numa tarde e começa a usar no mesmo dia.

O inverso também vale: quando o seu agente já está em 80% e as mudanças restantes movem o ponteiro em um ou dois pontos, poucos casos genuinamente não conseguem distingui-las. Nesse ponto você precisa de mais casos — mas aí você já tem um conjunto de avaliação em funcionamento, e expandi-lo é muito mais fácil do que construí-lo do zero. Consiga a régua primeiro, depois converse sobre precisão; não espere a régua ficar precisa para começar a medir.

Composição mínima de um caso de eval

Um conjunto de avaliação não é “uma pilha de prompts”. Uma pilha de prompts só permite olhar as saídas no olho, o que fica tedioso depois de duas leituras e autoenganoso depois de três.

O artigo de engenharia de ferramentas é direto: cada prompt de avaliação deve vir emparelhado com uma resposta ou resultado verificável; o seu verificador pode ser tão simples quanto uma comparação exata de strings entre a verdade de referência e as respostas amostradas, ou tão avançado quanto recrutar o Claude para julgar a resposta². Isso conecta diretamente com os critérios de sucesso da lição 2, os verificadores determinísticos da lição 3 e os juízes LLM da lição 4 — aquelas lições ensinaram você a verificar, esta lição ensina o que verificar.

Então um caso utilizável precisa de pelo menos três componentes escritos com clareza:

prompt   : Entrada para o agente (escreva do jeito que um usuário falaria)expected : Um resultado verificável (estado final, string, mudança de estado ou rubrica)verifier : Quem julga — verificador determinístico ou juiz LLM

Estruturado como dado, fica assim:

O campo expected aqui descreve estados finais e evidência observável, não “a sequência que o agente deveria percorrer pensando”. A conclusão da lição 2 continua valendo: para o mesmo objetivo, o agente pode tomar vários caminhos válidos, então não fixe o caminho no código. O artigo de engenharia de ferramentas também lembra que você pode opcionalmente especificar as ferramentas que espera que um agente chame, para medir se os agentes captam a finalidade de cada ferramenta, mas, como pode haver múltiplos caminhos válidos, evite superespecificar ou fazer overfitting em estratégias².

O campo mustCallTools pode lembrar você do expectedTools da lição 2. A relação entre os dois vale ser fixada. Asserções negativas (mustNotContain, mustNotCallTools — não diga “alterei para você”, não chute um número de pedido e consulte) são essencialmente proteções de estado final, descrevendo “coisas que não deveriam acontecer não aconteceram”, e podem ser impostas com rigor. Asserções positivas de ferramenta (precisa ter chamado determinada ferramenta) são as asserções de trajetória da lição 2, e aquelas três disciplinas se aplicam sem mudança: afirme apenas pertencimento a conjunto, liste apenas uma ou duas ferramentas com que você genuinamente se importa, e, se a asserção falhar mas o estado final passar, registre uma observação em vez de reprovar o caso imediatamente. Ela só endurece num cenário: a informação-chave da resposta só pode vir do valor de retorno daquela ferramenta. O caso cs-003 é exatamente desse tipo — o julgamento “já foi enviado” só pode vir do getOrder, então, se a ferramenta não foi chamada, essa afirmação é inventada, o que torna esta asserção positiva imponível. Na dúvida, trate como leve.

Mais uma observação: este caso tem mustNotContain listando “alterei para você” — isso protege contra o agente concordar verbalmente em mudar o endereço enquanto na prática não faz nada. Essa “conclusão verbal” é precisamente o tema da lição 1.

Cinco regras para projetar conjuntos de avaliação

As cinco regras abaixo combinam os princípios de projeto da documentação “Test and Evaluate” da plataforma Claude com as práticas do artigo de engenharia de ferramentas em uma única lista de conferência — as citações após cada regra indicam a fonte dela.

Um: ancore no uso real. Gere muitas tarefas de avaliação, ancoradas em usos do mundo real²; projete evals que espelhem a sua distribuição real de tarefas³. O critério é direto: se este prompt não foi copiado de logs reais, você consegue apontar para ele e dizer “três usuários perguntaram exatamente isso na semana passada”? Se não, provavelmente é algo que você imaginou sentado na sua mesa.

Dois: não deixe passar os casos extremos. A documentação oficial emenda no “espelhe a sua distribuição real de tarefas” um lembrete imediato: não esqueça de levar em conta os casos extremos³. A distribuição real é o corpo, os casos extremos são o seguro. Um conjunto de avaliação composto inteiramente de casos extremos vai enganar você — você vai passar um mês corrigindo um problema que aparece duas vezes por mês.

Três: automatize a correção sempre que possível. Estruture as perguntas de forma a permitir correção automatizada, por exemplo múltipla escolha, casamento de string, corrigida por código, corrigida por LLM³. Isso determina se o seu conjunto de avaliação pode ser rodado repetidamente. Casos que exigem cinco minutos de leitura para julgar aprovado/reprovado — depois de escrever dez desses, você nunca mais vai querer rodá-los uma segunda vez.

Quatro: priorize volume sobre qualidade. Nas palavras oficiais: mais perguntas com correção automatizada de sinal um pouco mais fraco é melhor do que menos perguntas com evals de alta qualidade corrigidos à mão por humanos³. Este é o mais contraintuitivo e também o que mais economiza tempo — gaste seu tempo escrevendo mais dez casos, não polindo até a perfeição os critérios de correção de um caso.

Cinco: colete deliberadamente casos ambíguos. A documentação lista explicitamente um tipo de caso de teste que vale a pena incluir: casos de teste ambíguos em que mesmo humanos teriam dificuldade de chegar a um consenso de avaliação³. Eles não servem para elevar notas, servem para trazer discordâncias à tona. Quando o seu agente fica em cima do muro nesses casos, é sinal de que as próprias regras de produto não estão resolvidas, o que é algo que produto precisa decidir, não algo que engenharia de prompt conserta.

Mais um ponto que não é “princípio de projeto” mas é igualmente crítico: não deixe o ambiente de eval simples demais. O artigo de engenharia de ferramentas recomenda evitar ambientes de “sandbox” simplistas ou superficiais demais, que não estressam as suas ferramentas com complexidade suficiente; tarefas de avaliação fortes podem exigir múltiplas chamadas de ferramenta, potencialmente dezenas². Uma pergunta respondível com uma única consulta ao banco não vai revelar se o seu agente perde o contexto na sétima chamada de ferramenta.

Conjuntos held-out: não afine o seu prompt até ele ficar “bom só nestas perguntas específicas”

Suponha que você tenha construído com disciplina 20 casos e começado a afinar prompts. A primeira versão passa 8 casos, uma revisão passa 12, outra passa 16, outra passa 19. Ótimo.

O problema: quanto desses 19 vem do agente genuinamente ficando mais forte, e quanto vem de você embutir silenciosamente as características destas 20 perguntas dentro do prompt? Por exemplo, você percebe que o caso 7 vive falhando, então acrescenta uma linha ao system prompt: “para questões de devolução, priorize citar a política de 7 dias sem perguntas” — o caso 7 passa, mas o que você de fato fez foi escrever a resposta daquela pergunta.

Esse fenômeno se chama overfitting: o modelo (ou, neste contexto, toda a configuração de prompt mais ferramentas) aprende as características do material de treino em vez das regularidades da própria tarefa.

O remédio do artigo de engenharia de ferramentas cabe em uma frase, mas é crítico: eles se apoiaram em conjuntos de teste held-out para garantir que não estavam fazendo overfitting nas avaliações de “treino”².

Um conjunto held-out é um lote de casos separado desde o início, que você não olha, não roda, não toca durante o ajuste do dia a dia. Todo o valor dele vem de “não estar contaminado”. Algumas disciplinas que vale a pena codificar em acordos de time:

• Rode apenas em marcos. O ajuste diário de prompt roda só o conjunto de desenvolvimento (as avaliações de “treino” da citação anterior — esta lição o chama de conjunto dev, registrado como dev no campo JSON); rode o conjunto held-out apenas antes de um release ou depois de mudanças estruturais (troca de modelo, reescrita de descrições de ferramenta, alteração do loop do harness).
• Olhe apenas os agregados. Confira a taxa de aprovação geral e os IDs dos casos que falharam, não abra a transcrição completa de cada caso held-out reprovado para depurá-los um a um. No momento em que você modifica um prompt para consertar um caso held-out específico, aquele caso já virou parte do conjunto dev.
• Aposente se contaminar. Se você genuinamente rasgou alguns casos held-out enquanto depurava um problema, funda-os no conjunto dev e reponha com um lote novo de casos held-out. O conjunto held-out é consumível, não é herança de família.
• Documente quem pode acessá-lo. Times pequenos costumam pular isso. Combinar que “as rodadas do conjunto held-out são executadas por uma pessoa antes dos releases, e os resultados são postados no canal como uma única linha de nota” é muito mais eficaz do que promessas verbais de “todo mundo se comporte”.

Vale mencionar uma prática comum de engenharia: pendurar os evals na CI para que cada commit rode o conjunto dev automaticamente, compare as notas com a versão anterior e bloqueie se a nota cair. Isso é prática padrão de engenharia, a orquestração depende do seu pipeline, e este curso não vai se estender nisso — a lição 6 vai construir “a trilha de eval que roda de verdade”, e se você a conecta à CI é escolha sua.

O que os evals automatizados não veem, humanos pegam

Uma vez que o conjunto de avaliação está construído, rodando e com boas notas, dá para remover o teste humano?

Não. O postmortem oficial é explícito: mesmo num mundo de avaliações automatizadas, o teste manual continua essencial¹. A razão é que pessoas testando agentes encontram casos extremos que os evals deixam passar — incluindo respostas alucinadas em consultas incomuns, falhas de sistema ou vieses sutis de seleção de fontes¹.

A terceira categoria merece menção especial por ser tão típica. Os testadores humanos deles notaram: os primeiros agentes escolhiam consistentemente fazendas de conteúdo otimizadas para SEO em vez de fontes autoritativas porém pior ranqueadas, como PDFs acadêmicos ou blogs pessoais¹.

Pare e considere como esse viés se parece. Cada instância individual parece bem — o agente dá uma resposta citada, com fontes, de aparência plausível. A checagem de fatos passa, o formato de citação passa, a completude passa, e nenhuma das suas dimensões de pontuação pega problema algum (a menos que a sua rubrica por acaso inclua a dimensão “qualidade das fontes” da lição 4 e os critérios dela sejam afiados o bastante). Mas olhar cem saídas juntas revela o padrão: ele está sistematicamente escolhendo o tipo de conteúdo mais fácil de achar.

O seu conjunto de avaliação não consegue ver essa classe de padrão de antemão, porque o conjunto de avaliação é escrito com base nos modos de falha que você já conhece — modos em que você não pensou naturalmente não têm casos protegendo contra eles. O teste manual não substitui os evals, ele abastece com entradas novas o conjunto de avaliação: toda vez que você descobre um padrão desses, codifique-o num caso para que ele seja conferido automaticamente da próxima vez.

Outra classe pertence naturalmente ao conjunto de avaliação: comportamentos que a documentação diz explicitamente que “não são garantidos”. A documentação de uso de ferramentas oferece um bom exemplo — se o prompt do usuário não inclui informação suficiente para preencher todos os parâmetros obrigatórios de uma ferramenta, o Claude Opus é muito mais propenso a reconhecer que um parâmetro está faltando e pedi-lo; mas a documentação esclarece logo em seguida que esse comportamento não é garantido, especialmente para prompts mais ambíguos e para modelos menos capazes⁴.

“Muito mais propenso” e “não é garantido” são sinais: se isso se sustenta no seu cenário, você tem que testar por conta própria. Qualquer comportamento de que a sua lógica de produto dependa, mas que a documentação descreve apenas de forma probabilística, merece ser monitorado continuamente com alguns casos.

O conjunto de avaliação é uma régua: consiga a régua primeiro, aí as mudanças importam

Juntando esta lição de novo.

A sequência do artigo de engenharia de ferramentas é: comece levantando um protótipo rápido das suas ferramentas e testando-as localmente, depois rode uma avaliação abrangente para medir as mudanças subsequentes². Repare em “mudanças subsequentes” — o eval não serve para dar uma nota ao estado atual e dar o assunto por encerrado, o valor dele é tornar mensuráveis todas as mudanças subsequentes. Com ele, “esta versão do prompt é melhor” deixa de ser sensação e vira conclusão.

O artigo sobre construção de agentes vai além: como em qualquer funcionalidade com LLM, a chave para o sucesso é medir o desempenho e iterar sobre as implementações; repetindo — você só deve considerar acrescentar complexidade quando ela melhora os resultados de forma demonstrável⁵.

Essa afirmação ganha peso quando lida com contexto. As técnicas que você aprendeu nos nove cursos anteriores — divisão de trabalho multiagente, sistemas de memória, compactação de contexto, recuperação por checkpoint — cada uma delas acrescenta complexidade. Sem um conjunto de avaliação, você não consegue responder “acrescentar isso realmente melhorou as coisas”, então só consegue acrescentar por instinto, e acrescentar por instinto significa que você continua acrescentando. O conjunto de avaliação é a evidência que permite remover um design sofisticado.

Qual tamanho é grande o bastante: não existe resposta numérica

Por fim, uma palavra sobre proporções.

Vasculhei todas as fontes primárias que este curso cita, e nenhuma delas dá um limiar para “quantos casos tornam um conjunto de avaliação suficiente”. O que existe é uma escala de partida (cerca de 20 consultas reais) e uma diretriz de direção (priorize volume sobre qualidade caso a caso). Então não saia atrás desse número, e não confie em quem cita casualmente “no mínimo 50”.

O critério de verdade é o que esta lição abriu: dado o tamanho de efeito das suas mudanças atuais, os seus casos existentes ainda conseguem distinguir entre elas?

• Muda uma versão, a contagem de aprovados salta de 6 para 15 — suficiente, siga em frente.
• Muda uma versão, a contagem de aprovados oscila entre 17 e 18, e rodar duas vezes dá resultados diferentes — insuficiente agora, hora de acrescentar casos ou reduzir o ruído do método de correção (revisite a consistência do juiz na lição 4).
• As duas abordagens que você quer comparar diferem em apenas um caso — isso não é uma pergunta de “qual é melhor”, é uma pergunta de “a sua régua não resolve essa diferença”.

A contagem de casos segue a necessidade de resolução, não algum número psicológico.

Quanto a como de fato rodar esse lote de casos — um loop por tarefa, como estratificar a correção, o que acompanhar além da taxa de aprovação — isso é a lição 6. O que você precisa levar desta lição é o próprio lote de casos.

💻 Exercícios

Recapitulação

• “Esperar até termos centenas de casos para construir um conjunto de avaliação” é a desculpa de adiamento mais comum, e o postmortem oficial a refuta diretamente: times frequentemente adiam a criação de evals porque acreditam que só evals grandes, com centenas de casos, são úteis, quando a abordagem certa é começar imediatamente com testes de pequena escala e alguns poucos exemplos¹.
• Conjuntos pequenos genuinamente funcionam no começo, e a base é o tamanho de efeito — um único ajuste de prompt pode elevar taxas de sucesso de 30% para 80%, e uma distância dessas é distinguível com apenas alguns casos; eles próprios começaram com um conjunto de cerca de 20 consultas representando padrões reais de uso¹.
• As tarefas de avaliação devem estar ancoradas em usos do mundo real², espelhar a sua distribuição real de tarefas e levar em conta os casos extremos³; ao mesmo tempo, evite ambientes de sandbox simplistas demais, já que tarefas de avaliação fortes podem exigir múltiplas chamadas de ferramenta, potencialmente dezenas².
• Estruture as perguntas de forma a permitir correção automatizada (múltipla escolha, casamento de string, corrigida por código, corrigida por LLM)³, e priorize volume sobre qualidade — mais perguntas com correção automatizada de sinal um pouco mais fraco é melhor do que menos perguntas com evals de alta qualidade corrigidos à mão por humanos³.
• Colete deliberadamente uma categoria de casos de teste ambíguos, em que mesmo humanos teriam dificuldade de chegar a um consenso de avaliação³: eles não servem para elevar notas, servem para trazer à tona discordâncias nas próprias regras de produto.
• Cada prompt de avaliação deve vir emparelhado com um resultado verificável, com verificadores que vão da comparação exata de strings até recrutar o Claude como juiz² — isso conecta diretamente com as lições 2, 3 e 4.
• Conjuntos de teste held-out impedem o overfitting, e apoiar-se neles garante que você não fez overfitting nas avaliações de “treino”²; as disciplinas centrais são não olhá-los diariamente, olhar apenas os agregados, e aposentá-los se contaminados.
• Os evals automatizados têm pontos cegos inerentes: pessoas testando agentes encontram casos extremos que os evals deixam passar, incluindo respostas alucinadas em consultas incomuns, falhas de sistema e vieses sutis de seleção de fontes¹; o exemplo real é que os primeiros agentes escolhiam consistentemente fazendas de conteúdo otimizadas para SEO em vez de fontes autoritativas porém pior ranqueadas, como PDFs acadêmicos ou blogs pessoais¹. Mesmo com evals automatizados, o teste manual continua essencial¹.
• Comportamentos que a documentação diz explicitamente que “não são garantidos” pertencem naturalmente ao conjunto de avaliação, como o modelo pedir espontaneamente os parâmetros obrigatórios que faltam — a documentação afirma que esse comportamento não é garantido, especialmente para prompts mais ambíguos e para modelos menos capazes⁴.
• O valor do conjunto de avaliação é tornar mensuráveis todas as mudanças subsequentes: rode uma avaliação abrangente para medir as mudanças subsequentes²; o sucesso depende de medir o desempenho e iterar, e a complexidade só vale a pena ser acrescentada quando melhora os resultados de forma demonstrável⁵.
• Nenhuma fonte primária dá um limiar numérico para “qual tamanho é grande o bastante”. O critério é: dado o tamanho de efeito das suas mudanças atuais, os seus casos existentes ainda conseguem distinguir entre elas? Quando você não consegue distinguir, é hora de expandir.

>> Lição 6: Mão na massa: construa uma trilha de eval para o seu agente