Versionamento de prompts: rastreie, compare e reverta
Um bom prompt raramente nasce pronto. Você ajusta uma palavra, adiciona uma restrição, troca um exemplo e, três edições depois, a resposta está pior do que no começo, sem um caminho claro de volta. O versionamento de prompts salva um instantâneo a cada mudança relevante, para você comparar o que tinha com o que tem agora, restaurar a versão que realmente funcionava e enxergar qual edição fez diferença em vez de ficar adivinhando.
Você mexeu num prompt que estava funcionando, a qualidade caiu e precisa voltar exatamente ao texto que tinha na semana passada.
Duas pessoas editam o mesmo prompt compartilhado e você precisa de um histórico que mostre quem mudou o quê, quando e por quê.
Você está testando duas redações de um prompt de sistema e quer manter as duas versões lado a lado em vez de sobrescrever uma.
Uma atualização de modelo (digamos, do Claude 3.5 para uma versão mais nova) mudou o comportamento do seu prompt e você quer criar uma versão específica para aquele modelo sem perder a original.
Você está iterando rápido e quer marcar uma versão sabidamente boa antes de começar a experimentar de novo.
Erros a evitar
Sobrescrever a versão que funcionava. No instante em que você cola o texto novo por cima do antigo, a redação que realmente funcionava desaparece. Salve um instantâneo antes de cada edição relevante, não depois de se arrepender.
Versionar o texto do prompt, mas não o contexto ao redor. O modelo, a temperatura e as {variables} que você preencheu fazem parte do resultado, então registre tudo isso em cada versão, senão o instantâneo não pode ser reproduzido.
Escrever notas vagas como 'melhorei o prompt'. Seis versões depois, você não consegue dizer qual mudança consertou a saída em JSON. Anote o que mudou e por quê, não apenas que algo mudou.
Tratar cada tecla digitada como uma nova versão. O histórico vira ruído. Crie uma versão em checkpoints de verdade (uma redação que você testou, uma correção que entrou em produção), não a cada vírgula que você move.
Prompts para copiar
01
Escrever uma entrada de changelog da versão
Você é um engenheiro de prompts que mantém uma biblioteca de prompts versionada. Compare a versão anterior e a nova versão do meu prompt abaixo e escreva uma entrada de changelog para a nova versão. ANTERIOR: {old_prompt}. NOVA: {new_prompt}. Formate a entrada assim: um rótulo de versão usando versionamento semântico considerando que a última versão foi {last_version}, um resumo de uma linha, uma lista com marcadores do que mudou e uma observação sobre se a mudança quebra o uso para quem reaproveita este prompt. Mantenha em até 120 palavras e estritamente factual. Não elogie a mudança.
02
Explicar como duas versões se comportam de forma diferente
Você é um revisor de QA de prompts. Aqui estão duas versões do mesmo prompt. VERSÃO A: {version_a}. VERSÃO B: {version_b}. Suponha que ambas rodem com esta entrada: {test_input}. Sem executar nada, preveja como a saída do modelo diferiria entre A e B, com foco em formato, tom, nível de detalhe e qualquer restrição que uma imponha e a outra deixe de lado. Apresente as diferenças em uma tabela com as colunas Aspecto, Versão A, Versão B. Termine com uma frase dizendo qual versão é mais segura para colocar em produção em {use_case} e por quê.
03
Recomendar o incremento do número de versão
Você mantém prompts versionados usando versionamento semântico (MAIOR.MENOR.CORREÇÃO). A versão atual é {current_version}. Aqui está a mudança que fiz: {change_description}. Decida se isso é um incremento MAIOR, MENOR ou de CORREÇÃO usando estas regras: MAIOR significa que o formato ou o comportamento da saída muda de um jeito que quebra os usuários existentes, MENOR significa um novo recurso adicionado mantendo a compatibilidade, CORREÇÃO significa um ajuste de redação ou clareza sem mudança de comportamento. Responda apenas com o novo número de versão, o tipo de incremento e uma justificativa de uma frase.
04
Revisar uma mudança no prompt antes de salvar
Você é um revisor cuidadoso aprovando mudanças em um prompt compartilhado. Revise a edição abaixo antes de eu salvá-la como uma nova versão. VERSÃO ATUAL: {current_prompt}. EDIÇÃO PROPOSTA: {new_prompt}. OBJETIVO da edição: {goal}. Verifique se há instruções que agora se contradizem, restrições removidas por acidente, {placeholders} que não fazem mais sentido e desvio de escopo além do objetivo declarado. Devolva um veredito de APROVAR ou PEDIR AJUSTES, seguido de uma lista curta com marcadores dos problemas ordenados por gravidade. Se PEDIR AJUSTES, proponha a menor correção que resolve cada problema.
05
Criar testes de regressão para uma versão do prompt
Você está montando testes de regressão para que versões futuras de um prompt não quebrem em silêncio. Aqui está o prompt: {prompt}. A função dele é: {intended_behavior}. Produza 6 casos de teste que qualquer versão futura ainda precise passar. Para cada um, dê um nome curto, a entrada a ser fornecida e uma condição de aprovação descrevendo o que a saída deve conter ou nunca pode conter. Cubra o caso normal, um caso limite com {variables} faltando e um caso pensado para fazer o prompt quebrar o formato de saída. Retorne os casos em uma lista numerada.
Como guardar no PromptAtlas
Crie uma pasta para cada trabalho ou canal.
Adicione tags claras para pesquisar depois.
Transforme detalhes variáveis em campos.
Salve versões melhores sem apagar tentativas úteis.
Exporte a biblioteca quando precisar de backup.
Perguntas frequentes
O que é versionamento de prompts?
Versionamento de prompts é manter um histórico salvo de um prompt conforme ele muda ao longo do tempo, de modo que cada edição relevante vira um instantâneo que você pode ver, comparar e restaurar. É aplicar a ideia de controle de versão de código à redação dos seus prompts.
Qual a diferença entre versionar prompts e só salvar cópias?
Salvar cópias te dá arquivos soltos; o versionamento te dá uma linha do tempo. Uma ferramenta de versionamento liga os instantâneos a um único prompt, mostra a diferença entre eles, registra por que cada um mudou e permite reverter em um clique, em vez de caçar no meio de 'prompt-final-v3-agora-vai.txt'.
Devo usar versionamento semântico (v1.2.0) para prompts?
Pode usar, e ajuda quando outras pessoas dependem do prompt. Uma regra simples: aumente o número maior para uma mudança de comportamento que quebra o que existia, o número intermediário quando você adiciona um recurso e o número de correção para ajustes de redação. Para prompts pessoais, data, hora e rótulos curtos costumam bastar.
O que registrar além do texto do prompt?
Registre o modelo e as configurações para os quais ele foi escrito, uma nota curta sobre o que mudou e por quê e, de preferência, um exemplo de entrada com a saída que você obteve. É esse contexto que permite entender por que uma versão antiga se comportava daquele jeito quando você voltar a ela meses depois.
{A}
Crie sua biblioteca de prompts
Salve os prompts que funcionam, adicione variáveis, mantenha versões e encontre tudo em segundos.