finding-duplicate-functions

Visão geral da skill finding-duplicate-functions

A skill finding-duplicate-functions ajuda você a identificar funções que fazem a mesma coisa, mas aparecem com nomes ou implementações diferentes. Ela é mais útil ao revisar codebases gerados por LLMs ou em rápida expansão, onde duplicação semântica acumula mais depressa do que duplicação por copy-paste. Se você procura finding-duplicate-functions for Code Review, esta skill é voltada para decisões de consolidação, não para detalhes de estilo.

Para que esta skill serve

Esta skill finding-duplicate-functions foi criada para encontrar casos de “mesma intenção, código diferente”: helpers que se sobrepõem, utilitários recriados do zero ou lógicas quase equivalentes espalhadas por vários arquivos. Ela é especialmente relevante antes de refatorações, durante limpezas de código ou depois que ferramentas de duplicação sintática como jscpd já trataram cópias exatas.

Quem deve instalar

Instale a skill finding-duplicate-functions se você revisa repositórios JavaScript ou TypeScript com muitos utilitários pequenos, arquivos gerados ou vários colaboradores. Ela é uma ótima opção quando você quer um método repetível para decidir se funções devem ser unificadas, mantidas separadas ou investigadas com mais profundidade.

O que a torna diferente

O diferencial principal é o fluxo em duas fases: primeiro extrair as funções, depois agrupá-las por intenção com análise de LLM. Isso significa que a skill foi pensada para reduzir a incerteza sobre duplicatas semânticas, e não apenas detectar linhas iguais. O ganho prático é chegar mais rápido de “este código parece redundante” a um plano de consolidação que pode ser revisado.

Como usar a skill finding-duplicate-functions

Instalar e localizar o fluxo de trabalho

Use o caminho de instalação do repositório no diretório de skills: npx skills add obra/superpowers-lab --skill finding-duplicate-functions. Depois da instalação, comece por skills/finding-duplicate-functions/SKILL.md e em seguida leia os scripts auxiliares em skills/finding-duplicate-functions/scripts/, porque eles definem a sequência real da análise. Para um guia de finding-duplicate-functions, esses scripts importam mais do que o resumo em texto.

Que entrada a skill precisa

A skill funciona melhor quando você fornece um diretório de origem e um objetivo concreto de revisão. Bons inputs mencionam a área de código, o motivo da análise e quaisquer exclusões. Por exemplo: “Varra packages/api/src em busca de helpers de validação duplicados antes de unificar os fluxos de auth; ignore arquivos de teste e reporte apenas candidatos com alta confiança.” Isso é melhor do que “encontre duplicados” porque define escopo, intenção e expectativa de saída.

Leia estes arquivos primeiro

Priorize scripts/extract-functions.sh, scripts/categorize-prompt.md, scripts/find-duplicates-prompt.md, scripts/prepare-category-analysis.sh e scripts/generate-report.sh. Esses arquivos mostram o padrão exato de uso da skill finding-duplicate-functions: extrair um catálogo, categorizar funções, dividir por categoria, executar comparação semântica e então gerar um relatório. Se for ler só um arquivo, leia SKILL.md junto com scripts/extract-functions.sh para entender a forma da entrada e as exclusões.

Dicas de fluxo que mudam o resultado

Trate a etapa de categorização como um filtro, não como um detalhe secundário. A skill fica mais precisa quando as categorias são coerentes e têm funções suficientes para comparação, porque a detecção de duplicatas é executada por categoria. Excluir testes por padrão normalmente faz sentido para limpeza de código de produção, mas inclua-os se o seu objetivo for revisar utilitários de teste compartilhados ou helpers de fixtures. Use o relatório gerado como uma shortlist para revisão humana, e não como um plano automático de refatoração.

Perguntas frequentes sobre a skill finding-duplicate-functions

Isso é melhor do que um prompt normal?

Sim, quando você quer um fluxo reproduzível para encontrar intenção duplicada em funções, em vez de uma resposta improvisada de brainstorming. Um prompt normal pode falhar em controle de escopo, seleção de arquivos e limites de confiança. A skill finding-duplicate-functions oferece um fluxo e uma estrutura de saída mais fáceis de repetir em code review.

Ela substitui ferramentas de duplicação sintática?

Não. Ela complementa essas ferramentas. Ferramentas sintáticas pegam código copiado; esta skill encontra funções semanticamente parecidas mesmo quando a implementação é diferente. Se sua codebase já tem problemas de cópia exata, trate isso primeiro para que a etapa semântica continue focada.

Ela é amigável para iniciantes?

Sim, desde que você consiga apontá-la para uma árvore de origem e descrever o que deve ser revisado. O principal que iniciantes precisam entender é que a detecção de duplicatas é baseada em categorias e depende de bons limites de entrada. Se houver dúvida, comece com um pacote ou uma área funcional, em vez de o repositório inteiro.

Quando eu não devo usar?

Não use quando você precisa de orientação arquitetural ampla, correção pontual de bug ou um resumo geral da codebase. Também é uma opção ruim se seu repositório for majoritariamente em código que não seja JS/TS, porque o script de extração é orientado a padrões de funções em JavaScript e TypeScript. Se seu objetivo for apenas encontrar cópias exatas, um detector de copy-paste mais simples já basta.

Como melhorar a skill finding-duplicate-functions

Delimite melhor o escopo e deixe o alvo da decisão claro

O maior ganho de qualidade vem de reduzir a superfície de revisão e declarar qual ação você quer tomar. Em vez de pedir todas as duplicatas, peça “pontos candidatos a consolidação em src/utils, com viés para merges de alta confiança”. Isso melhora o uso da skill finding-duplicate-functions porque o modelo consegue comparar funções que realmente competem entre si.

Forneça os casos de contraste certos

Se você já suspeita de alguns pares, inclua-os no prompt como possíveis correspondências e diga por que eles podem ser diferentes. Exemplo: “Compare parseUserInput, normalizeInput e sanitizeInput; eles podem se sobrepor, mas um deles trata escape de HTML.” Isso ajuda a skill a distinguir duplicatas reais de helpers vizinhos que só compartilham vocabulário.

Fique atento aos modos de falha mais comuns

O principal modo de falha é o agrupamento excessivo: funções com nomes parecidos, mas regras de negócio diferentes, acabam unificadas agressivamente demais. O segundo é o subagrupamento: wrappers pequenos são tratados como distintos quando só mudam na forma dos parâmetros ou na nomenclatura. Em ambos os casos, adicione contexto sobre entradas, saídas e comportamento esperado para que a revisão julgue intenção, e não só semelhança superficial.

Itere do relatório para a refatoração

Depois da primeira execução, use o relatório para escolher uma categoria e verificar manualmente os grupos de maior confiança no código-fonte. Se um grupo estiver em zona cinzenta, restrinja a categoria ou rode novamente com linhas de contexto melhores e um limite de recomendação mais claro. O melhor guia de finding-duplicate-functions é iterativo: use a saída inicial para refinar o escopo e depois rode novamente no próximo recorte da codebase.