Codex Technomanticus

03 - Prompt versioning — semver para prompts

Leitura de 11 min

03 - Prompt versioning — semver para prompts

TL;DR

05 cobre como versionar (registry, label, semver, tying ao trace). Esta nota cobre quando bumpar e o que cada bump dispara no Improvement Loop: patch passa sem A/B (deploy direto); minor passa por A/B offline + canary curto; major dispara golden set novo + champion-challenger formal + plano de migração de consumer. Versão do prompt vira gatilho no pipeline — bumpou minor, automação roda A/B; bumpou major, automação cria branch de migração. Mapeamento versão → ação é a parte que torna semver útil pro loop em vez de só ser etiqueta bonita.

Ponte com Observability/05

05 - Versionamento de prompts cobre:

  • A regra de semver pra prompt (major/minor/patch e a heurística “se eval antigo ainda vale como baseline, é minor”)
  • Labels dev / staging / production no registry
  • Tying versão ao span do trace
  • Tools (Langfuse Prompts, PromptLayer, Braintrust)
  • Rollback strategy
  • Anti-padrões de versionamento

Esta nota não duplica isso. Aqui o foco é o que cada bump dispara no loop: o gatilho que conecta versionamento e os outros artefatos da melhoria (A/B, eval, champion-challenger, CI).

Recap rápido — o mapa semver pra prompt

BumpMudançaEval antigo ainda vale?
Patch (v1.2.4 → v1.2.5)Typo, wording sem comportamentoSim, integralmente
Minor (v1.2 → v1.3)Qualidade, few-shot, reordenaçãoSim, como baseline
Major (v1 → v2)Schema de output, contrato, tool removidaNão — precisa novo dataset

Detalhes completos em 05 - Versionamento de prompts.

O que cada bump dispara

O ponto desta nota: o bump não é só metadata. Ele é gatilho que define o pipeline de promoção.

Patch — fast-track

EtapaO que acontece
Eval offlineSmoke test (5-10 itens críticos), confirma que não quebrou
A/BNão roda — mudança não comportamental
CanaryNão roda — risco residual baixo
PromoçãoDireto pra production após smoke OK
Rollback planLabel de volta pra versão anterior

Patch existe pra não atrapalhar o time. Erro de wording corrigido às 23h não pode esperar 7 dias de canary. Trade-off aceitável: risco pequeno por velocidade.

Minor — A/B obrigatório

EtapaO que acontece
Eval offlineFull golden set, comparado contra champion atual
Gate offlineMétrica primária ≥ champion (com significância); secundárias dentro da tolerância
A/B onlineCanary 5-10% por período suficiente pro sample size declarado
Gate onlineBayesian P(B > A) > 0.95 OR frequentista p < 0.05 na métrica primária; guardrails verdes
PromoçãoLabel production move pro novo minor
Rollback planLabel de volta pro minor anterior; cache 60s

Minor é o caso médio do loop: bumpou prompt pra melhorar uma categoria, automação roda eval offline → se passa, dispara canary → se passa, promove.

Major — champion-challenger formal

EtapaO que acontece
Eval offlineGolden set novo (esquema antigo não vale como baseline pra schema novo); rubrica revisitada
Consumer migrationSchema mudou — consumers precisam atualizar; coordena release com downstream
Shadow runTreatment roda em paralelo sem servir ao usuário, pra coletar amostras com o schema novo
A/B onlineCanary com traffic split menor (1-5%) e período maior
Gate onlineMétricas primárias + guardrails secundários + zero regressão de consumer downstream
PromoçãoCoordenada com release notes pro consumer; possivelmente feature flag por cliente
Rollback planMais complexo — consumer pode já ter migrado pro schema novo; rollback precisa cobrir esse cenário

Major é caro. Por isso bumpa pouco: se uma mudança pode ser feita preservando schema, prefere-se minor.

Tabela de gatilhos — versão → automação

Push de prompt change → registry detecta bump
                                ↓
                         qual tipo de bump?
                ┌───────────────┼────────────────┐
                ▼               ▼                ▼
              PATCH           MINOR            MAJOR
                │              │                │
        smoke test          full eval       new dataset
        (5-10 itens)        (200+ itens)    + dataset versionado
                │              │                │
        passou? promove     passou?         shadow run
        direto                ↓             (sem servir user)
                              canary 5-10%      ↓
                              ↓                 canary 1-5%
                              passou?           ↓
                              promove           gate (incl. consumer)
                                                ↓
                                                promoção coordenada
                                                + release notes

Esta automação é o que diferencia “prompt versionado” de “prompt versionado e usado pelo loop”. Registry só, sem gatilho, vira só changelog.

Registry patterns — onde mora cada versão

PatternOnde moraQuando faz sentido
Prompt em Git, tag = versãoSource code repo, tag prompt/research-system@v3.1.0Time pequeno, prompt poucos, review nativo via PR
Prompt em registry SaaS (Langfuse, Braintrust, PromptLayer)Banco do vendor, labels gerenciados via UI/APITime médio, prompts editados por produto/PM
Prompt em arquivo YAML/JSON versionadoRepo dedicado de prompts (separado do source), CI publica no registryTime com muitos prompts, governança forte
HíbridoSource canônico em Git, mas registry SaaS é cache pra runtimeQuer best of both — review em Git, hot-reload em runtime

Não há vencedor universal. A escolha depende de:

  • Quem edita prompt? Só dev → Git basta. Produto/PM também → registry com UI.
  • Frequência de mudança? Baixa → Git. Alta → registry.
  • Volume de prompts? Poucos → Git. Muitos → registry com tagging.
  • Governança? Compliance pesado → registry com audit log nativo.

Tying versão a git tag — fazer ou não fazer

Opção A: prompt versionado só no registry, sem espelhar em Git tag.

  • Pro: edição rápida (não precisa abrir PR pra typo)
  • Pro: produto/PM edita sem aprovação de dev
  • Contra: source of truth bifurca (Git vs registry)
  • Contra: rollback exige acesso ao registry

Opção B: prompt versionado em Git, registry é mirror publicado por CI.

  • Pro: source of truth único (Git)
  • Pro: review padrão (PR + diff)
  • Contra: edição requer fluxo de dev
  • Contra: cache do registry pode ficar atrás se CI falhar

Opção C: prompt em Git e versão do prompt nasce de tag Git semver (prompt/research-system@v3.1.0).

  • Pro: rastreio integrado com release do produto
  • Contra: cada mudança de wording é tag nova — pode poluir histórico do repo

Pattern recomendado em 2026 pra time típico: B com cache curto — Git canônico, CI publica no registry SaaS, registry tem cache de 60s no client. Best of both: review forte, runtime ágil.

Quando bumpar — heurísticas práticas

Patch — bumpa quando

  • Corrigiu typo ou ortografia
  • Removeu espaço duplicado, formatação cosmética
  • Reformulou em paralelo sem mudar sentido (“favor” → “por favor”)
  • Atualizou referência externa que não muda comportamento (“ver docs em URL1” → “URL2”)

Minor — bumpa quando

  • Adicionou few-shot
  • Reordenou seções do system prompt
  • Ajustou tom (mais formal, mais conciso)
  • Adicionou guardrail soft (request adicional no system, sem mudar schema de output)
  • Trocou exemplo few-shot
  • Ajustou instrução pra reduzir uma classe específica de erro

Major — bumpa quando

  • Mudou schema do output (adicionou ou removeu campo)
  • Mudou formato (markdown → JSON; texto → estruturado)
  • Removeu uma tool do tools array
  • Adicionou tool nova obrigatória
  • Mudou contrato com consumer (e.g., consumer agora precisa parsear novo campo)

A regra heurística do 05 - Versionamento de prompts vale: se o golden set antigo ainda mede a versão nova de forma justa, é minor; se precisa de golden set novo, é major.

Automação do gatilho — CI snippet

Exemplo em GitHub Actions: detecta o tipo de bump no PR e dispara o pipeline correspondente.

# .github/workflows/prompt-ci.yml
name: Prompt CI
 
on:
  pull_request:
    paths:
      - "prompts/**"
 
jobs:
  detect-bump:
    runs-on: ubuntu-latest
    outputs:
      bump_type: ${{ steps.detect.outputs.bump_type }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Detect bump type
        id: detect
        run: |
          python scripts/detect_prompt_bump.py \
            --base ${{ github.base_ref }} \
            --head HEAD \
            >> $GITHUB_OUTPUT
 
  smoke-test:
    needs: detect-bump
    if: needs.detect-bump.outputs.bump_type == 'patch'
    uses: ./.github/workflows/smoke-test.yml
 
  full-eval:
    needs: detect-bump
    if: needs.detect-bump.outputs.bump_type == 'minor'
    uses: ./.github/workflows/full-eval.yml
 
  major-pipeline:
    needs: detect-bump
    if: needs.detect-bump.outputs.bump_type == 'major'
    uses: ./.github/workflows/major-migration.yml

O script detect_prompt_bump.py compara o MAJOR.MINOR.PATCH do frontmatter do arquivo de prompt entre base_ref e HEAD e emite patch, minor ou major. A pipeline certa roda automaticamente — o autor do PR não decide, o bump decide.

Anti-padrões específicos do gatilho

  • Patch que muda comportamento — bumpou como patch, pulou A/B; regressão silenciosa
  • Minor sem A/B — “vai dar certo, eu testei manualmente”; perde o ciclo de validação
  • Major sem novo golden set — testou contra dataset antigo que não cobre o schema novo; baseline inválido
  • Bump sem changelog — versionou, mas ninguém sabe por que mudou
  • Sem versionamento de dataset — prompt em v3.1, eval ainda contra dataset de quando prompt era v2.x; comparação ruim
  • Skipping de promoção (dev → production) — pulou staging porque “apertou prazo”; sem rede

Armadilhas comuns

Bumpar como patch quando o comportamento mudou — e pular o A/B que deveria ter rodado

O instinto é: “é só um ajuste de wording, não muda nada”. Mas “adicionei ‘seja conciso’ no system prompt” pode reduzir respostas em 40% e quebrar consumers que esperam formato longo. A heurística correta: se você não tem certeza que o eval antigo ainda captura o comportamento da versão nova — é minor, não patch. Patch deve ser indiferente ao eval: se a pergunta “isso vai alterar algum score no golden set?” não tem resposta óbvia de “não”, não é patch. O custo de rodar o eval uma vez é pequeno; o custo de uma regressão silenciosa em prod pode ser enorme.

Bumpou major sem coordenar a migração do consumer — e quebrou downstream silenciosamente

Major de prompt que muda schema de saída é o equivalente de uma breaking change em API pública. Consumer que lê response.answer quebra quando o campo muda pra response.output. Diferente de código, a quebra pode ser silenciosa: o consumer pode receber um campo None, parsear errado, e retornar dado ruim sem exception. O padrão correto: (a) deprecation period com os dois formatos suportados simultaneamente (se possível); (b) notificação explícita aos consumers antes de promover o major pra production; (c) shadow run com o schema novo antes de qualquer usuário ver. Major sem plano de migração de consumer é um incident esperando acontecer.

Versionamento sem changelog — ninguém sabe por que o prompt mudou

Bumpar versão sem registrar hipótese, contexto e resultado esperado transforma o histórico em sequência de números sem significado. “v1.3.0 → v1.4.0” não diz nada. “v1.3.0 → v1.4.0: adicionou few-shot pra casos em PT-EU onde summarization estava errando tema; esperado +8% em eval PT-EU” é o registro que o próximo dev vai usar quando a regressão aparecer. O lugar certo pra esse contexto é o commit message do PR de bump OU um CHANGELOG.md por prompt. Sem isso, o loop não acumula conhecimento — cada ciclo começa do zero.

Como explicar em inglês

Interview quote: “We treat prompts as versioned artifacts with semantic versioning adapted for LLM behavior. Patch is a non-behavioral change that goes straight to production after a smoke test. Minor is a behavioral improvement — adding few-shots, reordering instructions — that triggers an offline eval against the golden set and then a canary in production. Major is a schema-breaking change that requires a new golden set, a consumer migration plan, a shadow run, and a formal champion-challenger gate. The bump type becomes an automation trigger — the CI pipeline branches based on what kind of change it detects.”

PortuguêsInglês
Versionamento semântico de promptPrompt semantic versioning
Bump de versãoVersion bump
Mudança sem comportamento (patch)Non-behavioral change (patch)
Mudança comportamental (minor)Behavioral change (minor)
Mudança de schema (major)Schema-breaking change (major)
Migração de consumerConsumer migration
Gatilho de automaçãoAutomation trigger
Changelog de promptPrompt changelog
Registry de promptsPrompt registry
Golden set novo por majorNew golden set for major bump

O que vem a seguir

Com o versioning e seus gatilhos claros, a nota 04 entra no mecanismo que executa o gate final após A/B: champion-challenger em produção — como promover o challener automaticamente quando os critérios passam, como configurar o rollback automático nas primeiras horas após ship, e como decidir entre rollback completo e hotfix quando os sinais são mistos.

Fontes

Veja também

Visão de gráfico

Backlinks