Prompt Sem Versão

Como reconhecer

Um pipeline de conteúdo gera posts para o blog de uma marca. Um deles viralizou, e o time de marketing quer outros iguais. A conversa no canal do time (anonimizada):

mkt:  qual prompt gerou o post sobre home office? queremos repetir
eng:  o prompt atual é este aqui
mkt:  testamos, não sai parecido
eng:  então mudou depois. o post é de 12/08, deixa eu ver o git
eng:  o prompt está no banco, numa tabela de config. não tem histórico
eng:  alguém editou pelo painel admin em agosto, mas não sei quando nem o quê

O post existe. O prompt que o gerou, não mais.

O mesmo buraco aparece quando um cliente pede, com base na LGPD, o que o assistente fez com os dados dele. O log tem a resposta. Não tem o texto que a produziu. Sem versão, não há auditoria de verdade.

Sinais de Prompt Sem Versão:

• O prompt pode ser editado (em código, banco ou painel) sem gerar uma versão nova com identificador.
• O trace ou o log não registram qual versão do prompt gerou cada resposta.
• Não dá para reproduzir uma resposta antiga.
• Reclamações sobre uma resposta de semanas atrás não têm como ser investigadas.
• Voltar a uma versão anterior exige lembrar o texto antigo.

flowchart LR
  E((("1. Alguém edita o prompt"))):::human --> P[("2. Prompt sobrescrito")]:::store
  P --> M(["3. Respostas novas"]):::llm
  M --> L[("4. Log sem versão")]:::store
  L --> Q{"5. Qual prompt gerou isto?"}

1. Alguém melhora o prompt.
2. A versão anterior deixa de existir.
3. As respostas mudam.
4. O registro guarda a resposta, mas não a versão que a gerou.
5. Semanas depois, ninguém consegue responder a pergunta.

Versionar o arquivo no git e carregar latest no runtime, sem gravar o identificador no span, deixa o mesmo buraco. O histórico existe no repositório. A execução não aponta para ele.

Checagem +20 XP de primeiraO post viral foi em 12/08. O prompt mora numa tabela de config, editada pelo painel, sem histórico. Marketing quer repetir o resultado. O que falta?

Um modelo maior, mais fiel ao tom do post

Um identificador imutável daquele prompt, gravado no trace do post

Guardar o post gerado e usá-lo como few-shot

Por que acontece

• Prompt editável em produção. Um painel admin ou uma tabela de configuração permite mudar sem deploy, e sem histórico. A agilidade come o rastro.
• Mudanças pequenas parecem inofensivas. “Só ajustei uma palavra” não parece merecer uma versão. A palavra era a que prendia o tom do post viral.
• O trace não tem o campo. Ninguém pensou em registrar a versão do prompt junto com a chamada. O span tem modelo, tokens, latência. Não tem prompt_version.
• latest parece simples. O código pede sempre a última. No dia da reclamação, a última já é outra.
• Confundir arquivo versionado com execução versionada. O git tem o histórico. A execução, se não gravar o hash, aponta para o vazio.

Quanto custa ignorar

• Bons resultados não se repetem. O que funcionou não pode ser recuperado. Marketing espera uma semana por um clone que não chega.
• Maus resultados não se explicam. Reclamações e incidentes ficam sem causa. Na LGPD, “não sabemos qual instrução processou os dados” é uma resposta ruim.
• Sem rollback. Uma mudança ruim fica em produção até alguém reescrever o texto antigo de memória.
• Comparação impossível. Sem versão, nenhum eval compara “antes” e “depois” de verdade. Você compara o código de agora com a memória.

Tratamento

Refatoração	Escolha quando
Extrair Template Versionado	O prompt não tem um lugar com histórico. Ele vira um template com nome e versão imutável; publicar uma mudança cria uma versão nova. Destino: Registro de Templates.
Adicionar Trace	O prompt até tem versão, mas as execuções não a registram. Toda chamada guarda nome e versão do template no span. Destino: Trilha de Auditoria.

Duas peças, as duas obrigatórias:

1. Texto imutável. content.blog@12 não se edita. Publicar cria @13. Rollback aponta de volta para @12.
2. Span com a versão resolvida. Grave content.blog@12, nunca latest. Se o código pede latest na hora, resolva o número antes da chamada e persista esse número.

Git serve. Hash do commit no trace identifica o prompt se o arquivo inteiro está no repositório. Painel admin também serve, se cada “salvar” gera um id novo e o id vai para o span. O que não serve é sobrescrever a linha.

No span, grave pelo menos isto:

Campo	Exemplo
prompt_name	content.blog
prompt_version	12 (resolvido, não latest)
model	o id que de fato atendeu

Sem o trio, você reproduz a prosa e ainda assim não sabe com qual modelo ela rodou. Versão de prompt e versão de modelo andam juntas no rastro.

Checagem +20 XP de primeiraO registro tem content.blog@1 até @14. O código carrega sempre latest, e o span grava só o nome content.blog. Uma reclamação aponta um post de sexta. O que quebra?

A execução não registra a versão resolvida

Nada, @14 é o latest e o registro tem o histórico

Falta um eval no latest antes de cada post

O que você ganha

• Toda resposta aponta para o texto exato que a gerou.
• Rollback em um clique.
• Evals que comparam versões de verdade.
• Investigação de incidentes com evidência.

Quando ignorar

• Script pessoal, uso único. Se ninguém vai precisar reproduzir, o controle de versão do repositório basta.

É esse smell?

Checagem +20 XP de primeiraO prompt está no repositório, com histórico no git, e cada deploy registra o hash do commit. Os traces guardam o hash. É Prompt Sem Versão?

Não

Sim, falta um registro de templates

Sim, porque hash de commit não é número semântico

Checagem +20 XP de primeiraO prompt tem versões num registro, mas o código sempre carrega 'latest'. Os traces registram só o nome do template, sem a versão. Qual é o problema?

Nenhum, o registro tem histórico

O nome do template deveria incluir a data

A execução não registra a versão

Checagem +20 XP de primeiraUm painel permite que o time de produto edite o prompt sem deploy, e cada edição gera uma versão numerada que aparece no trace. É Prompt Sem Versão?

Sim, editar em produção é arriscado

Não

Sim, até o eval entrar no painel o smell permanece

Checagem +20 XP de primeiraO prompt está espalhado em quatro arquivos, todos no git, e o span grava o hash do commit. Qual smell se destaca?

Prompt Sem Versão, porque quatro arquivos não têm um id só

Os dois, na mesma medida

Prompt Espalhado