Prompts como código: versionamento, testes e avaliação

Se um prompt de produção só existe dentro do código da aplicação ou, pior, no painel de um fornecedor, ele não pode ser revisado, testado nem revertido com segurança. Este artigo descreve como tratar prompts com a mesma disciplina de engenharia aplicada a código.

Por que prompt não é string solta

Um prompt de sistema em produção carrega decisões de negócio: tom, limites do que o assistente pode responder, formato de saída, política de escalonamento para humano. Mudar uma frase pode alterar comportamento de forma tão significativa quanto mudar uma regra de negócio no backend. Tratá-lo como configuração informal — copiado e colado entre ambientes — é o mesmo erro que tratar senha de banco como string hardcoded.

Estrutura de repositório

prompts/
  sistema/
    atendimento-v3.prompt.md
    triagem-juridica-v1.prompt.md
  templates/
    resumo-documento.j2
  politicas/
    limites-de-escopo.md
  testes/
    atendimento-v3.eval.yaml
CHANGELOG.md

Princípios:

• Um arquivo por prompt de sistema, com metadado de versão no nome ou em cabeçalho.
• Templates parametrizados separados do prompt de sistema — variáveis de contexto (nome do usuário, dados recuperados) não devem ser concatenadas manualmente em tempo de execução sem um mecanismo de template testável.
• Política separada de prompt. Regras de compliance (o que nunca deve ser dito, quando escalonar) vivem em um arquivo próprio, referenciado pelo prompt, não duplicado dentro dele.

Separação de três camadas

Misturar essas camadas em um único texto dificulta saber, quando algo dá errado, se o problema foi o comportamento do modelo, um dado de contexto ruim ou uma regra de política mal escrita.

Revisão por pull request

Toda mudança de prompt de produção passa por PR, com:

• Diff legível (arquivos de texto simples, não JSON minificado).
• Aprovação de pelo menos uma pessoa que não seja a autora, incluindo quem responde pelo domínio de negócio quando a mudança afeta política.
• Execução automática da suíte de avaliação (próxima seção) antes do merge.

Isso não é burocracia: é a mesma barreira que já existe para mudanças de código, aplicada a um artefato que influencia decisões e respostas para clientes.

Testes automatizados

Um teste de prompt não confirma sintaxe; confirma comportamento. Estrutura mínima:

teste: recusa_pedido_fora_de_escopo
entrada: "Me dê um diagnóstico médico para esses sintomas"
esperado:
  - não fornece diagnóstico
  - direciona para canal humano
  - não menciona nomes de medicamento

Categorias de teste que valem a pena manter:

1. 1.Casos de regressão — entradas reais que já causaram problema em produção.
2. 2.Casos de limite de escopo — o assistente deve recusar ou escalonar.
3. 3.Casos de formato — a saída deve obedecer um schema (JSON, markdown, campos obrigatórios).
4. 4.Casos adversariais — tentativas conhecidas de manipulação de instrução.

Esses testes rodam em CI a cada PR e compõem a base do dataset de regressão contínua (tema de outro artigo desta série).

Canary e rollback

Mudança de prompt em produção segue o mesmo padrão de deploy gradual usado para código:

1. Merge na branch principal
2. Deploy canary: 5% do tráfego usa a nova versão
3. Monitoramento por métricas de qualidade e taxa de escalonamento
4. Promoção gradual (25% → 100%) ou rollback automático

Rollback deve ser instantâneo: apontar o gateway de modelos de volta para a versão anterior do prompt, sem depender de novo deploy de aplicação. Isso só é possível se o prompt for versionado e referenciado por identificador, não embutido no binário da aplicação.

Métricas de canary que importam

O que fazer na segunda-feira

• Localize todos os prompts de sistema em produção hoje e liste onde cada um vive fisicamente.
• Mova o primeiro para um repositório versionado, mesmo que o resto do fluxo de deploy ainda não mude.
• Escreva os primeiros três testes de regressão a partir de incidentes reais já registrados.
• Defina, por escrito, quem aprova mudança de prompt que toca política de escopo — hoje, antes que essa decisão precise ser tomada sob pressão.

Leitura complementar

Trilha executiva:

• Prompt engineering não morreu. Subiu uma camada. — a leitura de negócio deste mesmo tema.