Prompt com
placar de regressão.
Prompt tem contrato de entrada e saída e costuma ser tratado como texto solto: testado no chat, salvo em nota, esquecido. Quando o modelo é atualizado meses depois, a degradação passa despercebida por falta de linha de base. Aqui o prompt, os casos e as asserções ficam no mesmo arquivo.
Seções desta página
Narrativa
Um prompt em produção não tem linha de base. Ele funciona quando foi escrito, o modelo muda meses depois, e a queda de qualidade aparece como impressão de quem lê a saída. Sem caso registrado e asserção verificável, não há como separar degradação do modelo de mudança no que se espera dele.
Cada lente é um arquivo YAML com quatro partes, que correspondem às competências do framework de AI Fluency: task para o que se delega e o que fica com o humano, versions para o prompt com histórico preservado, checks para as asserções e provenance para modelo, revisor, data e limite de uso da saída.
O campo provenance.nao_decide é obrigatório e o parser recusa a lente sem ele. Ele registra o limite de uso da saída, que é a informação que some primeiro quando um prompt circula pelo time. Fixtures gravadas por versão e por caso permitem que o placar rode em CI sem chave e sem custo.
A lente de nomear segmento tem três versões no arquivo, e a diferença entre elas é verificável. A v1 pedia o nome sem especificar formato, e o modelo devolvia título em prosa em dois dos cinco casos. A v3 declara o formato de saída em duas linhas e passa em todos. O CI trava a regressão nos dois sentidos.
O histórico de versão, executável
As três versões da lente de nomear segmento continuam no arquivo, e todas continuam executáveis. A diferença entre elas deixa de ser lembrança e vira resultado de comando.
Execuções do harness
✓ a v3 precisa passar
O sentido óbvio da trava. Se a versão corrente parar de passar, alguma coisa mudou: o prompt, a asserção ou o modelo.
✕ a v1 precisa continuar falhando
O sentido que quase ninguém escreve. Se a v1 parar de falhar, a asserção formato_snake_case quebrou, e o placar passaria a dar verde para tudo sem que ninguém percebesse.
Somar checagem de código e juiz-modelo num número único dá ao resultado uma precisão que a segunda metade não tem.
A anatomia de uma lente
Quatro partes no mesmo arquivo, que correspondem às competências do framework de AI Fluency. O prompt sem os casos é texto solto, e os casos sem o limite de uso são um convite a usar a saída para o que ela não serve.
# 1. o que se delega e o que fica com a pessoa
task:
delega: propor nome de uso interno a partir da definição do filtro
humano_decide: aprovar o nome e publicar no dicionário de segmentos
# 2. o prompt, com o histórico preservado e executável
versions:
- id: v1 # sem formato declarado
- id: v2
- id: v3 # formato de saída declarado em duas linhas
# 3. as asserções, com a família explícita
checks:
- nome: formato_snake_case familia: codigo
- nome: so_cita_entrada familia: codigo
- nome: sem_antitese familia: codigo
- nome: justifica_a_escolha familia: juiz
# 4. de onde veio e até onde vale
provenance:
modelo: <id do modelo avaliado>
revisor: Danilo Espeleta
data: 2026-01-14
nao_decide: não substitui a aprovação do dicionário de segmentos ← obrigatórioAs cinco lentes
Uma por tarefa recorrente de operação. Cada uma tem um contrato de entrada e de saída, e é esse contrato que as asserções verificam.
| Lente | Recebe | Devolve |
|---|---|---|
| nomear-segmento | a definição técnica do filtro | o nome de uso interno, com justificativa |
| diagnostico-queda | a série temporal de uma métrica | hipóteses ordenadas por custo de teste |
| copy-por-estagio | estágio de ciclo de vida e proposta de valor | variações, com a hipótese que cada uma testa |
| leitura-cancelamento | respostas abertas de pesquisa de churn | eixos de motivo com contagem e citação, restrito ao texto |
| auditoria-tom | as mensagens numeradas de uma régua | onde o registro quebra entre elas |
O placar não soma as famílias
As duas famílias medem coisas com confiabilidade diferente, então o relatório as imprime separadas e com rótulo. Números de uma lente, na versão corrente:
Determinística, reproduzível e sem custo de API. Oito checagens registradas em checks.py cobrem formato, contenção e padrões de texto.
Usa modelo para julgar o que forma não alcança. Carrega o viés do próprio juiz, e é por isso que aparece com rótulo em vez de diluída no total.
o relatório não soma as duas famílias num placar único
Reprova qualquer número da saída que não esteja na entrada. Ela cobre o modo de falha mais caro em análise de CRM, que é o modelo produzir um valor plausível e ninguém conferir.
Reprova o padrão "X não é A, é B". Em densidade alta ele funciona como assinatura de texto gerado por modelo, e a regra entrou aqui depois de aparecer em revisão de texto meu.
Limitações
As asserções cobrem forma, e a maior parte do valor de uma lente está no conteúdo. contagem_itens verifica que vieram quatro hipóteses, sem avaliar se são boas hipóteses. O juiz-modelo cobre parte dessa distância, com o viés que a marcação de família torna visível.
As fixtures envelhecem. Uma saída gravada há seis meses testa as asserções contra o comportamento de um modelo que mudou, e regravar é operação manual.
A suíte
Três repositórios sobre a mesma tese: jornada de cliente é artefato versionável. Se ela pode ser declarada em arquivo, ela pode ser lida, auditada e revisada em pull request, com histórico e revisão por pares. Hoje ela vive dentro da interface da ferramenta de automação, onde não existe diff entre versões nem registro de por que aquele delay é de 48 horas.
A saída de um é a entrada do outro, o que torna objetivo o critério de aceite do agente: a jornada proposta precisa passar no linter.
Lê as jornadas declaradas em YAML e acusa o defeito antes da publicação, inclusive o que só existe entre duas réguas.
Lê os eventos de produto e devolve o briefing de segmento com a jornada proposta, já validada pelo linter.
Guarda os prompts de leitura versionados, com asserções verificáveis e placar que mede regressão em CI.
Esta página