Abertura

Sexta-feira, cinco da tarde. Alguém do time de produto abre o painel de configurações e edita o prompt do classificador de tickets.

Troca a palavra urgente por alta prioridade, para soar um pouco mais educado. Ninguém roda teste. Afinal, é só texto.

Na segunda, a fila de urgentes está vazia. O código que lia a resposta do modelo procurava a palavra urgente. Metade dos tickets críticos passou o fim de semana inteiro na fila comum.

O prompt era uma interface. Ninguém tratou como uma. Nesta aula, você vai ver o que é tratar assim, e as quatro perguntas que transformam um prompt de rascunho em contrato.

A ideia

Um prompt de produção é um contrato de API entre o seu código e o modelo. Ele tem as mesmas partes de qualquer interface que você já versiona e testa. Você nunca deixaria alguém renomear um campo de uma API pública por um painel, numa sexta à tarde. O prompt merece o mesmo respeito.

Como funciona

Vamos percorrer o contrato. O código que chama sabe exatamente o que manda e o que espera de volta.

A entrada tem um formato definido. Quais variáveis, de que tipo e de onde vêm.

O prompt tem nome, versão e dono. Mudar o prompt é mudar a interface.

A saída segue um schema, com campos fixos, não um texto livre que alguém vai ter que interpretar.

O código valida essa saída antes de usar, igual faria com a resposta de qualquer API externa.

E um conjunto de casos de teste, o eval, roda contra toda versão nova do prompt.

Aquela sexta à tarde quebrou os passos quatro e seis ao mesmo tempo. A palavra na saída fazia parte do contrato. E ninguém tinha um teste que falhasse quando ela mudou.

As quatro perguntas

Antes de qualquer prompt ir para produção, responda quatro perguntas.

Entrada. O que entra, e de onde? No classificador: título e corpo do ticket, em texto simples, com dados pessoais já removidos.

Saída. Que formato sai? Um campo de prioridade que só pode ser urgente ou normal, e um campo de motivo com uma explicação curta.

Versão. Como eu sei qual rodou? Classificador de tickets, versão sete, registrada em todo trace.

Teste. Como eu sei que não piorou? Duzentos tickets rotulados, rodados a cada mudança.

Se alguma resposta for não sei, o prompt ainda é rascunho. Mesmo que já esteja em produção.

E na entrada, escreva também o que não pode entrar. Ticket de banco no Brasil vive trazendo CPF, chave Pix ou pedaço de comprovante. Isso é dado pessoal pela LGPD. O contrato diz que o seu código mascara isso antes da chamada. E o eval tem um caso provando que dado sensível não vaza para o provedor.

Isso vale para os casos de teste também. Repositório privado não cancela a lei. Se um CPF real está num caso de teste, ele vai para o provedor a cada rodada do eval. Mascare o caso também.

Um desafio

Uma pergunta para você. Na segunda, a fila de urgentes está vazia. O trace de sexta diz classificador de tickets, versão sete. Mas o painel de configurações não registra versão nenhuma. O que isso já te diz?

Diz que a mudança passou por fora do contrato. O trace diz versão sete, mas o texto que rodou de fato não é a versão sete do repositório. Você não consegue ligar o que rodou ao arquivo versionado. Então o trace não ajuda a investigar.

E só um eval também não salvaria. Ele testaria o arquivo do repositório, enquanto a produção roda outra coisa. O próximo passo é tirar o prompt do painel, versionar o arquivo e recusar qualquer saída que o schema não conhece.

Os erros comuns

A armadilha mais comum é justamente esse painel de configurações. Parece inofensivo, porque o texto está ali, visível. Na prática, é um deploy sem diff, sem revisão e sem eval.

E quem editou na sexta não foi irresponsável. O caminho que o produto oferecia é que estava errado. Conserte o caminho, não a pessoa.

O outro extremo também quebra. Três cópias do mesmo prompt, em três serviços, cada uma quase igual. Um bug é corrigido numa, e as outras duas ficam desatualizadas. Esse smell se chama scattered prompt strings. A cura é um template versionado só, reaproveitado por todos os serviços.

E tem um mais discreto. Digamos que o schema pede prioridade e motivo. Em 4% dos casos, o modelo devolve só a prioridade. E o código preenche um motivo padrão em silêncio e segue. É a mesma fragilidade de procurar a palavra urgente no texto. Saída incompleta tem que falhar na validação, e ir para um retry ou uma fila de revisão. Se o campo é mesmo opcional, diga isso no schema.

Experimente

Agora pegue um prompt seu e escreva o contrato dele, em cinco minutos, num arquivo bem ao lado do prompt. Um nome, uma versão, um dono.

O que entra, e o que precisa ficar de fora.

Se você não conseguiu preencher a saída sem hesitar, o seu código provavelmente interpreta texto livre. Isso é um smell chamado free text handoff.

E se não tem nada para colocar ao lado de eval, isso é untested prompt.

Depois, compare o contrato com o código que consome a saída. Se o código procura uma palavra em português e o contrato promete um valor em inglês, você acabou de achar o bug de sexta antes de ele acontecer. E a correção não é traduzir o schema. É ler só o campo validado e apagar a busca pela palavra.

Em produção

Então, o que muda na prática? O prompt mora no repositório, num arquivo próprio. Não espalhado como texto pelo código.

Mudança de prompt passa por revisão, como qualquer outra mudança de código.

A saída nunca é lida procurando uma palavra no texto. Ela é lida de um campo.

E toda chamada registra a versão do prompt no trace, para você saber o que rodou quando algo dá errado.

E uma mudança pequena também segue o ritual. Digamos que o produto quer um resumo de cinco frases em vez de três. Você sobe a versão, roda o eval e só publica se a checagem de tamanho continuar passando. O objetivo não é um prompt que nunca muda. É um prompt que dá para mudar com teste, e com caminho de volta.

Fechamento

Então, a ideia para levar. Tratar o prompt como interface não torna o modelo determinístico. Deixa o resto do sistema pronto para quando ele não for. E faz o seu time perder o medo de mexer nele.

Na próxima aula, a gente vê o que acontece quando essa interface cresce e ninguém poda: o prompt inchado, em que cada incidente deixou uma regra. Até lá.