Gerenciamento e versionamento de prompts

Um prompt em produção é parte do comportamento do seu software. O gerenciamento de prompts é a disciplina de tratá-lo assim: saber qual versão está rodando, quem a mudou e por quê, se foi testada e como voltar atrás. A prática às vezes é chamada de PromptOps.

Os problemas que resolve

• Um prompt é editado em um painel e ninguém sabe dizer como era na semana passada.
• O mesmo prompt é copiado para quatro serviços e três deles estão desatualizados.
• Uma pequena mudança de redação dobra o custo de tokens e só é notada na fatura.
• Uma atualização de modelo muda o comportamento e não há um teste que mostre como.
• Uma chave de API é colada em um arquivo de prompt e commitada.

Guarde os prompts como arquivos

Mantenha cada prompt em seu próprio arquivo sob controle de versão, ao lado do código que o usa.

prompts/
  support-reply.md
  ticket-classify.md
  summarize-incident.md

Arquivos dão histórico, diffs, revisão, blame e reversão de graça. Um arquivo de texto simples ou Markdown com variáveis nomeadas é suficiente:

## Task
Classify the support ticket as billing, bug, or feature request.

## Output format
Return only the label.

## Input
<ticket>
{{ticket}}
</ticket>

Evite montar prompts por concatenação de strings espalhada entre funções. Se ninguém consegue ler o prompt inteiro em um só lugar, ninguém consegue revisá-lo.

Separe o template dos dados

Um template de prompt tem instruções fixas e variáveis nomeadas. Mantenha-os separados:

• As variáveis são explícitas. {{ticket}}, não um espaço de formatação sem nome.
• Cada variável é delimitada. Envolvida em tags, para que o texto inserido não possa ser lido como instruções.
• A renderização acontece em um só lugar. Uma função preenche os templates, escapa a entrada e registra qual versão do template foi usada.

Versione cada mudança

Use commits como versões. Cada mudança tem um autor, uma data e uma mensagem que explica por quê.

Registre o par que importa. O comportamento depende do prompt e do modelo. Registre a versão do prompt e o identificador do modelo em cada requisição, para que uma saída possa ser rastreada até o que a produziu.

Escreva um registro de mudanças para prompts importantes. Uma linha por mudança: o quê, por quê e o efeito nos resultados dos testes.

Marque as versões com tags. Quando um prompt é implantado, marque-o. Reverter passa a ser uma operação conhecida.

Revise mudanças em prompts como mudanças em código

Um diff de prompt merece uma revisão de verdade. Os revisores devem perguntar:

• A mudança contradiz uma instrução existente?
• Algo foi removido, como uma restrição ou o formato de saída?
• A contagem de tokens mudou, e isso é aceitável?
• Existe um teste para o comportamento que essa mudança pretende corrigir?

Verificações automáticas respondem a várias delas antes de uma pessoa olhar. O portão de testes de prompts reprova o build quando um arquivo de prompt cai abaixo de uma pontuação mínima de qualidade, excede um orçamento de tokens ou contém um achado crítico. A configuração fica no repositório:

{
  "include": ["prompts/**/*.md"],
  "model": "gpt-4.1",
  "minScore": 70,
  "maxTokens": 2000,
  "failOn": "critical"
}

Como as verificações são determinísticas e offline, não precisam de chave de API no CI e nunca produzem uma falha intermitente.

Teste antes de lançar

As verificações estáticas confirmam que o prompt é sólido. Um conjunto de testes de saída confirma que ele continua se comportando. Execute ambos quando um prompt mudar e reexecute os testes de saída quando a versão do modelo mudar. Veja os testes e a avaliação de prompts.

Implante gradualmente

Para prompts com tráfego real:

1. Sombra. Execute a nova versão ao lado da antiga e compare as saídas sem mostrá-las aos usuários.
2. Canário. Envie uma pequena parte do tráfego para a nova versão e observe as taxas de erro, a validade do formato e os sinais dos usuários.
3. Promova ou reverta. Decida pelos números.

Mantenha a versão anterior implantável até a nova se provar.

Monitore em produção

Acompanhe por versão de prompt:

• Tokens de entrada e saída, e custo.
• Latência.
• Parcela de respostas que falham na validação.
• Recusas e fallbacks.
• Feedback dos usuários, quando você o coleta.

Cuidado com o que você registra. Prompts e saídas podem conter dados pessoais e segredos. Registre metadados por padrão e oculte o conteúdo antes de armazená-lo. Veja a detecção de PII e segredos em prompts.

Mantenha segredos fora dos prompts

Arquivos de prompts são lidos, comparados, compartilhados e enviados a terceiros. Nunca guarde credenciais neles. Passe segredos às ferramentas pela sua aplicação, não pelo contexto do modelo. Um scanner no CI pega os acidentes; o scanner de segurança de prompts reprova qualquer credencial detectada.

Responsabilidade e reutilização

• Dê um responsável a cada prompt. Alguém decide as mudanças e responde às dúvidas.
• Compartilhe por uma biblioteca, não copiando. Uma única fonte, importada onde necessário.
• Documente o contrato. Que variáveis recebe, o que retorna e o que pressupõe.
• Aposente prompts antigos. Prompts sem uso ainda são copiados pela próxima pessoa que os encontra.

Pontos de partida selecionados e testados ajudam aqui. Os templates do PromptFlowEngine são mantidos com pontuação alta e sem avisos a cada build.

Ferramentas dedicadas ou arquivos simples

As plataformas de gerenciamento de prompts acrescentam um editor visual, acompanhamento de experimentos e acesso para quem não é engenheiro. Valem a pena quando muitas pessoas de fora da engenharia editam prompts. Para a maioria das equipes, arquivos no git mais verificações automáticas dão o essencial sem nada novo para operar. Qualquer que seja a escolha, os requisitos são os mesmos: uma única fonte de verdade, histórico, revisão, testes e reversão.

Uma lista de verificação inicial

• Todo prompt de produção é um arquivo sob controle de versão.
• As variáveis são nomeadas e delimitadas.
• A versão do prompt e o modelo são registrados em cada requisição.
• Uma verificação estática roda a cada pull request.
• Existe um conjunto de testes que roda quando o prompt ou o modelo muda.
• Os orçamentos de tokens estão definidos e são aplicados.
• Sem segredos em arquivos de prompts, verificado automaticamente.
• Existe uma forma documentada de reverter.