Exemplos Chumbados

Como reconhecer

A triagem de chamados de uma empresa de software usa exemplos para classificar. Eles vivem numa constante, no meio do código (anonimizado):

# classifier.py
FEW_SHOTS = [
    ("Não consigo acessar o painel", "acesso"),
    ("Cobrança em duplicidade no cartão", "cobranca"),
    ("O relatório de vendas está vazio", "bug"),
    # TODO: pedir ao time de ops os exemplos de integração
]

O time de operações percebeu que chamados sobre integração com ERP estão caindo em “bug” quando deveriam ir para “integracao”. Eles sabem exatamente quais exemplos ajudariam. Para mudar, precisam abrir um ticket para engenharia, esperar alguém pegar, revisar o PR e esperar o deploy da semana seguinte. O TODO está ali há quatro meses.

Enquanto o ticket anda, o modelo continua vendo só três classes. Um chamado de “o webhook do ERP não dispara a NF-e” vira bug de relatório, porque o exemplo mais próximo é o relatório vazio.

Sinais de Exemplos Chumbados:

• Exemplos de prompt ficam em constantes ou strings no código-fonte.
• Mudar um exemplo exige pull request, revisão e deploy.
• Quem entende do domínio (operações, atendimento) não consegue editar os exemplos.
• Não há histórico de por que cada exemplo entrou.
• Os exemplos do código e os casos do eval estão misturados ou são os mesmos.

flowchart LR
  O((("1. Time de operações"))):::human --> T["2. Ticket para engenharia"]:::tool
  T --> PR["3. PR e revisão"]:::tool
  PR --> D["4. Deploy semanal"]:::tool
  D --> P(["5. Exemplo novo no prompt"]):::llm

1. Quem conhece o problema não tem acesso aos exemplos.
2. A mudança vira um pedido para outro time.
3. Um engenheiro faz uma mudança de texto como se fosse de código.
4. A correção espera o ciclo de deploy.
5. Semanas depois, o exemplo entra.

O smell não é “exemplos no git”. É o ciclo: só engenharia mexe, só no deploy, sem dono nem motivo gravado.

Checagem +20 XP de primeiraOps tem 4 exemplos prontos de integração com ERP. Para entrar no classificador, o caminho é ticket, PR e deploy da quinta. Qual é o cheiro?

Prompt Sem Eval, porque ninguém mediu os 4 exemplos

Exemplos Chumbados: quem conhece o domínio não publica o exemplo

Acúmulo de Exemplos, porque quatro já são demais

Por que acontece

• Começou como protótipo. A constante no código era o jeito mais rápido de testar. O protótipo foi para produção com o TODO na linha 7.
• Prompt tratado como código. Por estar no repositório, passou a seguir o ciclo do código: PR, CI de aplicação, deploy semanal. Texto de domínio não precisa desse ciclo.
• Não havia outro lugar. Ninguém criou um armazenamento de exemplos com versão e permissão.
• Medo de ops quebrar produção. Sem eval na publicação, a engenharia vira o único gate. O gate certo é o eval, não o deploy.

Quanto custa ignorar

• Lentidão. Correções simples demoram semanas. No atendimento por WhatsApp, quatro meses de ERP classificado como bug é fila no time errado.
• Conhecimento perdido. Quem sabe quais exemplos ajudariam desiste de pedir.
• Engenharia ocupada com texto. Pessoas caras fazem mudanças que não são de engenharia.
• Risco. Sem eval separado, um exemplo novo pode piorar outra categoria sem ninguém ver.
• Contaminação. Se os mesmos 3 exemplos do código são o eval, o eval sempre passa e não vê o ERP.

Antes e depois do fluxo

	Chumbado	Dataset
Quem edita	Engenharia, via PR	Ops, com revisão
Quando entra	Próximo deploy	Depois do eval, minutos
Histórico	Blame do arquivo, se alguém comentou	Dono, motivo, data
Relação com o eval	Costuma ser a mesma lista	Listas separadas

Tratamento

Refatoração	Escolha quando
Mover Exemplos para um Dataset	Sempre que os exemplos precisam mudar com frequência ou por pessoas fora da engenharia. Eles vão para um conjunto versionado, editável com revisão, e entram no prompt na hora do pedido. Destinos: Seletor de Exemplos e Dataset de Ouro.

O destino tem três regras que o time esquece quando “só joga numa planilha”:

1. Versão imutável. Publicar cria erp-triage@14, não sobrescreve a linha 4.
2. Eval antes de valer. Os novos exemplos de integração não podem derrubar a acurácia de “cobranca”. O conjunto de eval é outro conjunto.
3. Quem conhece o domínio edita. Engenharia constrói o cano (schema, permissão, seletor). Ops escolhe os exemplos.

Um YAML no repositório, com ops abrindo PR só naquele arquivo e um job aplicando depois do eval, já é um dataset. Uma constante em classifier.py não é.

Checagem +20 XP de primeiraVocês moveram os exemplos para uma planilha que ops edita à vontade. O classificador lê a planilha a cada pedido. Não há revisão nem eval. O que você acabou de trocar?

Nada de grave: o smell era a lentidão, e ela acabou

Um ciclo lento por um ciclo sem versão e sem medida

Exemplos Chumbados por Prompt Sem Versão, só

O que você ganha

• Quem conhece o domínio edita os exemplos, com revisão e histórico.
• Mudanças entram em minutos, depois de passar no eval, sem deploy de código.
• Cada exemplo tem dono, motivo e data.
• Exemplos e casos de eval ficam separados.

Quando ignorar

• Exemplos estáveis e técnicos. Exemplos de formato que mudam uma vez por ano podem ficar no código.
• Time pequeno, mesma pessoa. Se quem entende do domínio é quem faz o deploy, o custo é menor. O ganho de versionar e separar do eval continua.

É esse smell?

Checagem +20 XP de primeiraOs exemplos ficam num arquivo YAML no repositório. O time de operações tem acesso para editar via pull request, e um job aplica as mudanças sem deploy da aplicação, depois de rodar o eval. É Exemplos Chumbados?

Sim, estão no repositório

Não

Sim, porque ops não deveria tocar em git

Checagem +20 XP de primeiraOs exemplos estão numa planilha que o time de operações edita livremente, e o sistema lê a planilha a cada pedido, sem revisão nem eval. Qual é o risco?

Nenhum, é editável

Mudança sem versão e sem eval

Só se a planilha sair da empresa, por LGPD

Checagem +20 XP de primeiraO prompt tem 35 exemplos no código e ninguém sabe por que cada um está lá. Qual smell se destaca?

Exemplos Chumbados

Acúmulo de Exemplos

Prompt Inchado, e só isso

Checagem +20 XP de primeiraOs únicos exemplos do classificador são três strings de formato JSON, no código, e não mudam há um ano. Ops nunca pediu para editá-los. É Exemplos Chumbados?

Sim, qualquer exemplo no código é este smell

Não, e você pode ignorar com tranquilidade absoluta

Não é o caso urgente; o ganho de versionar é pequeno enquanto ninguém precisa editar