Communitygithub.com

shimo4228/pesquisar-primeiro

Skill para Claude Code: força agentes a pesquisarem soluções existentes antes de construir — reduz reinvenção

O que é pesquisar-primeiro?

Esta skill impõe uma disciplina de pesquisa antes da implementação para qualquer feature, utilidade, integração ou escolha de biblioteca. Ela não se preocupa com o mecanismo de busca (subagentes paralelos, consultas a registros, documentação ao vivo), mas sim com os princípios que permanecem: articular o requisito de forma clara antes de pesquisar, pesquisar por prioridade de fonte e encerrar com um veredito registrado. A skill suporta qualquer plataforma de agente (Claude Code, Cursor, Codex, etc.) e define três etapas obrigatórias: articular a necessidade em texto legível ao usuário, pesquisar em ordem de fontes (repositório local, registros de pacotes, servidores MCP, habilidades instaladas, OSS mantido) e decidir entre Adotar, Estender, Compor ou Construir com um veredito baseado em evidências. Ela também oferece um Modo Rápido (inline) e um Modo Completo (delegado a subagentes), além de tratar explicitamente o caso de o usuário pedir para pular a pesquisa, registrando esse desvio como um veredito para manter a auditabilidade.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add shimo4228/search-first

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

/pesquisar-primeiro — Pesquise Antes de Codificar

Antes de escrever uma nova funcionalidade, utilidade, integração ou escolher uma biblioteca, pesquise uma solução existente primeiro. O melhor código é o código que você não precisa escrever.

Esta skill é disciplina, não mecanismo. O como da pesquisa — subagentes paralelos, consulta a documentação ao vivo, consultas a registros — pertence ao seu ambiente de agente e está sempre mudando. O que esta skill fixa é a parte que sobrevive a essas mudanças: articule antes de pesquisar, pesquise por prioridade de fonte e termine com um veredito registrado. Lidere com a disciplina; delegue o mecanismo.

Etapa 0 — Articule o requisito (obrigatório, texto visível ao usuário)

Antes de qualquer chamada de ferramenta ou subagente, escreva 2–3 frases de texto simples do assistente (não enterrado dentro de argumentos de ferramenta) declarando:

  • O que funcionalidade é necessária — concretamente, não "suporte a X"
  • Linguagem / framework que a implementação usará
  • Restrições — dependências existentes, limites de desempenho, requisitos de licença

Por que: isso externaliza a consulta de pesquisa para que o usuário possa redirecionar antes de você gastar esforço, e deixa um registro auditável. Uma chamada de subagente cujos args carregam o requisito não satisfaz esta etapa — o usuário lê o texto do chat, não os argumentos da ferramenta. Emita a articulação como texto primeiro, depois chame ferramentas cujos argumentos podem espelhá-la.

Etapa 1 — Pesquise por prioridade de fonte

Verifique nestas ordens; pare cedo quando encontrar uma correspondência forte:

  1. Este repositório — rg / grep nos módulos e testes relevantes. A coisa pode já existir aqui.
  2. Registros de pacotes — npm / PyPI / crates / módulos Go para a linguagem em uso.
  3. Servidores MCP — servidores já configurados primeiro, depois o registro. A capacidade pode já estar conectada.
  4. Skills / agentes / ferramentas instalados — seu ambiente pode já carregá-la.
  5. OSS mantido / templates — pesquise no GitHub por código antes de escrever código novo.

Consulte a documentação ao vivo no momento da decisão (ex.: context7, ou o próprio registro) em vez de confiar em fatos de pacotes lembrados — as recomendações envelhecem.

Etapa 2 — Decida e registre um Veredito

Avalie os candidatos holisticamente: adequação funcional, manutenção (último commit, velocidade de resposta a issues), comunidade, documentação, licença, pegada de dependências. Descreva pontos fortes e fracos em prosa. Não atribua pontuações numéricas (8/10), notas de letras ou tabelas de pontos ponderados — elas fabricam precisão falsa; um veredito baseado em evidências é a saída honesta.

VereditoQuandoAção
AdotarCorrespondência exata, bem mantida, licença permissivaInstalar e usar diretamente
EstenderBoa base, adequação parcialInstalar + wrapper/configuração fina
ComporVárias correspondências fracasCombinar 2–3 pacotes pequenos
ConstruirNada adequadoEscrever personalizado — mas informado pelo que encontrou

Termine cada passagem com uma linha de veredito reconhecível — esta linha é o entregável:

Veredito: <Adotar|Estender|Compor|Construir> — <pacote(s) ou "personalizado"> — <motivo baseado em evidências>

Uma pesquisa sem linha de veredito é uma passagem incompleta: você fez o trabalho, mas não deixou nenhuma decisão que o usuário (ou o próximo passo) possa usar — a falha mais comum deste fluxo de trabalho. Apoie o motivo com evidências (estrelas, data do último commit, a correspondência de funcionalidade específica), nunca adjetivos ("parece bom", "popular").

Modo Rápido vs Modo Completo

  • Modo Rápido (inline) — para uma necessidade única e óbvia: execute as Etapas 0–2 você mesmo com algumas pesquisas e declare o veredito.
  • Modo Completo (delegar) — para necessidades não triviais: após a Etapa 0, passe a varredura para um subagente de pesquisa (o que seu ambiente fornecer para descoberta de soluções). Espelhe a articulação em seu prompt e peça que ele retorne candidatos mais um veredito no formato acima. Reserve pesquisas multi-fonte pesadas para perguntas genuinamente difíceis — encontrar uma biblioteca é mais leve que um relatório de pesquisa.

Quando o usuário disser "pule a pesquisa"

Se o usuário lhe disser para pular a pesquisa ("apenas implemente", "sem tempo", "use qualquer coisa"), ainda registre a decisão como uma linha de veredito antes de implementar — pular a pesquisa é, em si, uma decisão, então recebe um veredito como qualquer outra passagem (isso mantém a escolha auditável e a janela de correção de curso aberta):

Pulando pesquisa a seu pedido — não verifiquei se existe uma biblioteca existente para X. Veredito: <Adotar|Construir> — <escolha provisória ou "personalizado"> — escolhido sem pesquisa a seu pedido; diga a palavra para uma verificação de 60 segundos.

Por que: o usuário pode não saber que uma solução já existe; um pulo silencioso remove sua chance de corrigir o curso. Após a linha de veredito, prossiga sem pesquisar — não use isso como uma porta dos fundos para fazer pesquisa completa de qualquer maneira.

Anti-Padrões

  • Pular para o código — escrever uma utilidade sem verificar se uma já existe.
  • Ignorar MCP / capacidade instalada — reconstruir o que já está conectado.
  • Personalização excessiva — encapsular uma biblioteca tão fortemente que seu benefício se perde.
  • Inchaço de dependências — instalar um pacote enorme para uma funcionalidade pequena.
  • Pesquisa sem veredito — fazer o trabalho braçal mas nunca registrar uma decisão.

Exemplos (ilustrativos — verifique pacotes ao vivo)

Estes mostram como um veredito se parece; não são endossos de pacotes atuais. Re-pesquise antes de confiar em qualquer pacote específico.

  • Verificação de links quebrados → uma regra de verificação de links mantida, com licença permissiva, cobrindo todos os tipos de link → Veredito: Adotar — textlint-rule-no-dead-link — manutenção ativa, MIT, cobertura completa
  • Cross-posting no Qiita → apenas wrappers parciais não mantidos existem → Veredito: Construir — personalizado — nenhuma solução completa mantida; reutilizar a API da plataforma via um cliente HTTP
  • Consistência de terminologia JP → um verificador baseado em dicionário que precisa de uma configuração de projeto → Veredito: Estender — textlint-rule-prh — instalar + um dicionário de projeto

Habilidades Relacionadas