SamuelChien/mega-skills-collection

Fluxo de Trabalho de Otimização de Desempenho de Agentes

Melhoria sistemática de agentes existentes por meio de análise de desempenho, engenharia de prompts e iteração contínua.

[Pensamento estendido: A otimização de agentes requer uma abordagem orientada por dados que combina métricas de desempenho, análise de feedback do usuário e técnicas avançadas de engenharia de prompts. O sucesso depende de avaliação sistemática, melhorias direcionadas e testes rigorosos com capacidade de reversão para segurança em produção.]

Use este skill quando

• Melhorar o desempenho ou a confiabilidade de um agente existente
• Analisar modos de falha, qualidade do prompt ou uso de ferramentas
• Executar suítes de testes A/B ou avaliações estruturadas
• Projetar fluxos de trabalho de otimização iterativos para agentes

Não use este skill quando

• Você está construindo um agente totalmente novo do zero
• Não há métricas, feedback ou casos de teste disponíveis
• A tarefa não está relacionada ao desempenho do agente ou à qualidade do prompt

Instruções

1. Estabeleça métricas de baseline e colete exemplos representativos.
2. Identifique modos de falha e priorize correções de alto impacto.
3. Aplique melhorias de prompt e fluxo de trabalho com metas mensuráveis.
4. Valide com testes e implemente mudanças em estágios controlados.

Segurança

• Evite implantar alterações de prompt sem testes de regressão.
• Reverta rapidamente se as métricas de qualidade ou segurança regredirem.

Fase 1: Análise de Desempenho e Métricas de Baseline

Análise abrangente do desempenho do agente usando context-manager para coleta de dados históricos.

1.1 Coletar Dados de Desempenho

Use: context-manager
Command: analyze-agent-performance $ARGUMENTS --days 30

Colete métricas incluindo:

• Taxa de conclusão de tarefas (tarefas bem-sucedidas vs. falhas)
• Precisão da resposta e correção factual
• Eficiência no uso de ferramentas (ferramentas corretas, frequência de chamadas)
• Tempo médio de resposta e consumo de tokens
• Indicadores de satisfação do usuário (correções, tentativas)
• Incidentes de alucinação e padrões de erro

1.2 Análise de Padrões de Feedback do Usuário

Identifique padrões recorrentes nas interações do usuário:

• Padrões de correção: Onde os usuários modificam consistentemente as saídas
• Solicitações de esclarecimento: Áreas comuns de ambiguidade
• Abandono de tarefas: Pontos onde os usuários desistem
• Perguntas de acompanhamento: Indicadores de respostas incompletas
• Feedback positivo: Padrões bem-sucedidos a preservar

1.3 Classificação de Modos de Falha

Categorize falhas por causa raiz:

• Má compreensão da instrução: Confusão de função ou tarefa
• Erros de formato de saída: Problemas de estrutura ou formatação
• Perda de contexto: Degradação em conversas longas
• Uso indevido de ferramentas: Seleção incorreta ou ineficiente de ferramentas
• Violações de restrições: Quebras de regras de segurança ou de negócios
• Tratamento de casos extremos: Cenários de entrada incomuns

1.4 Relatório de Baseline de Desempenho

Gere métricas quantitativas de baseline:

Baseline de Desempenho:
- Taxa de Sucesso de Tarefas: [X%]
- Correções Médias por Tarefa: [Y]
- Eficiência de Chamadas de Ferramentas: [Z%]
- Pontuação de Satisfação do Usuário: [1-10]
- Latência Média de Resposta: [Xms]
- Proporção de Eficiência de Tokens: [X:Y]

Fase 2: Melhorias de Engenharia de Prompts

Aplique técnicas avançadas de otimização de prompts usando o agente prompt-engineer.

2.1 Aprimoramento de Chain-of-Thought

Implemente padrões de raciocínio estruturados:

Use: prompt-engineer
Technique: chain-of-thought-optimization

• Adicione etapas de raciocínio explícitas: "Vamos abordar isso passo a passo..."
• Inclua pontos de verificação de autoverificação: "Antes de prosseguir, verifique se..."
• Implemente decomposição recursiva para tarefas complexas
• Adicione visibilidade do rastro de raciocínio para depuração

2.2 Otimização de Exemplos Few-Shot

Selecione exemplos de alta qualidade de interações bem-sucedidas:

• Selecione exemplos diversos cobrindo casos de uso comuns
• Inclua casos extremos que falharam anteriormente
• Mostre exemplos positivos e negativos com explicações
• Ordene exemplos do simples para o complexo
• Anote exemplos com pontos de decisão importantes

Estrutura de exemplo:

Bom Exemplo:
Entrada: [Solicitação do usuário]
Raciocínio: [Processo de pensamento passo a passo]
Saída: [Resposta bem-sucedida]
Por que funciona: [Fatores-chave de sucesso]

Mau Exemplo:
Entrada: [Solicitação semelhante]
Saída: [Resposta falha]
Por que falha: [Problemas específicos]
Abordagem correta: [Versão corrigida]

2.3 Refinamento da Definição de Papel

Fortaleça a identidade e as capacidades do agente:

• Propósito central: Missão clara em uma frase
• Domínios de especialização: Áreas de conhecimento específicas
• Traços comportamentais: Personalidade e estilo de interação
• Proficiência em ferramentas: Ferramentas disponíveis e quando usá-las
• Restrições: O que o agente NÃO deve fazer
• Critérios de sucesso: Como medir a conclusão da tarefa

2.4 Integração de IA Constitucional

Implemente mecanismos de autocorreção:

Princípios Constitucionais:
1. Verifique a precisão factual antes de responder
2. Autoavalie possíveis vieses ou conteúdo prejudicial
3. Valide se o formato da saída corresponde aos requisitos
4. Garanta a completude da resposta
5. Mantenha consistência com respostas anteriores

Adicione loops de crítica e revisão:

• Geração de resposta inicial
• Autocrítica com base nos princípios
• Revisão automática se problemas forem detectados
• Validação final antes da saída

2.5 Ajuste de Formato de Saída

Otimize a estrutura da resposta:

• Modelos estruturados para tarefas comuns
• Formatação dinâmica com base na complexidade
• Divulgação progressiva para informações detalhadas
• Otimização de Markdown para legibilidade
• Formatação de blocos de código com destaque de sintaxe
• Geração de tabelas e listas para apresentação de dados

Fase 3: Testes e Validação

Estrutura abrangente de testes com comparação A/B.

3.1 Desenvolvimento de Suíte de Testes

Crie cenários de teste representativos:

Categorias de Teste:
1. Cenários de caminho feliz (casos bem-sucedidos comuns)
2. Tarefas que falharam anteriormente (teste de regressão)
3. Casos extremos e cenários de borda
4. Testes de estresse (tarefas complexas, de várias etapas)
5. Entradas adversariais (pontos de falha em potencial)
6. Tarefas entre domínios (combinação de capacidades)

3.2 Estrutura de Testes A/B

Compare agente original vs. melhorado:

Use: parallel-test-runner
Config:
  - Agente A: Versão original
  - Agente B: Versão melhorada
  - Conjunto de teste: 100 tarefas representativas
  - Métricas: Taxa de sucesso, velocidade, uso de tokens
  - Avaliação: Revisão humana cega + pontuação automatizada

Teste de significância estatística:

• Tamanho mínimo da amostra: 100 tarefas por variante
• Nível de confiança: 95% (p < 0,05)
• Cálculo do tamanho do efeito (d de Cohen)
• Análise de poder para testes futuros

3.3 Métricas de Avaliação

Estrutura abrangente de pontuação:

Métricas de Nível de Tarefa:

• Taxa de conclusão (sucesso/falha binário)
• Pontuação de correção (0-100% de precisão)
• Pontuação de eficiência (etapas executadas vs. ideal)
• Adequação do uso da ferramenta
• Relevância e completude da resposta

Métricas de Qualidade:

• Taxa de alucinação (erros factuais por resposta)
• Pontuação de consistência (alinhamento com respostas anteriores)
• Conformidade de formato (corresponde à estrutura especificada)
• Pontuação de segurança (aderência às restrições)
• Previsão de satisfação do usuário

Métricas de Desempenho:

• Latência de resposta (tempo até o primeiro token)
• Tempo total de geração
• Consumo de tokens (entrada + saída)
• Custo por tarefa (taxas de uso da API)
• Eficiência de memória/contexto

3.4 Protocolo de Avaliação Humana

Processo estruturado de revisão humana:

• Avaliação cega (avaliadores não sabem a versão)
• Rubrica padronizada com critérios claros
• Vários avaliadores por amostra (confiabilidade entre avaliadores)
• Coleta de feedback qualitativo
• Classificação de preferência (comparação A vs B)

Fase 4: Controle de Versão e Implantação

Implantação segura com monitoramento e capacidade de reversão.

4.1 Gerenciamento de Versão

Estratégia de versionamento sistemático:

Formato da Versão: nome-do-agente-v[MAJOR].[MINOR].[PATCH]
Exemplo: suporte-ao-cliente-v2.3.1

MAJOR: Mudanças significativas de capacidade
MINOR: Melhorias de prompt, novos exemplos
PATCH: Correções de bugs, ajustes menores

Mantenha o histórico de versões:

• Armazenamento de prompts baseado em Git
• Changelog com detalhes das melhorias
• Métricas de desempenho por versão
• Procedimentos de reversão documentados

4.2 Implantação em Estágios

Estratégia de implantação progressiva:

1. Testes Alpha: Validação pela equipe interna (5% do tráfego)
2. Testes Beta: Usuários selecionados (20% do tráfego)
3. Lançamento Canário: Aumento gradual (20% → 50% → 100%)
4. Implantação Completa: Após cumprir critérios de sucesso
5. Período de Monitoramento: Janela de observação de 7 dias

4.3 Procedimentos de Reversão

Mecanismo de recuperação rápida:

Gatilhos de Reversão:
- Queda na taxa de sucesso >10% em relação ao baseline
- Aumento de erros críticos >5%
- Pico de reclamações de usuários
- Aumento do custo por tarefa >20%
- Violações de segurança detectadas

Processo de Reversão:
1. Detecte o problema via monitoramento
2. Alerte a equipe imediatamente
3. Alterne para a versão estável anterior
4. Analise a causa raiz
5. Corrija e teste novamente antes de repetir

4.4 Monitoramento Contínuo

Acompanhamento de desempenho em tempo real:

• Painel com métricas principais
• Alertas de detecção de anomalias
• Coleta de feedback do usuário
• Testes de regressão automatizados
• Relatórios semanais de desempenho

Critérios de Sucesso

O aprimoramento do agente é bem-sucedido quando:

• A taxa de sucesso de tarefas melhora em ≥15%
• As correções do usuário diminuem em ≥25%
• Não há aumento nas violações de segurança
• O tempo de resposta permanece dentro de 10% do baseline
• O custo por tarefa não aumenta >5%
• O feedback positivo do usuário aumenta

Revisão Pós-Implantação

Após 30 dias de uso em produção:

1. Analise os dados de desempenho acumulados
2. Compare com o baseline e as metas
3. Identifique novas oportunidades de melhoria
4. Documente as lições aprendidas
5. Planeje o próximo ciclo de otimização

Ciclo de Melhoria Contínua

Estabeleça uma cadência regular de melhoria:

• Semanalmente: Monitore métricas e colete feedback
• Mensalmente: Analise padrões e planeje melhorias
• Trimestralmente: Grandes atualizações de versão com novas capacidades
• Anualmente: Revisão estratégica e atualizações de arquitetura

Lembre-se: A otimização de agentes é um processo iterativo. Cada ciclo se baseia em aprendizados anteriores, melhorando gradualmente o desempenho enquanto mantém a estabilidade e a segurança.

Limitações

• Use este skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação, teste ou revisão especializada específica do ambiente.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.