/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:
- Este repositório —
rg/ grep nos módulos e testes relevantes. A coisa pode já existir aqui. - Registros de pacotes — npm / PyPI / crates / módulos Go para a linguagem em uso.
- Servidores MCP — servidores já configurados primeiro, depois o registro. A capacidade pode já estar conectada.
- Skills / agentes / ferramentas instalados — seu ambiente pode já carregá-la.
- 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.
| Veredito | Quando | Ação |
|---|---|---|
| Adotar | Correspondência exata, bem mantida, licença permissiva | Instalar e usar diretamente |
| Estender | Boa base, adequação parcial | Instalar + wrapper/configuração fina |
| Compor | Várias correspondências fracas | Combinar 2–3 pacotes pequenos |
| Construir | Nada adequado | Escrever 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