Avaliar e melhorar qualidade de prompts de IA

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

1. Análise da situação atual: Classificação de problemas, priorização, avaliação do grau de impacto
2. Prioridade para problemas fatais: Resolução completa de problemas Nível 1 como máxima prioridade
3. Implementação gradual: Não fazer todas as mudanças de uma vez, implementar em unidades verificáveis
4. Medição de efeitos: Comparação quantitativa antes e depois da melhoria
5. 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)

1. Compreensão da estrutura geral: Visualização de configuração de seções, fluxo de informações, relações de dependência
2. Detecção de ambiguidade: Extração de todas as expressões com margem de interpretação
3. Análise de dispersão de informações: Mapeamento de padrões de dispersão de informações relacionadas
4. Avaliação de força obrigatória: Avaliação de classificação e eficácia de recomendado/obrigatório
5. 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)

1. Classificação de criticidade: Classificação de problemas Nível 1-3 e avaliação do grau de impacto
2. Determinação da ordem de melhoria: Ordem ótima considerando relações de interdependência
3. Alocação de recursos: Otimização do equilíbrio entre efeito de melhoria e custo
4. Avaliação de riscos: Previsão de efeitos colaterais e problemas de compatibilidade durante melhoria

Fase 3: Implementação Gradual (2-5 dias)

1. Resolução de problemas Nível 1: Eliminação completa de ambiguidade fatal
2. Implementação de integração de informações: Agregação estratégica de informações dispersas
3. Reforço de força obrigatória: Promoção gradual de recomendado → obrigatório
4. Implementação de sistema de rastreamento: Função automática de registro e verificação de resultados de execução
5. Reforço de template: Clarificação de elementos obrigatórios e obrigatoriedade de conformidade

Fase 4: Verificação e Ajuste (1-2 dias)

1. Teste de função: Confirmação de operação de todos os pontos de mudança
2. Teste de integração: Confirmação de consistência do sistema como um todo
3. Teste de performance: Confirmação de eficiência de execução e resposta
4. Teste de usabilidade: Verificação em cenários reais de uso

Fase 5: Operação e Monitoramento (contínuo)

1. Medição de efeitos: Comparação quantitativa antes e depois da melhoria
2. Monitoramento contínuo: Detecção precoce de degradação da qualidade
3. Coleta de feedback: Extração de problemas na operação real
4. 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

1. Abordagem gradual: Não fazer todas as mudanças de uma vez, implementar em unidades verificáveis
2. Baseado em dados: Melhoria baseada em dados medidos, não julgamento subjetivo
3. Monitoramento contínuo: Confirmação periódica da sustentabilidade dos efeitos de melhoria
4. Foco no feedback: Coleta ativa de opiniões de usuários reais

Estratégias para Evitar Falhas

1. Perfeccionismo excessivo: Começar operação ao atingir 90 pontos, buscar 100 pontos com melhoria contínua
2. Perigo de mudanças em lote: Implementar sempre mudanças de grande escala de forma gradual
3. Compatibilidade com versões anteriores: Minimizar impacto em workflows existentes
4. 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.