wasabeef Avaliar e melhorar qualidade de prompts de IA
Coleção abrangente de melhores práticas para avaliar e melhorar a qualidade de prompts para AI Agent. Sistematiza conhecimentos obtidos através de processos reais de melhoria de prompts, cobrindo todos os aspectos importantes: eliminação de ambiguidade, integração de informações, reforço de obrigatoriedade, sistema de rastreamento e melhoria contínua.
Uso
# Verificar qualidade de arquivo de prompt
cat your-prompt.md
/check-prompt
"Verifique a qualidade deste prompt e apresente propostas de melhoria"
Opções
- nenhuma : Analisa o arquivo atual ou texto selecionado
--category <name>: Verifica apenas categoria específica (structure/execution/restrictions/quality/roles/improvement)--score: Calcula apenas o score de qualidade--fix: Proposta de correção automática dos problemas detectados--deep: Modo de análise profunda (foco em ambiguidade, dispersão de informação, força obrigatória)
Exemplos Básicos
# Avaliação geral da qualidade do prompt
cat devin/playbooks/code-review.md
/check-prompt
"Avalie a qualidade deste prompt em 6 categorias e apresente problemas e propostas de melhoria"
# Modo de análise profunda
/check-prompt --deep
"Verifique intensivamente ambiguidade, dispersão de informação e falta de força obrigatória e apresente propostas de melhoria fundamentais"
# Verificação de categoria específica
/check-prompt --category structure
"Verifique este prompt na perspectiva de estrutura e clareza"
# Detecção e correção de expressões ambíguas
/check-prompt --fix
"Detecte expressões ambíguas e proponha correções para expressões claras"
Princípios Fundamentais de Design
Princípio 1: Eliminação Completa de Margem para Interpretação
- Absolutamente proibido: "em princípio", "recomendado", "se possível", "dependendo da situação", "julgue adequadamente"
- Uso obrigatório: "obrigatoriamente", "absolutamente", "cumprimento rigoroso", "sem exceção", "forçado"
- Condições de exceção: Limitação rigorosa com números ("apenas as 3 condições a seguir", "exceto estes 2 casos")
Princípio 2: Integração Estratégica de Informações
- Integração completa de informações importantes relacionadas em uma seção
- Resumo do quadro geral em checklist de execução
- Eliminação completa de referências circulares ou dispersas
Princípio 3: Construção de Força Obrigatória por Etapas
- 🔴 (nível de parada de execução) → 🟡 (qualidade importante) → 🟢 (item recomendado) hierarquia clara
- Promoção gradual do nível recomendado para obrigatório
- Demonstração clara do grau de impacto e métodos de tratamento em caso de violação
Princípio 4: Garantia de Rastreabilidade
- Capacidade de registrar e verificar todos os resultados de execução
- Prevenção técnica de relatórios falsos
- Critérios objetivos de julgamento de sucesso/falha
Princípio 5: Melhoria Baseada em Feedback
- Aprendizado a partir de casos reais de falha
- Verificação contínua de eficácia
- Detecção automática de novos padrões
📋 Itens de Verificação Abrangentes
1. 📐 Estrutura e Clareza (Pontuação: 25 pontos)
1.1 Exibição de Prioridade de Instruções (8 pontos)
- Prioridades 🔴🟡🟢 são claramente indicadas em todas as instruções importantes
- Condições de nível de parada de execução são definidas de forma específica e clara
- Critérios de julgamento de cada prioridade são objetivos e verificáveis
- Hierarquia de prioridades é aplicada de forma consistente
1.2 Eliminação Completa de Expressões Ambíguas (9 pontos)
- Expressões ambíguas fatais: "em princípio", "recomendado", "se possível" = 0 ocorrências
- Uso de expressões obrigatórias: Uso apropriado de "obrigatoriamente", "absolutamente", "cumprimento rigoroso", "sem exceção"
- Limitação numérica de condições de exceção: Linhas de demarcação claras como "apenas 3 condições"
- Eliminação de margem de julgamento: Uso apenas de expressões que não permitem múltiplas interpretações
- Erradicação de zonas cinzentas: Critérios claros de julgamento em todas as situações
1.3 Integração Estratégica de Informações (8 pontos)
- Dispersão de informações importantes em múltiplos locais completamente resolvida
- Instruções relacionadas logicamente integradas em uma seção
- Quadro geral completamente resumido em checklist de execução
- Não existem referências circulares ou loops infinitos
2. 🎯 Executabilidade (Pontuação: 20 pontos)
2.1 Integridade de Procedimentos Específicos (7 pontos)
- Todos os exemplos de comandos são executáveis e verificados
- Variáveis de ambiente, pré-requisitos e dependências claramente especificados
- Métodos de tratamento de erros específicos e executáveis
- Ordem dos procedimentos lógica e com necessidade
2.2 Garantia de Verificabilidade (7 pontos)
- Sucesso/falha dos resultados de execução podem ser julgados objetivamente
- Exemplos de saída, formatos de log e valores esperados mostrados especificamente
- Métodos de teste e procedimentos de verificação implementáveis
- Pontos de verificação de resultados intermediários adequadamente posicionados
2.3 Adaptabilidade à Automação (6 pontos)
- Formato fácil para criação de scripts e integração CI/CD
- Separação clara entre partes de julgamento humano e execução de IA
- Suporte para processamento em lote e execução paralela
3. 🚫 Clarificação de Itens Proibidos (Pontuação: 15 pontos)
3.1 Sistematização de Itens Absolutamente Proibidos (8 pontos)
- Lista completa de operações que não devem ser executadas
- Indicação do grau de impacto de violação de cada item proibido (leve/grave/fatal)
- Apresentação específica de meios alternativos e métodos de contorno
- Explicação das bases técnicas dos itens proibidos
3.2 Limitação Rigorosa de Condições de Exceção (7 pontos)
- Condições para reconhecer exceções específicas e limitadas (especificação numérica)
- Critérios objetivos de julgamento como "completamente duplicado", "explicitamente descrito"
- Linhas de demarcação claras que não deixam zonas cinzentas
- Indicação de condições e restrições adicionais ao aplicar exceções
4. 📊 Mecanismo de Garantia de Qualidade (Pontuação: 20 pontos)
4.1 Integridade do Sistema de Rastreamento (8 pontos)
- Função de registro automático e obtenção de estatísticas de todos os resultados de execução
- Função de verificação que previne tecnicamente relatórios falsos
- Função de monitoramento em tempo real e alertas
- Função de prevenção de alteração de logs de auditoria
4.2 Obrigatoriedade de Conformidade com Template (7 pontos)
- Definição clara de elementos obrigatórios e função de verificação
- Limitações técnicas em locais proibidos de customização
- Checkpoints automatizados de confirmação de conformidade
- Função automática de correção e aviso em caso de violação
4.3 Abrangência do Tratamento de Erros (5 pontos)
- Catalogação completa de padrões de erro esperados
- Processo de tratamento por etapas em caso de erro
- Prevenção técnica de relatar falha como sucesso
5. 🎭 Clarificação de Papéis e Responsabilidades (Pontuação: 10 pontos)
5.1 Escopo de Autoridade do AI Agent (5 pontos)
- Linha de demarcação clara entre operações executáveis e proibidas
- Escopo específico e restrições da autoridade de julgamento
- Separação clara de operações que requerem confirmação humana
5.2 Unificação do Sistema de Classificação (5 pontos)
- Clareza, unicidade e exclusividade das definições de classificação
- Explicação explícita para prevenir mal-entendidos sobre importância entre classificações
- Exemplos específicos de uso de cada classificação e fluxograma de julgamento
6. 🔄 Melhoria Contínua (Pontuação: 10 pontos)
6.1 Automação da Coleta de Feedback (5 pontos)
- Extração automática de pontos de melhoria de logs de execução
- Análise baseada em machine learning de padrões de falha
- Mecanismo de atualização automática de melhores práticas
6.2 Implementação de Função de Aprendizado (5 pontos)
- Detecção e classificação automática de novos padrões
- Monitoramento contínuo da eficácia de regras existentes
- Proposta automática de melhorias graduais
🚨 Padrões de Problemas Fatais (Correção Imediata Necessária)
❌ Nível 1: Ambiguidade Fatal (Nível de Parada de Execução)
- Instruções com múltiplas interpretações possíveis: "julgue adequadamente", "dependendo da situação", "em princípio"
- Condições ambíguas de exceção: "em casos especiais", "conforme necessário"
- Critérios subjetivos de julgamento: "adequadamente", "suficientemente", "na medida do possível"
- Conceitos importantes não definidos: "padrão", "geral", "básico"
❌ Nível 2: Defeitos Estruturais (Nível de Qualidade Importante)
- Dispersão de informações: Informações importantes relacionadas dispersas em 3 ou mais locais
- Referência circular: Loop infinito Seção A→B→C→A
- Instruções contraditórias: Instruções opostas em seções diferentes
- Ordem de execução não clara: Procedimentos com dependências não claras
❌ Nível 3: Degradação da Qualidade (Nível de Melhoria Recomendada)
- Não verificabilidade: Critérios de julgamento de sucesso/falha não claros
- Dificuldade de automação: Design que depende de julgamento subjetivo humano
- Dificuldade de manutenção: Estrutura onde o escopo de impacto de atualizações não pode ser previsto
- Dificuldade de aprendizado: Complexidade que leva tempo para novos usuários entenderem
🎯 Métodos de Melhoria Comprovados
✅ Abordagem de Reforço Gradual
- Análise da situação atual: Classificação de problemas, priorização, avaliação do grau de impacto
- Prioridade para problemas fatais: Resolução completa de problemas Nível 1 como máxima prioridade
- Implementação gradual: Não fazer todas as mudanças de uma vez, implementar em unidades verificáveis
- Medição de efeitos: Comparação quantitativa antes e depois da melhoria
- Monitoramento contínuo: Confirmação da sustentabilidade dos efeitos de melhoria
✅ Métodos Práticos de Eliminação de Ambiguidade
# ❌ Antes da melhoria (ambíguo)
"Pontos apontados devem, em princípio, ser descritos como comentários inline nos locais de mudança correspondentes no GitHub"
# ✅ Depois da melhoria (claro)
"Pontos apontados devem ser obrigatoriamente descritos como comentários inline nos locais de mudança correspondentes no GitHub. Exceções são apenas as 3 condições definidas na Seção 3.3"
✅ Métodos Práticos de Integração de Informações
# ❌ Antes da melhoria (disperso)
Seção 2.1: "Usar 6 seções obrigatórias"
Seção 3.5: "📊 Avaliação geral, 📋 Itens apontados..."
Seção 4.2: "Proibição de deletar seções"
# ✅ Depois da melhoria (integrado)
Checklist de execução:
□ 10. Postar comentário de resumo (usar 6 seções obrigatórias)
🔴 6 seções obrigatórias: 1) 📊 Avaliação geral 2) 📋 Agregação por classificação de itens apontados 3) ⚠️ Principais preocupações 4) ✅ Pontos avaliáveis 5) 🎯 Conclusão 6) 🤖 Auto-avaliação da qualidade do review de IA
❌ Absolutamente proibido: deletar, adicionar, renomear seções
✅ Padrões de Implementação de Sistema de Rastreamento
# Rastreamento rigoroso de resultados de execução
POSTED_COMMENTS=0
FAILED_COMMENTS=0
TOTAL_COMMENTS=0
# Registro de resultado de cada operação
if [ $? -eq 0 ]; then
echo "✅ Sucesso: $OPERATION" >> /tmp/execution_log.txt
POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
else
echo "❌ Falha: $OPERATION" >> /tmp/execution_log.txt
FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
fi
# Prevenção de relatórios falsos
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
echo "🚨 Aviso: Número reportado e número real de posts não coincidem"
exit 1
fi
📈 Cálculo de Score de Qualidade (Versão Melhorada)
Cálculo do Score Total
Score base = Σ(Score de cada categoria × Pontuação) / 100
Penalidades por problemas fatais:
- Problemas Nível 1: -20 pontos/caso
- Problemas Nível 2: -10 pontos/caso
- Problemas Nível 3: -5 pontos/caso
Elementos de bônus:
- Suporte à automação: +5 pontos
- Implementação de função de aprendizado: +5 pontos
- Casos de melhoria comprovados: +5 pontos
Score final = Score base + Bônus - Penalidades
Julgamento do Nível de Qualidade
95-100 pontos: Padrão mundial mais alto (recomendável como padrão da indústria)
90-94 pontos: Excelente (operável em produção)
80-89 pontos: Bom (operável com melhorias menores)
70-79 pontos: Normal (melhoria necessária)
60-69 pontos: Requer melhoria (correção substancial necessária)
50-59 pontos: Requer correção substancial (revisão fundamental necessária)
49 pontos ou menos: Proibido o uso (redesign completo necessário)
🔧 Processo Prático de Melhoria
Fase 1: Diagnóstico e Análise (1-2 dias)
- Compreensão da estrutura geral: Visualização de configuração de seções, fluxo de informações, relações de dependência
- Detecção de ambiguidade: Extração de todas as expressões com margem de interpretação
- Análise de dispersão de informações: Mapeamento de padrões de dispersão de informações relacionadas
- Avaliação de força obrigatória: Avaliação de classificação e eficácia de recomendado/obrigatório
- Confirmação de rastreabilidade: Avaliação de funções de registro e verificação de resultados de execução
Fase 2: Priorização e Planejamento (meio dia)
- Classificação de criticidade: Classificação de problemas Nível 1-3 e avaliação do grau de impacto
- Determinação da ordem de melhoria: Ordem ótima considerando relações de interdependência
- Alocação de recursos: Otimização do equilíbrio entre efeito de melhoria e custo
- Avaliação de riscos: Previsão de efeitos colaterais e problemas de compatibilidade durante melhoria
Fase 3: Implementação Gradual (2-5 dias)
- Resolução de problemas Nível 1: Eliminação completa de ambiguidade fatal
- Implementação de integração de informações: Agregação estratégica de informações dispersas
- Reforço de força obrigatória: Promoção gradual de recomendado → obrigatório
- Implementação de sistema de rastreamento: Função automática de registro e verificação de resultados de execução
- Reforço de template: Clarificação de elementos obrigatórios e obrigatoriedade de conformidade
Fase 4: Verificação e Ajuste (1-2 dias)
- Teste de função: Confirmação de operação de todos os pontos de mudança
- Teste de integração: Confirmação de consistência do sistema como um todo
- Teste de performance: Confirmação de eficiência de execução e resposta
- Teste de usabilidade: Verificação em cenários reais de uso
Fase 5: Operação e Monitoramento (contínuo)
- Medição de efeitos: Comparação quantitativa antes e depois da melhoria
- Monitoramento contínuo: Detecção precoce de degradação da qualidade
- Coleta de feedback: Extração de problemas na operação real
- Otimização contínua: Ciclo de melhoria contínua
📊 Casos Reais de Melhoria (Versão Detalhada)
Estudo de Caso: Melhoria da Qualidade de Prompt de Grande Escala
Situação Antes da Melhoria
Score de qualidade: 70 pontos/100 pontos
- Expressões ambíguas: 15 locais encontrados
- Dispersão de informações: Informações importantes dispersas em 6 locais
- Falta de força obrigatória: 80% expressões de nível recomendado
- Função de rastreamento: Nenhum registro de resultados de execução
- Tratamento de erros: Métodos de tratamento em caso de falha não claros
Conteúdos de Melhoria Implementados
# 1. Eliminação de ambiguidade (2 dias)
- "em princípio" → "exceções são apenas as 3 condições da Seção 3.3"
- "recomendado" → "obrigatório" (nível de importância 2 ou superior)
- "adequadamente" → indicação de critérios específicos de julgamento
# 2. Integração de informações (1 dia)
- Informações dispersas das 6 seções obrigatórias → integradas no checklist de execução
- Itens proibidos relacionados → agregados em uma seção
- Resolução de referências circulares → fluxo linear de informações
# 3. Implementação de sistema de rastreamento (1 dia)
- Registro automático de logs de resultados de execução
- Função de verificação para prevenção de relatórios falsos
- Exibição de estatísticas em tempo real
# 4. Reforço do tratamento de erros (meio dia)
- Catalogação completa de padrões de erro esperados
- Documentação de processo de tratamento por etapas
- Implementação de função de recuperação automática
Resultados Após Melhoria
Score de qualidade: 90 pontos/100 pontos (+20 pontos de melhoria)
- Expressões ambíguas: 0 locais (eliminação completa)
- Integração de informações: Informações importantes agregadas em 3 locais
- Força obrigatória: 95% expressões de nível obrigatório
- Função de rastreamento: Automação completa
- Tratamento de erros: 90% dos problemas resolvidos automaticamente
Efeitos reais de melhoria:
- Erros de julgamento: 85% de redução
- Tempo de execução: 40% de redução
- Taxa de ocorrência de erros: 70% de redução
- Satisfação do usuário: 95% de melhoria
Lições Aprendidas e Melhores Práticas
Fatores de Sucesso
- Abordagem gradual: Não fazer todas as mudanças de uma vez, implementar em unidades verificáveis
- Baseado em dados: Melhoria baseada em dados medidos, não julgamento subjetivo
- Monitoramento contínuo: Confirmação periódica da sustentabilidade dos efeitos de melhoria
- Foco no feedback: Coleta ativa de opiniões de usuários reais
Estratégias para Evitar Falhas
- Perfeccionismo excessivo: Começar operação ao atingir 90 pontos, buscar 100 pontos com melhoria contínua
- Perigo de mudanças em lote: Implementar sempre mudanças de grande escala de forma gradual
- Compatibilidade com versões anteriores: Minimizar impacto em workflows existentes
- Falta de documentação: Registrar e compartilhar todas as mudanças detalhadamente
Integração com Claude
# Verificação de qualidade combinando com arquivo de prompt
cat your-prompt.md
/check-prompt
"Avalie a qualidade deste prompt e proponha pontos de melhoria"
# Comparação de múltiplos arquivos de prompt
cat prompt-v1.md && echo "---" && cat prompt-v2.md
/check-prompt
"Compare as duas versões e analise pontos melhorados e desafios restantes"
# Análise combinando com log de erros reais
cat execution-errors.log
/check-prompt --deep
"Identifique problemas no prompt que podem ter causado este erro"
Observações
- Pré-requisitos: Recomenda-se que os arquivos de prompt sejam descritos em formato Markdown
- Limitações: Para prompts de grande escala (mais de 10 mil linhas), recomenda-se dividir para análise
- Recomendação: Implemente verificações regulares de qualidade de prompt e melhore continuamente
Esta checklist é uma versão completa de conhecimentos comprovados em projetos reais de melhoria de prompts e continua evoluindo continuamente.