Teste de regressão de prompt: como saber se a mudança no prompt do seu app com LLM não piorou as respostas antes de publicar

Mexer no system prompt sem um conjunto fixo de casos é publicar no escuro: o ajuste que corrige um caso pode quebrar outro que já funcionava

Fala aí, beleza? Se tu mantém um app com LLM e vai reescrever uma instrução, trocar um exemplo ou reorganizar o system prompt (sem trocar de modelo), esse post é pra você 🙂

A ideia é simples: antes de publicar, rodar o prompt antigo e o novo contra os mesmos casos reais e ver o que melhorou e o que piorou

Isso tem nome: eval. A OpenAI define evals como testes estruturados para medir o desempenho de um modelo, e explica no guia de boas práticas de avaliação por que teste de software tradicional não basta aqui: o mesmo input pode gerar outputs diferentes

Bora ver na prática?

Por que um ajuste no prompt quebra respostas que já funcionavam

Porque o prompt é UM contrato só para todos os casos do seu app

Você mexe pensando no bug que apareceu ontem, mas a instrução nova também vale para as centenas de perguntas que você não estava olhando

Reescrever uma regra, mudar a ordem das instruções ou trocar os exemplos muda o comportamento do modelo no conjunto inteiro, não só no caso que te incomodou

E quanto mais camadas de instrução você empilha (quem trabalha com meta-prompting no GSD sabe bem como isso cresce), mais difícil fica prever esse efeito de cabeça

Aí entra o segundo problema: o não determinismo

Testar 2 ou 3 perguntas na mão e achar que ficou bom não distingue melhora real de sorte, já que a mesma pergunta pode sair diferente na próxima execução

A Anthropic vai na mesma linha no guia de definição de critérios de sucesso: um app com LLM começa com critérios específicos e mensuráveis, senão a engenharia de prompt fica sem alvo

Ou seja, sem critério, "ficou melhor" é só impressão 😛

O que você precisa antes de começar

Nada de PC da Nasa, se liga na lista:

• A versão atual do prompt guardada: ela é o seu baseline, o ponto de comparação. Sem ela não existe "antes"
• Exemplos reais de produção: perguntas e entradas que usuários de verdade mandaram para o app
• Um critério de sucesso por caso: o que conta como resposta aprovada para aquela entrada
• Acesso ao mesmo modelo que o app já usa: o teste muda o prompt, não o modelo. Se trocar os dois juntos, você não sabe quem causou a diferença

Um aviso importante sobre ferramenta, porque o cenário mudou este ano

A OpenAI anunciou em 3 de junho de 2026 a descontinuação da plataforma Evals (dashboard e API), conforme a página de deprecations: as evals existentes ficam somente leitura em 31 de outubro de 2026, e o dashboard e a API serão desligados em 30 de novembro de 2026

Na própria documentação, a OpenAI indica o Promptfoo como caminho de migração

E tem contexto: a OpenAI anunciou a aquisição do Promptfoo em 9 de março de 2026, e o projeto segue open source sob a licença atual (MIT)

Por isso os exemplos de ferramenta deste post usam o Promptfoo. O método, porém, vale para qualquer ferramenta (ou até planilha + script)

Passo 1: monte um conjunto fixo de casos reais, incluindo os que já falharam

O conjunto de casos é a base de tudo, e ele precisa ser FIXO entre uma versão e outra do prompt

Três regras para montar:

• Puxe da produção: o guia da OpenAI recomenda que os exemplos venham da produção, não de dados sintéticos
• Espelhe a distribuição real e inclua edge cases: a Anthropic recomenda, no guia de criação de testes, que as evals reflitam a distribuição real das tarefas e incluam casos extremos. Se a maior parte do tráfego é dúvida simples, a maior parte do conjunto também deve ser
• Todo incidente vira teste permanente: cada caso que já deu problema em produção entra no conjunto e não sai mais

Uma estrutura de planilha que funciona bem (as linhas abaixo são fictícias, só para ilustrar o formato, e não trazem resultado nenhum):

A coluna "crítico" é o que vai decidir o bloqueio lá no Passo 5, então preencha agora, com calma, e não depois de ver o resultado

E sobre tamanho: a Anthropic diz que mais casos com avaliação automática, mesmo com sinal um pouco menor, valem mais do que poucos casos avaliados à mão por humanos

Traduzindo: melhor um conjunto grande com critério automático do que meia dúzia de perguntas que você confere no olho

Erro comum deste passo: testar só os casos que motivaram a mudança e esquecer os que já funcionavam. É justamente ali que a regressão se esconde

Passo 2: defina o critério de aprovação de cada caso

Cada caso precisa de uma regra clara de "passou ou não passou", e o tipo de regra muda conforme o caso

As opções, com os limites de cada uma:

• Correspondência exata e regras por código: segundo a Anthropic, é a avaliação mais rápida, confiável e escalável, mas perde nuance em julgamentos complexos. Serve muito bem para formato, presença de um dado, idioma detectável por padrão e por aí vai
• Rubrica: uma lista de critérios do que a resposta precisa ter (ou não pode ter), usada quando o certo não é uma string fixa
• LLM como juiz: outro modelo avalia a resposta. A Anthropic descreve como rápido, flexível e bom para julgamentos complexos, mas avisa que a confiabilidade dele deve ser testada antes de escalar

No Promptfoo, isso vira asserções que já existem na ferramenta:

• Determinísticas: equals, contains, is-json, regex
• Semântica: similar
• Avaliadas por modelo: llm-rubric, factuality, g-eval

Tome cuidado com a llm-rubric: ela manda a saída para outro LLM dar a nota com base numa rubrica, e isso gasta tokens a cada caso, a cada execução

Se for usar LLM como juiz, as boas práticas das duas documentações se somam:

• Rubrica detalhada e clara (Anthropic)
• Saída restrita, tipo correct/incorrect ou escala de 1 a 5 (Anthropic)
• Pedir que o modelo raciocine antes de dar a nota e descartar esse raciocínio depois, ficando só com a nota (Anthropic)
• Preferir comparação em pares, classificação ou nota contra critérios específicos, em vez de geração aberta, porque LLMs discriminam melhor entre opções (OpenAI)
• Controlar o tamanho da resposta, porque o avaliador LLM costuma favorecer respostas mais longas (OpenAI)

Esse último é traiçoeiro: o prompt novo pode "ganhar" só porque deixou a resposta maior, e não melhor…

Erro comum deste passo: usar LLM como juiz para tudo, inclusive onde uma regex ou um is-json resolveria. Fica mais caro, mais lento e menos confiável sem necessidade

Passo 3: rode o prompt antigo e o novo sobre o mesmo conjunto e compare lado a lado

A lógica é: as duas variantes do prompt, os mesmos casos, o mesmo critério, o mesmo modelo

Aí você olha caso a caso o que passava e deixou de passar (e o que falhava e passou a funcionar), em vez de olhar só a média

O Promptfoo é uma ferramenta local que avalia e compara saídas de LLM, coloca variantes de prompt lado a lado e serve exatamente para pegar regressões, segundo a documentação de primeiros passos

O fluxo básico tem três comandos:

1. Criar os arquivos iniciais do projeto, entre eles o promptfooconfig.yaml, onde ficam a configuração da avaliação:

npx promptfoo init

2. Rodar a avaliação, a partir do diretório que contém o promptfooconfig.yaml:

npx promptfoo eval

3. Abrir o visualizador web dos resultados:

npx promptfoo view

No promptfooconfig.yaml você descreve os prompts, o modelo e os casos com as asserções do Passo 2. A sintaxe exata para declarar as duas versões do prompt está na documentação oficial do Promptfoo, vale conferir lá antes de escrever o arquivo

Checagem: no visualizador, cada caso precisa aparecer com o resultado das duas versões do prompt. Se só uma versão aparece, a comparação não está montada

Erro comum deste passo: editar o conjunto de casos junto com o prompt. Se os casos mudaram, a diferença no resultado pode vir dos casos e não do prompt, e aí não dá para comparar nada

Passo 4: trate a variação entre execuções antes de declarar regressão

Uma falha isolada pode ser só variação, não regressão

Lembra do não determinismo que a OpenAI cita? Ele vale para os dois lados: um caso pode falhar uma vez por azar e um prompt pior pode passar uma vez por sorte

A saída é rodar cada caso mais de uma vez e olhar a consistência. No Promptfoo isso é a flag --repeat, que, segundo a documentação de linha de comando, define quantas vezes cada caso roda (o padrão é 1):

npx promptfoo eval --repeat N

Troque N pelo número de repetições que você escolher. A mesma página mostra que dá para configurar esse comportamento em evaluateOptions.repeat

Não existe número mágico de repetições aqui, e desconfie de quem vender um 😛

O que importa é definir a sua regra ANTES de rodar, por exemplo: quantas repetições, e quantas falhas num caso contam como "falhou de forma consistente". Decidir a regra depois de ver o resultado é ajustar o teste para dar o resultado que você queria

Lembrando que mais repetições multiplicam o custo, principalmente se tiver LLM como juiz no meio

Essa mesma ideia de repetir prompts para separar padrão de acaso aparece no teste de AEO com prompts repetidos, só que aplicada a outro problema

Erro comum deste passo: rodar uma vez só, ver um caso falhar (ou passar) e decidir com base nisso

Passo 5: quando bloquear a publicação do novo prompt

Bloqueia quando um caso que importa piorou de forma consistente, mesmo que a média tenha melhorado

Regras de decisão que fazem sentido, definidas antes de rodar:

• Bloquear se um caso marcado como crítico que passava no prompt antigo passa a falhar de forma consistente nas repetições
• Bloquear se um caso vindo de incidente de produção volta a falhar. Esse bug você já pagou uma vez, né?
• Revisar manualmente quando a diferença entre as versões vier só de um LLM juiz que você ainda não validou

E para isso não depender de alguém lembrar de rodar, a OpenAI recomenda levar as evals ao pipeline de entrega: começar por um conjunto compacto (smoke set) que cubra as jornadas críticas do usuário e rodar esse conjunto a cada pull request

O Promptfoo roda em CI, então dá para encaixar essa etapa no mesmo fluxo onde o resto do código já é testado

Checagem final: nenhum caso crítico regrediu e as melhorias que motivaram a mudança aparecem nos casos alvo. Se só a primeira condição vale, o prompt novo não piorou, mas também não resolveu o que você queria

Erro comum deste passo: decidir pela média geral e aceitar que um caso crítico piorou porque outros melhoraram. Para o usuário que caiu naquele caso, o app simplesmente quebrou

O mesmo conjunto de testes serve para trocar de modelo

Sim, e esse é o melhor reaproveitamento do trabalho que você teve até aqui

O gatilho deste post é editar o prompt na manutenção contínua, com o modelo parado. O caso vizinho é o contrário: o prompt fica e quem muda é o modelo

Os casos reais, os incidentes e os critérios são os mesmos. Muda só a variável que você compara: no lugar de duas versões do prompt, entram dois modelos rodando o mesmo prompt

E com o tempo, a parte crítica desse conjunto vira o seu smoke set rodando em todo pull request, seja qual for a mudança

Vídeo complementar do canal

Falando em gasto de tokens (que cresce rápido com repetições e LLM como juiz), fica aqui um conteúdo do Hora de Codar: um teste completo do FreeLLMAPI 🙂

Próximo passo: transforme o próximo bug de produção no primeiro caso do conjunto

Antes da próxima edição do prompt, faz assim:

• Salve a versão atual do prompt como baseline
• Registre os casos reais e o último caso que falhou em produção, cada um com o critério definido e marcado como crítico ou não
• Rode o prompt antigo e o novo sobre esse conjunto e só publique se nenhum caso crítico regrediu

Se esse conjunto ainda estiver na plataforma Evals da OpenAI, se liga nas datas: somente leitura em 31 de outubro de 2026 e desligamento em 30 de novembro de 2026. Melhor migrar antes, sem pressa de última hora

Até o próximo post!

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.