Engenharia de prompts como código: versionamento, testes e CI/CD para prompts de LLMs

A maior parte das equipes que executa LLMs em produção ainda administra prompts como strings soltas — inline no código da aplicação, espalhadas por arquivos .env ou editadas diretamente no dashboard de um fornecedor, sem diff, revisão ou suíte de testes. Isso funciona até deixar de funcionar: um “pequeno ajuste de texto” quebra silenciosamente o parsing de saída estruturada, uma atualização de modelo altera tom ou formato sem ninguém perceber, ou um agente de suporte encontra um jailbreak três semanas antes da engenharia.

Prompt Engineering as Code (PEaC) trata o prompt como artefato de software versionado, testável e revisável — sujeito à mesma disciplina de qualquer código que chega à produção: contratos de schema, suítes de regressão, code review e gates de CI/CD. Esta é a arquitetura do projeto Prompt Pocket; o restante deste post detalha o raciocínio, os modos de falha que ela evita e os detalhes de implementação que importam depois de um protótipo de brinquedo.

Por que prompts precisam de disciplina de engenharia de software

O que quebra quando prompts são tratados como strings, e não como artefatos?

Quatro modos de falha aparecem de modo recorrente em sistemas LLM de produção que ignoram essa disciplina:

Deriva comportamental silenciosa — um prompt editado em dashboard muda o comportamento downstream sem code review, diff visível ou verificação automatizada de que formato e qualidade permaneceram estáveis.
Quebra de schema sem stack trace — o modelo devolve prosa em vez de JSON, omite campo obrigatório ou alucina um valor de enum fora do conjunto permitido. Sem validação em runtime, isso falha silenciosamente downstream ou quebra profundamente na lógica de negócio, longe da causa real.
Regressões na troca de modelo — atualizar uma versão de modelo ou trocar de provedor muda hábitos de formatação, verbosidade ou fidelidade a instruções de modos que QA manual não detecta antes de um cliente reclamar.
Ausência de controle de blast radius — uma mudança ruim no prompt chega direto a 100% do tráfego porque não existe gate de staging, suíte de eval ou caminho de rollback separado de um deploy completo.

Prompt-as-code fecha essas lacunas com os mesmos guardrails usados para código de aplicação: controle de versão, contratos tipados, testes automatizados de regressão e rollout em estágios.

Prompt-as-Code vs. prompting ad hoc: comparação direta

Dimensão	Prompting ad hoc	Prompt-as-code (PEaC)
Armazenamento	Strings inline, UI de dashboard, `.env`	Arquivos versionados em git, revisados via PR
Rastreamento de mudança	Nenhum, ou mensagem informal no Slack	Diff git + incremento de versão semântica
Contrato de saída	Implícito, parseado com regex/esperança	Schema explícito (Zod/Pydantic/JSON Schema), validado em runtime
Detecção de regressão	Checagem manual pontual, se houver	Suíte de eval automatizada no CI contra dataset golden
Rollback	Redeploy da versão anterior do app	Apontar para versão anterior do prompt, sem deploy do app
Atualização de modelos	“Teste e veja”	Suíte de eval reexecutada contra novo modelo, comparada ao baseline
Entrada adversarial	Descoberta em produção	Testada contra conjunto adversarial/red-team antes do merge
Responsabilidade	Quem editou por último o dashboard	Code owners via `CODEOWNERS`, revisão de PR obrigatória

Princípio central 1: schemas estritos para saída estruturada

Por que não confiar diretamente em saída de linguagem natural em pipelines de produção?

Porque LLMs são geradores de texto não determinísticos, não chamadas de função tipadas — mesmo com temperatura baixa, o formato deriva (uma fence Markdown extra, uma frase antes do JSON, um campo renomeado pelo impulso “prestativo” do modelo). Todo pipeline que consome essa saída precisa de uma fronteira de validação, tal como você validaria a resposta de uma API externa que não controla.

O padrão é definir o contrato com uma biblioteca de schema (Zod em TypeScript, Pydantic em Python), pedir saída estruturada ao modelo (modo tool-calling/function-calling quando disponível, ou prompt de sistema em JSON mode como fallback) e fazer parse e validação antes de qualquer lógica de negócio:

import { z } from "zod"

export const CodeReviewOutputSchema = z.object({
  status: z.enum(["approved", "changes_requested"]),
  findings: z.array(
    z.object({
      severity: z.enum(["critical", "important", "minor"]),
      file: z.string(),
      description: z.string(),
    })
  ),
})

export type CodeReviewOutput = z.infer<typeof CodeReviewOutputSchema>

// Na fronteira da API — falhe de modo explícito e tipado, não silenciosamente no downstream
const result = CodeReviewOutputSchema.safeParse(rawModelOutput)
if (!result.success) {
  // Nunca deixe uma saída malformada do modelo chegar à lógica de negócio.
  // Registre o erro de validação, a saída bruta e a versão do prompt
  // que a produziu — essa tríade é sua superfície de depuração.
  throw new StructuredOutputValidationError(result.error, promptVersion)
}

Isso oferece três coisas que parsing com regex ou “peça com educação” não oferece:

Um único ponto de falha observável. Quando a forma da saída quebra, há um erro de validação tipado vinculado a uma versão específica do prompt — não um TypeError: undefined is not a function três camadas dentro do app.
Um contrato que pode ser testado sem chamar o modelo. Testes unitários verificam o comportamento do schema sobre fixtures de modo instantâneo e gratuito, separado dos testes de integração lentos, não determinísticos e caros que chamam o LLM.
Um caminho de migração quando o contrato muda. Alterações de schema se tornam diffs explícitos revisáveis em PR, não renegociações implícitas entre texto do prompt e código downstream que por acaso ainda funcionam.

Saída estruturada: modo tool-calling vs. prompt de sistema em JSON mode

Há duas formas de obter saída estruturada, com perfis distintos de confiabilidade:

Tool/function calling nativo (tool use do Claude, function calling da OpenAI) — o modelo é direcionado a um schema no nível da API. Tem maior aderência, funciona bem para schemas aninhados e enums estritos e se integra naturalmente a Zod quando você gera a definição de ferramenta a partir do mesmo schema usado para validar.
JSON mode por instrução no prompt de sistema (“responda apenas com JSON válido nesta forma”) — menos confiável, mais sujeito a vazamento de prosa ou colchetes malformados, mas necessário quando o workflow não cabe no formato de chamada de ferramenta (por exemplo, a “ferramenta” é a resposta final). Sempre combine-o a validação runtime e retry com feedback de erro, nunca a confiança cega.

Prefira tool-calling para qualquer coisa com schema estrito e baixa tolerância a falhas; reserve JSON mode para casos em que a semântica de tool-calling não se encaixa bem na tarefa.

Lidando com falhas de validação: estratégia de retry

Uma falha de validação não é necessariamente terminal. Uma escada pragmática de retry:

Faça novo prompt com o erro de validação anexado — forneça a mensagem Zod/Pydantic ao modelo como contexto (your previous response failed validation: findings[0].severity must be one of critical/important/minor, got 'high') e peça resposta corrigida. Isso resolve a maioria das falhas transitórias de formato porque o modelo consegue se autocorrigir com feedback específico.
Use fallback para um prompt de extração mais estrito — se o retry #1 falhar, reduza para um prompt estreito e de propósito único, cujo trabalho é reformatar a saída bruta anterior para o schema.
Devolva um erro tipado ao chamador — após N retries (2–3 é comum), pare de tentar silenciosamente. Propague um erro estruturado que o chamador consiga tratar de modo explícito, em vez de entrar em loop infinito e gastar tokens.

Jamais tente sem limite: limite as tentativas e registre cada falha com versão do prompt, versão do modelo e saída bruta para inclusão posterior na suíte de eval (a falha de hoje é o caso de regressão de amanhã).

Princípio central 2: versionamento semântico para prompts

Como versionar um prompt?

Trate cada prompt de sistema como um pacote: dê-lhe uma versão semântica (v1.2.0), guarde-o no git junto do código e exija que todo incremento de versão passe uma suíte de eval automatizada contra dataset de referência antes de ser elegível para tráfego de produção.

Aplique semver deliberadamente, não só como rótulo:

MAJOR (v2.0.0) — mudança que quebra o contrato de saída ou o comportamento fundamental. Consumidores downstream devem atualizar seu parsing/tratamento. Exemplo: mudar findings[].severity de enum com 3 valores para enum com 5.
MINOR (v1.3.0) — mudança de comportamento retrocompatível com o schema existente. Exemplo: adicionar campo opcional, melhorar clareza de instrução, acrescentar exemplo few-shot que desloca o tom.
PATCH (v1.2.1) — correção de redação, typo ou esclarecimento que não deveria mudar mensuravelmente a distribuição da saída. Exemplo: corrigir erro gramatical no prompt de sistema sem tocar nas instruções.

Prompt-as-config vs. prompt-as-code: qual modelo de armazenamento usar?

Há duas estratégias defensáveis, e a correta depende de com que frequência prompts mudam em relação aos deploys e de quem pode alterá-los:

Prompt-as-code — prompts ficam em arquivos .ts/.md/.txt no mesmo repositório da aplicação, versionados por commits git e implantados pelo pipeline normal de CI/CD. É melhor quando:

Mudanças de prompt devem passar pelo mesmo gate de revisão que código (padrão recomendado para qualquer coisa com efeitos colaterais, como o padrão da ferramenta contact do servidor MCP deste site).
Você quer que versão do prompt e versão do app avancem juntas, sem risco de divergência entre o que o código espera e o que o prompt produz.
Rollback = git revert, sem infraestrutura adicional.

Prompt-as-config — prompts ficam em store externo (banco, serviço de feature flags, plataforma dedicada de gerenciamento de prompts), buscados em runtime e implantáveis independentemente do código. É melhor quando:

Stakeholders não técnicos (conteúdo, suporte, growth) precisam iterar o texto sem deploy de código.
Você precisa de rollback instantâneo ou teste A/B entre versões sem redeploy.
Você aceita o trade-off de uma dependência runtime extra, a necessidade de ainda impor disciplina de revisão/versionamento fora do git e um histórico de mudança mais difícil de auditar se a plataforma não o registrar bem.

Na prática, o híbrido é comum: templates e schemas de prompts vivem como código (revisados, versionados, tipados), enquanto variáveis específicas inseridas no template (presets de tom, exemplos few-shot de um conjunto curado) podem ficar em config para iteração mais rápida — desde que o contrato de schema permaneça propriedade do código.

Versionamento de prompts em git: layout concreto de diretórios

prompts/
├── code-review/
│   ├── v1.0.0.ts       # versão inicial, arquivada
│   ├── v1.1.0.ts       # adicionou instruções de triagem de severidade
│   ├── v1.2.0.ts       # versão atual em produção
│   └── schema.ts       # CodeReviewOutputSchema — compartilhado entre versões
├── recruiter-evaluate/
│   ├── v1.0.0.ts
│   └── schema.ts
└── registry.ts          # mapeia { promptId, environment } -> versão ativa

Mantenha versões antigas na árvore em vez de apagá-las a cada incremento: é isso que torna comparação de regressão e rollback triviais. Um rollback é uma alteração de uma linha em registry.ts apontando de volta para v1.1.0, não arqueologia de git revert. Combine cada incremento com uma entrada de CHANGELOG explicando por que, não apenas o que; futuras sessões de debug precisam do raciocínio, não somente do diff.

Princípio central 3: construindo um harness de eval e dataset golden

O que é um dataset golden e por que toda suíte séria de eval de prompts precisa de um?

Um dataset golden é um conjunto curado e versionado de entradas representativas, pareadas com saídas esperadas exatas ou critérios de avaliação — o conjunto de referência contra o qual toda versão de prompt é avaliada antes de publicar. Ele desempenha o mesmo papel de fixtures/ nos testes tradicionais, adaptado à saída não determinística.

Um bom dataset golden mistura:

Casos de caminho feliz — entradas típicas e bem formadas que cobrem os principais usos do prompt.
Casos extremos — entradas vazias, muito longas, em idiomas inesperados e solicitações ambíguas.
Casos de regressão conhecidos — todo bug de produção causado por regressão de prompt é adicionado permanentemente assim que corrigido, para nunca reaparecer de modo silencioso. Este é o hábito de maior alavancagem na manutenção de evals.
Casos adversariais/red-team — tentativas de prompt injection, jailbreak, pedidos para vazar o prompt de sistema e solicitações fora de escopo que tentam descarrilar a persona do assistente.

Como estruturar uma suíte de eval de prompts?

Um harness mínimo, mas viável para produção, tem quatro estágios:

interface EvalCase {
  id: string
  input: Record<string, unknown>
  // Asserções de match exato quando a saída é suficientemente determinística
  // (forma do schema, pertencimento ao enum, presença de campos obrigatórios).
  assertions: (output: unknown) => { pass: boolean; reason?: string }[]
  // Opcional: para casos em que a correção é qualitativa, não de match exato.
  rubric?: string
}

async function runEvalSuite(
  promptVersion: string,
  model: string,
  cases: EvalCase[]
): Promise<EvalReport> {
  const results = await Promise.all(
    cases.map(async (c) => {
      const rawOutput = await callModel(promptVersion, model, c.input)
      const parsed = OutputSchema.safeParse(rawOutput)

      const schemaAssertion = {
        pass: parsed.success,
        reason: parsed.success ? undefined : parsed.error.message,
      }

      const customAssertions = parsed.success
        ? c.assertions(parsed.data)
        : []

      const judgeScore = c.rubric
        ? await runLlmAsJudge(c.rubric, c.input, rawOutput)
        : null

      return { caseId: c.id, schemaAssertion, customAssertions, judgeScore }
    })
  )

  return summarizeReport(promptVersion, model, results)
}

Validação de schema — a saída sequer obedece ao contrato? Só isso captura a maior parte das regressões catastróficas e é completamente determinístico.
Asserções determinísticas — verificações de string/campo que não precisam de judge: “status é o valor esperado?”, “findings não está vazio nesta entrada conhecida como problemática?”, “a resposta tem menos de N tokens?”.
Pontuação LLM-as-judge — para dimensões qualitativas (tom, utilidade, aderência à persona) que resistem a match exato, uma segunda chamada de modelo com rubrica explícita avalia a saída. As ressalvas críticas vêm abaixo.
Relatório agregado com limiar de aprovação/reprovação — a suíte produz um único sinal de gate: percentual de casos que passam a validação de schema, média de score do judge versus baseline da versão anterior e uma lista rígida de casos de regressão conhecida que falharam (estes devem bloquear merge incondicionalmente, não apenas baixar uma média).

LLM-as-judge: onde funciona e onde mente

LLM-as-judge — usar um segundo modelo, muitas vezes mais forte ou com prompt diferente, para pontuar a saída do prompt principal contra uma rubrica — é a resposta prática para avaliar qualidades abertas que não se verificam com regex ou igualdade: tom, utilidade, fidelidade a fonte e seguimento de instruções sob critérios subjetivos.

Ele tem modos de falha reais e bem documentados que precisam entrar no desenho:

Viés de autopreferência — um modelo judge tende a avaliar saídas da própria família de modelos mais favoravelmente. Ao comparar Claude a outro modelo, use judge que não seja da família de nenhum candidato ou controle esse fator na metodologia.
Viés de verbosidade — judges frequentemente avaliam respostas maiores como “melhores”, independentemente de qualidade. Restrinja a rubrica explicitamente (“não favoreça extensão; respostas concisas e corretas devem receber a mesma nota que respostas longas e corretas”).
Viés de posição em comparação pareada — ao pedir que um judge escolha entre saída A e B, a posição apresentada primeiro é favorecida desproporcionalmente. Mitigue executando a comparação duas vezes com posições trocadas e exigindo veredito consistente.
Ambiguidade da rubrica se acumula em silêncio — uma rubrica vaga (“esta é uma boa resposta?”) produz scores ruidosos e de baixa concordância. Rubricas devem ser tão explícitas e estruturadas quanto o schema de saída, enumerando critérios e pesos relativos.

Trate scores de LLM-as-judge como sinal para investigar, não como verdade fundamental — especialmente perto de um limiar de aprovação. Faça periodicamente spot-check de amostras contra julgamento humano para detectar deriva do judge.

Detectando regressões silenciosas ao atualizar versões de modelos

Atualizações de modelo são um dos momentos mais arriscados e menos testados no ciclo de vida de um prompt, pois o texto do prompt não muda — só muda o modelo que o interpreta. Um workflow prático:

Execute a suíte de eval completa contra a nova versão antes de direcionar tráfego de produção, usando exatamente a mesma versão de prompt e dataset golden do baseline atual.
Compare scores agregados, não apenas passa/falha — uma troca pode preservar a taxa de aprovação e alterar silenciosamente comprimento, verbosidade, taxa de recusa ou hábitos de formatação, como Markdown inesperado quebrando consumidor plaintext.
Dê atenção especial à taxa de aderência a saída estruturada — versões diferentes têm confiabilidade diferente em tool-calling nativo; uma atualização que parece boa em prosa pode regredir na conformidade de schema.
Execute o subconjunto adversarial/red-team separadamente — comportamento em limites de segurança/persona muda de forma imprevisível, e uma eval geral pode mascarar essa regressão se os casos adversariais forem minoria.
Faça canary da nova versão para pequena porcentagem de tráfego, com logging de saída, e compare a distribuição real à prevista pelas evals antes do corte completo.

A disciplina central: uma atualização de modelo é risco de regressão de prompt, não apenas mudança de infraestrutura — encaminhe-a pelo mesmo gate de eval de uma edição no prompt.

Princípio central 4: gates de CI/CD para prompts

Como conectar evals de prompts ao CI/CD?

Trate a suíte de eval como check obrigatório, exatamente como uma suíte unitária que bloqueia merge:

# .github/workflows/prompt-eval.yml
name: Prompt Eval Gate
on:
  pull_request:
    paths:
      - "prompts/**"

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Run eval suite against changed prompt versions
        run: npm run eval:prompts -- --diff-against=main
      - name: Fail if any known-regression case fails
        run: npm run eval:check-regressions
      - name: Fail if schema-conformance rate drops below threshold
        run: npm run eval:check-schema-rate -- --min=0.98
      - name: Post score diff as PR comment
        uses: actions/github-script@v7
        with:
          script: |
            // Publique diretamente no PR o delta de score agregado em relação à versão
            // atual do prompt na branch main, para que revisores vejam o impacto na qualidade, não só um diff de texto.

Propriedades-chave impostas pelo pipeline:

Mudanças de prompt disparam o mesmo gate de eval que mudanças de código — o filtro paths: mantém o CI rápido, mas o executa incondicionalmente quando prompts/** muda.
Casos de regressão conhecidos são bloqueio rígido, não parte de score médio — um único bug já corrigido reaparecendo não pode se esconder atrás de um agregado bom.
A taxa de conformidade de schema tem limiar explícito próprio, separado de scores qualitativos do judge — quebra estrutural e “tom um pouco pior” são severidades distintas e precisam de gates independentes.
Diffs de score aparecem ao revisor, não enterrados em log de build; é isso que torna a revisão de prompt substantivamente diferente de aprovar uma alteração silenciosa de texto.

Rollout em estágios para mudanças de prompt

Depois que uma versão passa no CI, trate seu rollout em produção como qualquer mudança de comportamento com casos extremos reais desconhecidos:

Shadow mode — execute a nova versão contra entradas reais de produção sem servir a saída, registrando resultados para comparação com a versão ativa.
Rollout percentual — sirva a nova versão a pequena porcentagem de tráfego (5–10%), monitorando taxa de falha de validação de schema, latência e custo de tokens em tempo real contra o baseline.
Corte completo com a versão anterior pinada e pronta — mantenha a entrada de registry anterior intacta para que rollback seja mudança de configuração, não redeploy.

Princípio central 5: separação entre system prompt e user prompt e defesa contra injection

Por que a fronteira system/user prompt importa para segurança?

O system prompt contém instruções e restrições que você controla; o user prompt — e tudo mais influenciado pela pessoa usuária, como documentos recuperados, saída de ferramentas e arquivos enviados — contém conteúdo que você não controla. Prompt injection explora o fato de que modelos processam ambos como texto no mesmo contexto, para tentar fazer instruções presentes em conteúdo controlado pela pessoa usuária prevalecerem sobre as regras de sistema.

Defesas práticas, em camadas e não isoladamente:

Delimitação explícita no system prompt — instrua o modelo a tratar conteúdo dentro de tags/delimitadores como dados, não instruções, e a ignorar texto que pareça instrução ali. Isso reduz, mas não elimina, injection.
Desenho de ferramentas com menor privilégio — se o modelo tem ferramentas, limite a capacidade de cada uma ao mínimo (somente leitura versus efeito colateral, como este projeto faz explicitamente: cinco ferramentas somente leitura e uma contact com limites rígidos de entrada). Uma instrução injetada é muito menos perigosa se as ferramentas disponíveis não conseguem causar dano mesmo quando usadas incorretamente.
Validação na saída, não apenas filtragem na entrada — schemas de saída estruturada também mitigam injection: mesmo se ela tiver sucesso parcial, a saída ainda precisa obedecer a schema estrito, limitando o blast radius ao que seus campos permitem.
Casos adversariais na suíte de eval são testes de regressão da resistência a injection — todo padrão de injection conhecido que tenha funcionado uma vez, até em testes, entra permanentemente no subconjunto adversarial do dataset golden, como um caso funcional de regressão.

Few-shot vs. zero-shot: quando o peso extra do prompt compensa?

Zero-shot (somente instruções, sem exemplos) é o padrão correto: custa menos tokens, é mais simples de versionar e comparar, e modelos modernos instruídos seguem instruções bem especificadas de modo confiável na maioria das tarefas bem delimitadas.

Use few-shot especificamente quando:

O formato de saída for incomum ou muito estruturado e instruções não o especificarem suficientemente — mostrar 2–3 exemplos da forma alvo elimina ambiguidade que um parágrafo de instruções deixa aberta.
A calibração de tom/estilo importar mais do que instruções conseguem capturar — “profissional, mas não rígido” é mais fácil de demonstrar que descrever.
O tratamento de casos extremos precisar ser fixado — exemplo que mostra exatamente como lidar com resultado vazio ou pedido ambíguo desambigua comportamento que instruções livres tendem a deixar vago.

O custo: exemplos few-shot aumentam o custo e a latência de todos os requests e, ponto frequentemente subestimado, os próprios exemplos precisam de controle de versão e cobertura de eval, pois um exemplo desatualizado ou sutilmente errado influencia toda saída seguinte. Trate o conjunto few-shot como parte do artefato de prompt versionado, não como acréscimo único que você esquece.

Princípio central 6: benchmark de latência, determinismo e custo

Como comparar modelos para uma decisão de prompt em produção?

Comparar modelos para um caso real precisa de mais que uma impressão sobre alguns prompts manuais: use o mesmo dataset golden e harness de eval de regressão, pontuado em três eixos independentes:

Taxa de sucesso na primeira tentativa — porcentagem de casos que passa validação de schema e asserções determinísticas na primeira chamada, sem retry. É ela que determina overhead de retry e latência efetiva, não apenas velocidade bruta.
Custo por saída bem-sucedida, não custo por token — modelo barato com menor taxa de sucesso inicial pode custar mais após o gasto em retries. Calcule (tokens médios por tentativa × tentativas médias até sucesso × preço por token) como métrica real.
Latência no percentil relevante para UX, não a média — chat usa p50/p90 de time-to-first-token; pipeline em lote usa p99 de conclusão. Escolha o percentil do requisito de quem usa.

Temperatura e determinismo: qual trade-off em um pipeline de saída estruturada?

Temperatura baixa (próxima de 0) aumenta consistência, especialmente quando a tarefa tem uma estrutura objetivamente correta (extração, classificação, veredito de revisão de código) ou quando os scores de eval precisam ser reproduzíveis entre execuções. Temperatura maior vale o custo quando a tarefa é verdadeiramente generativa (copy criativo, brainstorming, conversas variadas) ou quando diversidade é funcionalidade.

Mesmo em temperatura 0, não espere determinismo bit a bit: não determinismo de infraestrutura (batching, diferenças de hardware) reduz a variância, mas não garante texto idêntico. Desenhe asserções de eval para equivalência semântica e conformidade de schema, não igualdade textual, salvo quando a tarefa for estreita o suficiente para match exato.

Juntando tudo: workflow de referência

Mudança de prompt proposta em PR tocando prompts/<feature>/vX.Y.Z.ts, com CHANGELOG explicando o raciocínio.
CI executa a suíte de eval da versão contra o dataset golden: conformidade de schema, asserções determinísticas, LLM-as-judge e subconjunto adversarial.
Casos de regressão conhecidos e limiar de conformidade de schema bloqueiam o merge incondicionalmente; deltas qualitativos aparecem ao revisor como comentário de PR.
No merge, a versão nova é implantada, mas ainda não fica ativa — registry.ts continua apontando à anterior.
Shadow mode, depois rollout percentual, acompanhando em tempo real taxa de falha de schema e custo.
Corte completo, mantendo a versão anterior na árvore para rollback imediato.
Todo incidente de produção atribuído ao prompt adiciona a entrada disparadora ao dataset golden como caso permanente de regressão antes de a correção ser publicada.

Este é o mesmo ciclo de vida que uma base de código bem administrada aplica a uma alteração de código arriscada; a única novidade real é que os “testes” incluem um judge não determinístico e o “contrato” é imposto por validador de schema, não compilador. Todo o resto — versionamento, revisão, rollout em etapas e proteção de regressão — é disciplina de engenharia aplicada a um artefato que por acaso é linguagem natural.

FAQ técnico

Qual é a diferença entre versionamento de prompt e teste A/B de prompt?

Versionamento é gerenciamento controlado e auditável de mudança: toda versão é testada, revisada e reproduzível, com ponteiro claro da versão atual em produção. Teste A/B é uma estratégia de rollout sobre o versionamento: servir duas variantes já versionadas e aprovadas em eval para fatias distintas de tráfego e comparar métricas reais. Você precisa de versionamento mesmo sem A/B; A/B é opcional e se sobrepõe a ele.

Preciso de plataforma dedicada de gerenciamento de prompts ou posso usar apenas git?

Git com harness leve de eval cobre a maioria dos casos, em especial quando engenheiros mudam prompts e as alterações devem passar por code review. Use plataforma dedicada quando pessoas não técnicas precisam iterar sem deploy ou quando você precisa de infraestrutura A/B e analytics embutidos que não quer construir; saiba apenas que troca a trilha de auditoria e gate de revisão gratuitos do git por uma ferramenta que precisa ser configurada para replicá-los.

Qual tamanho um dataset golden deve ter antes de ser útil?

Ele é útil antes de ser exaustivo: 15–30 casos bem escolhidos, cobrindo caminhos felizes, casos extremos conhecidos e 2–3 entradas adversariais, capturam a maioria das regressões catastróficas. Faça-o crescer incremental e permanentemente — todo bug de produção vira caso — em vez de tentar desenhar um dataset “completo” no início, o que é impossível e menos valioso que publicar.

A pontuação LLM-as-judge pode substituir completamente revisão humana?

Não. Trate-a como mecanismo de escala para detectar regressões entre revisões humanas, não como substituta do julgamento humano em casos ambíguos ou de alto risco. Modelos judge trazem os mesmos modos de falha de qualquer LLM — viés, inconsistência perto de limiares e pontos cegos de correção sutil — e spot-checks humanos periódicos contra os scores são necessários para perceber deriva.

Como testar um prompt especificamente contra prompt injection?

Construa subconjunto adversarial no dataset golden com padrões conhecidos: instruções inseridas em conteúdo da pessoa usuária tentando sobrescrever o sistema, tentativas de exfiltrar literalmente o prompt de sistema, de invocar ferramentas fora do escopo e instruções codificadas/ofuscadas (como instruções divididas entre turnos ou escondidas em formatação). Avalie se a saída do modelo — validada pelo schema estrito — mostra qualquer sinal de conformidade com a instrução injetada, e não apenas se ele “recusou” em texto simples.

Qual a diferença prática entre prompt-as-code e prompt-as-config para um time pequeno?

Para um time pequeno em que os mesmos engenheiros escrevem prompts e entregam código, prompt-as-code quase sempre é a escolha mais simples e de menor overhead: nenhuma infraestrutura adicional, e o git já fornece revisão, versionamento e rollback. Prompt-as-config ganha sua complexidade quando uma pessoa não técnica precisa iterar texto independente de deploy ou quando é necessário rollback instantâneo sem deploy entre muitas variantes rodando ao mesmo tempo.

Como saber se um incremento de versão do prompt deve ser MAJOR ou MINOR?

Pergunte se a lógica de parsing/tratamento de um consumidor downstream existente quebraria sem modificação com a nova saída. Se sim — campo renomeado, valor de enum removido, estrutura reconfigurada — é MAJOR. Se o schema continua completamente retrocompatível (novos campos opcionais, instruções refinadas sem mudança de contrato), mas o comportamento muda, é MINOR. Correções apenas de redação, sem mudança de comportamento mensurável, são PATCH.

O que deve disparar a inclusão de um caso no dataset golden fora de um bug de produção?

Qualquer entrada que em teste manual produza saída inesperada, qualquer caso extremo identificado em code review do prompt, qualquer entrada adversarial surgida em revisão de segurança e qualquer caso em que atualização de modelo tenha produzido resultado diferente da versão anterior — mesmo se o novo resultado ainda for aceitável. Capturá-lo permite detectar deriva futura sobre aquela mesma entrada.