Template de prompt
Um prompt para diagnosticar erros começando pelas evidências.
Este template transforma sintoma, reprodução e evidências disponíveis em um plano de investigação ordenado. Ele ajuda o agente a diagnosticar primeiro e evita alterações prematuras antes que a causa esteja sustentada.
Revisado em 22 de setembro de 2026 · Os templates e exemplos usam dados fictícios.
Quando usar este prompt para diagnóstico
Use-o para um erro reproduzível, uma regressão após uma mudança, uma falha intermitente com logs parciais ou uma diferença entre o comportamento esperado e o observado. Comece pelo menor sintoma reproduzível em vez de pedir que o agente “encontre o bug” no sistema inteiro.
O template separa deliberadamente fatos confirmados de hipóteses. Essa distinção torna a investigação auditável e reduz o risco de a primeira explicação plausível virar uma correção sem teste.
Template reutilizável
Prompt para diagnóstico de erro
# Investigar {{erro}}
## Contexto
- Projeto: {{projeto}}
- Sintoma observado: {{sintoma}}
- Comportamento esperado: {{comportamento_esperado}}
- Passos para reproduzir: {{passos_reproducao}}
- Evidências disponíveis: {{evidencias}}
- Alterações recentes relevantes: {{alteracoes_recentes}}
<instructions>
Rastreie o caminho de execução envolvido na falha. Separe evidências confirmadas de hipóteses e ordene as hipóteses por probabilidade.
Para cada hipótese, indique a observação ou o teste que poderia confirmá-la ou descartá-la. Prefira a menor correção verificável e explique o risco de regressão. Ainda não altere arquivos.
</instructions>
<output_format>
1. Fatos confirmados
2. Hipóteses ordenadas
3. Plano de investigação com verificações concretas
4. Causa raiz mais provável, caso sustentada pelas evidências
5. Menor correção proposta e plano de validação
</output_format>O que coletar antes de perguntar
{{erro}}
Um nome curto para a falha. Mantenha a mensagem exata no campo de evidências.
{{sintoma}}
O que ocorreu, com frequência e consequência visível para o usuário.
{{comportamento_esperado}}
O resultado observável que deveria ter acontecido.
{{passos_reproducao}}
Ações, entradas, ambiente e condições de tempo mínimas para reproduzir.
{{evidencias}}
Logs, stack traces, capturas, testes com falha ou medições relevantes, sempre sem segredos.
{{alteracoes_recentes}}
Deploys, atualizações, configurações ou migrações próximas da primeira ocorrência.
Exemplo preenchido
Erro: Pedido duplicado após nova tentativa.
Projeto: API de checkout e worker de webhooks de pagamento.
Sintoma: Aproximadamente um em cada 200 checkouts com timeout cria dois pedidos para a mesma referência.
Esperado: Repetir a requisição com a mesma chave retorna o pedido original.
Reprodução: Atrasar a resposta do banco além do timeout, repetir com a mesma chave de idempotência e liberar as duas requisições.
Evidência: Duas inserções compartilham a referência; só a segunda requisição registra falha na consulta de idempotência.
Alteração recente: A consulta de idempotência saiu da transação.
Um ciclo prático de investigação
- Fixe os fatos. Registre sintoma e evidências antes de mudar o sistema.
- Reduza a reprodução. Retire serviços e etapas não relacionados enquanto a falha continuar.
- Ordene as hipóteses. Prefira explicações que cubram todos os fatos confirmados.
- Projete uma verificação discriminante. Cada checagem deve alterar a probabilidade de alguma hipótese.
- Aplique a menor correção. Valide a reprodução e comportamentos vizinhos.
Limites e privacidade
Remova credenciais e dados pessoais antes de compartilhar evidências. Se o agente não puder observar runtime, banco ou repositório, peça que ele proponha verificações em vez de fingir que inspecionou esses sistemas.