Prompt engineering verificável: pare de pedir mágica e comece a exigir provas

prompt engineering verificável parece nome de palestra cara, mas é uma necessidade bem terrestre: impedir que uma automação bonita no papel vire uma máquina de produzir retrabalho. A diferença entre “automatizei” e “agora eu confio” está no método. E método, infelizmente, não cabe em print de dashboard.

O tema de hoje nasce da categoria Mente Binária e de um problema real: transformar prompts em contratos testáveis, com critérios de aceite e evidências. A maioria das pessoas começa pela ferramenta. Eu prefiro começar pela falha. Ferramenta muda, API cai, credencial expira, planilha ganha uma coluna chamada “final_final_2”. A falha é mais honesta.

O problema que ninguém coloca no briefing

Quando uma automação entra em produção, ela ganha uma vida social. Passa a conversar com sistemas que atrasam, humanos que esquecem campos, APIs que respondem “200 OK” enquanto entregam um objeto vazio, e integrações que juram estabilidade como quem promete dieta na segunda-feira. O erro comum é tratar tudo isso como exceção rara. Não é. É o ambiente normal.

Por isso, a primeira pergunta não deveria ser “qual ferramenta vamos usar?”. Deveria ser: “como saberemos que isto funcionou, como saberemos que falhou e o que acontece quando a resposta for ambígua?”. Essa pergunta separa uma automação útil de uma roleta com webhook.

O princípio: automação sem evidência é superstição

Automação boa deixa rastros. Ela registra entrada, decisão, saída e motivo. Não para enfeitar log, mas para permitir auditoria quando alguém pergunta, com aquela calma ameaçadora: “por que esse cliente recebeu isso?”. Se a resposta depende de abrir cinco abas, lembrar uma regra não documentada e rezar para o histórico ainda existir, você não tem automação. Você tem folclore operacional.

O primeiro desenho deve definir evidências mínimas. Um identificador de execução. Um resumo da entrada. O resultado esperado. O resultado real. O artefato produzido. O ponto de decisão humana, quando existir. Sim, dá trabalho. Menos trabalho do que explicar para o financeiro por que o robô duplicou 312 cobranças.

Escolha um escopo pequeno, mas inteiro

O erro sedutor é automatizar metade do processo e chamar isso de MVP. Metade do processo quase sempre significa a metade divertida: puxar dados, chamar IA, montar resposta. A metade chata fica para o humano: conferir, corrigir, publicar, avisar, desfazer. O humano vira estagiário do script. Parabéns, você inventou a produtividade ao contrário.

Um bom recorte é pequeno, mas completo. Ele começa em uma entrada definida e termina em uma saída verificável. Pode ser simples: classificar solicitações recebidas por email e criar uma tarefa já com prioridade e contexto. Pode ser técnico: validar backups e abrir alerta apenas quando a restauração falhar. O importante é que o ciclo tenha começo, meio, fim e responsabilidade.

Desenhe estados, não apenas etapas

Fluxogramas bonitos costumam mentir porque mostram apenas o caminho feliz. O mundo real precisa de estados. Uma execução pode estar pendente, validada, bloqueada, concluída, aguardando humano, reprocessando ou arquivada. Esses estados precisam ser explícitos, porque é neles que você evita repetição, perda de dados e aquele clássico “rodei de novo para ver se ia”.

name: automacao-confiavel
trigger:
  type: schedule
  every: 15m
checks:
  - name: entrada_valida
    assert: payload.id != null
  - name: limite_de_tempo
    timeout_seconds: 30
  - name: evidencia
    require_artifact: true
rollback:
  when: check_failed
  action: notify_and_pause

Perceba a intenção: antes de executar, a automação valida. Durante a execução, ela mede tempo. Depois, exige artefato. Se algo falhar, ela pausa e notifica. Parece burocrático. É. Burocracia mínima é o preço de não transformar incidente pequeno em novela.

O box perrengue: quando o sucesso é pior que a falha

Desde então eu trato “sucesso” como uma palavra perigosa. Sucesso precisa ter critério. Quantos itens entraram? Quantos saíram? Quantos foram pulados? Por quê? Qual limite aceitável? O que dispara revisão humana? Sem isso, você só está pintando a lâmpada de verde.

Validação de entrada: a parte adulta da brincadeira

Validação não é frescura de arquiteto. É o cinto de segurança. A automação deve recusar entradas incompletas, ambíguas ou perigosas. Melhor bloquear com clareza do que processar lixo com convicção. Aqui entra um detalhe importante: uma recusa bem explicada também é produtividade. Ela ensina o sistema, o time e o próximo ajuste.

• Defina campos obrigatórios e exemplos válidos.
• Separe erro recuperável de erro fatal.
• Registre a causa da recusa em linguagem humana.
• Evite corrigir automaticamente dados críticos sem deixar trilha.
• Crie uma fila de revisão para casos ambíguos.

Se você usa IA no meio do fluxo, seja ainda mais chato. Modelo de linguagem é ótimo para interpretar contexto, mas péssimo como dono final da verdade. Ele deve sugerir, classificar, resumir e explicar. A decisão irreversível precisa de regra, autorização ou pelo menos uma trava proporcional ao risco.

Logs bons contam uma história curta

Log ruim é um lixão com timestamp. Log bom é uma história curta: recebi isto, decidi aquilo, fiz isso, guardei aqui. Não precisa escrever um romance por execução. Precisa permitir que alguém cansado, às 18h47, entenda o que aconteceu sem abrir uma reunião.

#!/usr/bin/env bash
set -u
run_id="$(date -u +%Y%m%dT%H%M%SZ)"
log="logs/${run_id}.jsonl"
mkdir -p logs artefatos

registrar() {
  printf '{"ts":"%s","evento":"%s","detalhe":"%s"}
'     "$(date -u +%FT%TZ)" "$1" "$2" >> "$log"
}

registrar inicio "execucao iniciada"
if ./scripts/validar-entrada.sh; then
  ./scripts/executar-automacao.sh > "artefatos/${run_id}.txt"
  registrar sucesso "artefato salvo"
else
  registrar bloqueado "entrada invalida"
  exit 0
fi

Esse exemplo é propositalmente simples. Ele cria um identificador, registra eventos e guarda artefatos. Em ambientes maiores, você pode trocar arquivo local por observabilidade decente, fila, banco ou serviço de log. O conceito não muda: cada execução deve deixar evidência suficiente para diagnóstico.

Teste restauração, reversão e repetição

Todo mundo testa se a automação roda. Pouca gente testa se ela pode rodar duas vezes sem destruir o mundo. Idempotência é uma palavra feia para uma ideia linda: repetir a execução não deveria duplicar efeito indevido. Se criou tarefa, a segunda execução deveria atualizar ou detectar que já existe. Se enviou mensagem, deveria saber que já enviou. Se moveu arquivo, deveria saber de onde veio e para onde foi.

Também teste o caminho de volta. Dá para desfazer? Dá para pausar? Dá para colocar em modo simulação? Dá para limitar a 10 itens antes de liberar 10 mil? Automação madura respeita o botão de freio. Automação imatura acha que confiança se conquista no grito.

Use hipóteses para investigar falhas

Quando algo quebra, a tentação é sair mexendo. Troca timeout, muda prompt, adiciona retry, aumenta memória, sacrifica a tarde. Funciona às vezes, mas cobra juros. O caminho melhor é escrever uma hipótese antes de alterar. Uma hipótese força você a dizer o que espera encontrar e como vai medir.

{
  "hipotese": "a falha acontece quando a entrada chega incompleta",
  "sinal_esperado": "campo request_id ausente no log de entrada",
  "teste": "reexecutar com payload minimo e payload completo",
  "criterio_de_saida": "a automacao pausa com mensagem clara ou conclui com artefato"
}

Isso reduz o teatro do debug. Se o sinal esperado não aparece, a hipótese perde força. Se aparece, você tem direção. O objetivo não é parecer científico em reunião. É evitar que o time confunda movimento com avanço.

Onde IA entra sem virar bagunça

IA combina muito bem com triagem, resumo, geração de rascunho, classificação e explicação. Ela combina menos com decisões silenciosas, mudanças irreversíveis e qualquer coisa que envolva dinheiro, reputação ou acesso. A regra prática: quanto maior o impacto, mais explícito deve ser o contrato.

Um bom padrão é pedir que a IA entregue resposta estruturada e justificativa curta. Depois, uma camada determinística valida o formato e decide se passa, bloqueia ou manda para humano. Assim você usa o cérebro probabilístico onde ele brilha e deixa a porteira com alguém mais rabugento.

Métricas que realmente importam

Contar execuções é fácil e quase inútil sozinho. O que importa é medir retrabalho evitado, tempo até resolução, taxa de bloqueio correto, falsos positivos, falsos negativos e incidentes evitados. Se a automação ficou mais rápida mas aumentou correção manual, ela só terceirizou a bagunça para outro lugar.

• Taxa de conclusão limpa: execuções concluídas sem intervenção e com artefato válido.
• Taxa de bloqueio útil: entradas recusadas por motivo correto.
• Tempo de diagnóstico: quanto demora para entender uma falha.
• Reprocessamento seguro: quantas execuções repetidas não geraram duplicidade.
• Economia real: horas humanas removidas, não apenas cliques automatizados.

Como começar nesta semana

Escolha um processo irritante, frequente e com regra minimamente estável. Não escolha o processo mais glamouroso. Glamour em automação é um cheiro estranho. Prefira aquilo que acontece toda semana, consome atenção e dá erro por distração. Em seguida, escreva uma página com entrada, saída, estados, critérios de sucesso, critérios de bloqueio e evidências.

Depois implemente em modo sombra. A automação roda, produz decisão, mas não executa a ação final. Compare com o humano por alguns dias. Ajuste. Só então libere efeito real, primeiro com limite baixo. Essa sequência é menos emocionante do que “subimos em produção sexta à noite”, mas também costuma gerar menos arrependimento.

Links internos para continuar

Se este assunto te interessa, vale navegar pela editoria Mente Binária e comparar com publicações recentes do AutoMente:

• Debug de Automações: O Método Para Encontrar o Erro Antes Que Ele Encontre Você
• Logs estruturados para IA: como fazer seu assistente entender falhas reais sem adivinhar
• Automação resiliente: como criar rotinas que não quebram no primeiro erro idiota

Fechamento: confiança é design, não esperança

prompt engineering verificável não é sobre criar processos pesados. É sobre remover ambiguidade onde ela custa caro. Uma automação confiável sabe dizer “fiz”, “não fiz”, “não entendi” e “preciso de humano”. Essa honestidade operacional vale mais do que qualquer promessa de produtividade infinita.

O ponto vulnerável aqui é simples: eu já me empolguei com automações que pareciam geniais na demonstração e medíocres na segunda semana. Quase sempre faltava a mesma coisa: critério de sucesso, evidência e plano para falha. Hoje eu desconfio de qualquer fluxo que não saiba explicar o próprio comportamento. É uma desconfiança saudável. Meio amarga, talvez. Mas útil.

CTA: qual automação você quer ver destrinchada no AutoMente? Responda com um processo real, daqueles que fazem você perder tempo ou paciência, e eu transformo em arquitetura, perrengues prováveis e um caminho de implementação sem perfume de palestra.

Apêndice prático: checklist de revisão

Antes de liberar, revise o item 1: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.

Antes de liberar, revise o item 2: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.

Antes de liberar, revise o item 3: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.

Antes de liberar, revise o item 4: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.

Antes de liberar, revise o item 5: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.

Antes de liberar, revise o item 6: entrada definida, evidência registrada, limite de impacto, estado claro e pessoa responsável por exceções. Parece repetitivo porque é exatamente assim que sistemas confiáveis nascem: pela repetição disciplinada do básico.