📊 Por que sub-agentes superam testes manuais
Testes manuais de skills têm um defeito estrutural: você testa o caminho que você imaginou. Você criou a skill com uma intenção de uso em mente, e naturalmente vai testá-la nessa intenção. Os casos que você não imaginou — os edge cases, os usuários com perfis diferentes, as situações extremas — ficam invisíveis até que alguém os encontre na prática. Sub-agentes resolvem esse problema porque não têm o viés do criador. Eles simulam sistematicamente o espaço de possibilidades, incluindo os cenários que nenhum humano pensaria em testar. O resultado é uma cobertura de teste radicalmente mais ampla, com uma fração do tempo que testes manuais abrangentes demandariam.
🎯 A vantagem estrutural dos sub-agentes
Testes manuais
- ✗Viés do criador — testa o caminho feliz
- ✗Escala linear com o número de casos
- ✗Edge cases raramente cobertos
- ✗Perspectiva de uma única persona
Sub-agentes
- ✓Sem viés — explora todo o espaço
- ✓Paralelizável para cobertura total
- ✓Edge cases são o foco principal
- ✓Múltiplas personas simultâneas
💡 Dica Prática
Comece com sub-agentes apenas para suas 5 skills mais usadas. O ROI é imediato e você vai calibrar o processo antes de escalar. Tentar fazer tudo de uma vez é a receita para abandonar a prática antes de sentir os resultados.
👥 Agente de UX friction
UX friction é o atrito que surge quando uma skill é difícil de usar — quando o trigger não é intuitivo, quando as instruções assumem conhecimento que o usuário não tem, quando o output requer interpretação excessiva. O agente de UX friction simula múltiplos perfis de usuário e identifica sistematicamente esses pontos de atrito. Diferente de uma análise técnica, que pergunta "isso funciona?", o agente de UX friction pergunta "isso é fácil de usar para pessoas diferentes?" — uma distinção crítica porque uma skill pode ser tecnicamente correta e ainda assim ser praticamente inutilizável para qualquer pessoa além do criador.
👥 Personas de teste recomendadas
Persona 1: O Iniciante
Não sabe o que a skill faz, vai tentar acioná-la de formas inesperadas, não leu a documentação
Persona 2: O Impaciente
Quer resultados imediatos, vai pular etapas, vai dar o mínimo de contexto possível
Persona 3: O Perfeccionista
Vai questionar cada instrução, vai querer customizar tudo, vai encontrar ambiguidades
Persona 4: O Expert
Sabe mais do que a skill assume, vai querer bypass das etapas básicas, vai testar os limites
🤖 Prompt do Agente de UX Friction
Você vai simular 4 perfis de usuário tentando usar a skill abaixo. Para cada perfil, relate: (1) como tenta acionar a skill, (2) onde encontra atrito, (3) o que pode fazer de errado. [COLE O CONTEÚDO COMPLETO DA SKILL AQUI] ## Perfil 1: Iniciante - Tentativa de acionamento: Como alguém sem experiência tentaria usar? - Pontos de atrito: O que seria confuso ou difícil de entender? - Erros prováveis: O que poderia dar errado sem perceber? ## Perfil 2: Impaciente - Tentativa de acionamento: Como alguém com pressa tentaria usar? - Pontos de atrito: Quais etapas pareceriam desnecessárias? - Erros prováveis: O que seria pulado com consequências negativas? ## Perfil 3: Perfeccionista - Tentativa de acionamento: O que seria questionado antes de usar? - Pontos de atrito: Quais ambiguidades gerariam paralisia? - Erros prováveis: Onde a interpretação excessiva levaria ao lugar errado? ## Perfil 4: Expert - Tentativa de acionamento: Como alguém avançado tentaria customizar? - Pontos de atrito: O que pareceria excessivamente básico ou limitante? - Erros prováveis: Onde a expertise levaria a comportamentos inesperados? ## Síntese Liste os 5 principais pontos de atrito identificados em todos os perfis, ordenados do mais crítico ao menos crítico. Para cada um: o que causou, quem é mais afetado, como corrigir.
💡 Dica Prática
O Perfil 2 (Impaciente) é geralmente o mais revelador. Usuários impacientes expõem todas as etapas que parecem obrigatórias mas que a skill consegue executar com menos contexto. Se o impaciente pode pular algo sem comprometer o resultado, essa etapa provavelmente é opcional e deve ser marcada como tal.
🔬 Agente de auditoria estrutural
Enquanto o agente de UX friction foca na experiência do usuário, o agente de auditoria estrutural foca na arquitetura interna da skill. Ele analisa o fluxo de decisão, identifica redundâncias de instrução, mapeia os pontos onde a skill pode falhar silenciosamente (sem erro explícito, mas com resultado errado) e verifica se a skill tem scope creep — fazendo mais do que deveria. Problemas estruturais raramente aparecem em uso normal; eles aparecem nos casos que desafiam as suposições implícitas da skill. O agente de auditoria estrutural faz exatamente isso: testa as suposições, não o comportamento declarado, expondo fraquezas que ficam invisíveis no caminho feliz.
🔬 O que a auditoria estrutural verifica
- •Fluxo de decisão: A skill tem um caminho claro do trigger ao output, sem becos sem saída?
- •Redundância: Há instruções que se repetem ou que contradizem outras?
- •Falha silenciosa: Há situações em que a skill produziria output errado sem sinalizar o problema?
- •Scope creep: A skill tenta fazer mais do que seu propósito declarado?
- •Dependências ocultas: A skill assume recursos ou contextos que podem não estar disponíveis?
💡 Dica Prática
Foque especialmente nas falhas silenciosas — cenários onde a skill executa sem erro mas produz output incorreto. Essas são as mais perigosas porque você não sabe que algo está errado. Peça ao agente para listar especificamente as situações onde isso pode acontecer.
✓ Sinais de boa estrutura
- ✓Cada instrução tem propósito único e claro
- ✓Fluxo linear sem bifurcações ambíguas
- ✓Falhas são sinalizadas explicitamente
- ✓Escopo claro e limitado
✗ Sinais de estrutura problemática
- ✗Instruções que dependem de "bom senso"
- ✗Múltiplas formas de interpretar o fluxo
- ✗Nenhum tratamento de caso de falha
- ✗Skill tentando resolver 3 problemas diferentes
📋 Como ler os relatórios
Sub-agentes bem configurados produzem relatórios detalhados — e relatórios detalhados sem triagem produzem paralisia. A habilidade de ler e priorizar os achados é tão importante quanto a habilidade de gerar os achados. O framework de classificação por impacto — high, medium, low — parece simples mas requer julgamento calibrado para ser aplicado corretamente. High impact não significa "sério", significa "afeta significativamente a utilidade da skill para casos de uso comuns". Low impact não significa "ignorar", significa "melhora desejável quando houver tempo". A distinção define onde você deve focar sua energia limitada de melhoria.
🎯 Framework de classificação por impacto
HIGH IMPACT — Corrigir antes de usar
Afeta casos de uso comuns, pode produzir output incorreto em situações frequentes, ou torna a skill difícil de usar para qualquer perfil de usuário. Se não corrigir, a skill vai causar problemas regularmente.
MEDIUM IMPACT — Corrigir no próximo ciclo
Afeta casos de uso menos frequentes ou degrada a qualidade do output sem torná-lo inútil. A skill funciona razoavelmente bem sem essa correção, mas seria significativamente melhor com ela.
LOW IMPACT — Endereçar quando houver tempo
Melhorias cosméticas, casos extremamente raros, ou otimizações de performance em situações específicas. A skill não está pior por não ter essas correções; apenas poderia ser ligeiramente melhor.
💡 Dica Prática
Antes de ler o relatório, decida quantas horas você tem para melhorias nessa skill. Se tem 30 minutos, corrige apenas high impact. Se tem 2 horas, adiciona os medium impact. Nunca comece pelos low impact — é a armadilha clássica de otimizar o que não importa enquanto o que importa continua quebrado.
🎯 Priorizando e corrigindo
Com o relatório priorizado em mãos, o processo de correção tem uma lógica clara: começar pelos high impact, validar cada correção antes de avançar para a próxima, e manter um registro das mudanças feitas. A tentação é corrigir tudo de uma vez — mas correções em cascata sem validação intermediária introduzem novos problemas ao resolver os anteriores. A abordagem correta é cirúrgica: uma correção, um teste, um avanço. Esse ritmo parece mais lento, mas evita a situação de entregar uma skill "corrigida" que na prática está pior do que a versão original.
Isolar o high impact #1
Foco singular
Identificar a correção mais impactante e tratá-la isoladamente, sem tocar em mais nada da skill.
Aplicar a correção e testar
Validação imediata
Testar o caso específico que a correção endereçou, E os casos adjacentes, para verificar que nenhuma regressão foi introduzida.
Registrar a mudança no CHANGELOG
Rastreabilidade
Documentar o que foi corrigido, por que, e a data. Uma linha no CHANGELOG é suficiente para manter o histórico útil.
Avançar para o próximo high impact
Progressão controlada
Repetir o ciclo até esgotar os high impacts, depois decidir se há tempo e necessidade de endereçar os medium impacts.
💡 Dica Prática
Se a correção de um high impact gerou 3 novos problemas, é sinal de que você está tentando corrigir um sintoma em vez da causa raiz. Volte e entenda por que o problema existe antes de tentar corrigir como ele se manifesta.
🎬 Exemplo de sessão completa
Para tornar o processo concreto, vamos percorrer uma sessão real de teste com sub-agentes, desde o dispatch inicial até a skill melhorada ao final. O exemplo usa a skill de reflexão de sessão como objeto de teste — uma skill simples o suficiente para ser entendida rapidamente, mas com complexidade suficiente para demonstrar os diferentes tipos de findings que os agentes produzem. Cada etapa da sessão é documentada com os inputs e outputs reais, mostrando exatamente como as decisões foram tomadas e por que. O objetivo é fornecer um template mental que você pode replicar em suas próprias sessões de melhoria.
🎬 Walkthrough: Sessão completa de teste
Etapa 1: Escolher a skill e definir o escopo (2 min)
Selecionar a skill, decidir quais agentes usar e quanto tempo está disponível. Para essa sessão: session-reflection, agente de UX friction + auditoria estrutural, 45 minutos.
Etapa 2: Dispatch do agente de UX friction (10 min)
Executar o prompt com as 4 personas. Resultado típico: 3-5 friction points, com pelo menos 1 high impact (ex: "o iniciante não entende quando usar sem ver um exemplo").
Etapa 3: Dispatch do agente estrutural (10 min)
Executar a auditoria estrutural. Resultado típico: 2-4 findings, sendo 1-2 high impact (ex: "a seção de ações de saída não tem critério claro para decidir o que vai para CLAUDE.md").
Etapa 4: Triagem e priorização (5 min)
Consolidar todos os findings em uma lista única, classificar por impacto, decidir o que corrigir agora. Para 45 minutos: focar nos 2-3 high impacts identificados.
Etapa 5: Correção iterativa (15 min)
Aplicar cada correção high impact separadamente, testando após cada uma. Documentar no CHANGELOG. Resultado: skill V2 com problemas principais resolvidos.
Etapa 6: Validação final (5 min)
Testar a skill V2 em 2-3 casos reais. Confirmar que as correções funcionam sem regressões. Publicar a nova versão. Arquivar a V1 se necessário.
💡 Dica Prática
Reserve um bloco de 45-60 minutos por semana especificamente para sessões de melhoria de skills. Skills melhoradas em blocos dedicados evoluem muito mais rápido do que skills melhoradas ad hoc. A diferença ao longo de 3 meses é notável.
✅ Resumo do Módulo
Próximo Módulo:
3.4 — 🧹 Consolidação de Skills: fundir skills sobrepostas com o Skill Creator 2.0