/pesquisar-primeiro — Pesquise Antes de Codificar
Sistematiza o fluxo de trabalho "pesquise soluções existentes antes de implementar".
Gatilho
Use esta habilidade quando:
- Iniciar um novo recurso que provavelmente já tem soluções existentes
- Adicionar uma dependência ou integração
- O usuário pedir "adicione funcionalidade X" e você estiver prestes a escrever código
- Antes de criar um novo utilitário, auxiliar ou abstração
Fluxo de Trabalho
┌─────────────────────────────────────────────┐
│ 0. PRÉ-VOO DE DISPONIBILIDADE DE │
│ FERRAMENTAS │
│ Verifique os canais de busca antes de │
│ confiar neles; relate canais ignorados │
│ honestamente │
├─────────────────────────────────────────────┤
│ 1. ANÁLISE DE NECESSIDADE │
│ Defina qual funcionalidade é necessária │
│ Identifique restrições de linguagem/ │
│ framework │
├─────────────────────────────────────────────┤
│ 2. BUSCA PARALELA (agente de pesquisa) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ Skills │ │ Web │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. AVALIAÇÃO │
│ Pontue candidatos (funcionalidade, │
│ manutenção, comunidade, docs, licença, │
│ dependências) │
├─────────────────────────────────────────────┤
│ 4. DECISÃO │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Adotar │ │ Estender│ │ Criar │ │
│ │ tal qual│ │ /Encap. │ │ Custom.│ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. IMPLEMENTAÇÃO │
│ Instalar pacote / Configurar MCP / │
│ Escrever código personalizado mínimo │
└─────────────────────────────────────────────┘
Matriz de Decisão
| Sinal | Ação |
|---|---|
| Correspondência exata, bem mantida, MIT/Apache | Adotar — instalar e usar diretamente |
| Correspondência parcial, boa base | Estender — instalar + escrever invólucro fino |
| Múltiplas correspondências fracas | Compor — combinar 2-3 pacotes pequenos |
| Nada adequado encontrado | Criar — escrever customizado, mas informado pela pesquisa |
Como Usar
Passo 0: Pré-voo de Disponibilidade de Ferramentas
Isto é orientação para o agente, não um script de configuração executável. Verifique apenas os canais que são relevantes para a tarefa e o projeto à sua frente.
| Canal | Verificar | Se ausente |
|---|---|---|
| Busca no repositório | rg --files e consultas rg direcionadas | Declare que apenas arquivos visíveis foram inspecionados |
| Registro de pacotes | npm --version, python -m pip --version, ou gerenciador de pacotes do projeto | Use busca na web/documentação e evite afirmar cobertura de registro |
| GitHub CLI | gh auth status | Use apenas web pública ou histórico git local |
| Ferramentas MCP/docs | Lista de ferramentas disponíveis ou configuração MCP local | Recorra à documentação oficial/busca na web |
| Diretório de habilidades | ls ~/.claude/skills ~/.codex/skills onde aplicável | Diga que nenhum catálogo local de habilidades estava disponível |
Modo Rápido (em linha)
Antes de escrever um utilitário ou adicionar funcionalidade, percorra mentalmente:
- Isso já existe no repositório? → primeiro faça
rgnos módulos/testes relevantes - Este é um problema comum? → Busque no npm/PyPI
- Existe um MCP para isso? → Verifique
~/.claude/settings.jsone busque - Existe uma habilidade para isso? → Verifique
~/.claude/skills/ - Existe uma implementação/modelo no GitHub? → Execute busca de código no GitHub por OSS mantido antes de escrever código novo do zero
Modo Completo (agente)
Para funcionalidades não triviais, lance o agente de pesquisa:
Agent(subagent_type="general-purpose", prompt="
Pesquise ferramentas existentes para: [DESCRIÇÃO]
Linguagem/framework: [LINGUAGEM]
Restrições: [QUALQUER]
Busque: npm/PyPI, servidores MCP, habilidades Claude Code, GitHub
Retorne: Comparação estruturada com recomendação
")
Documentações mais antigas do Claude Code podem chamar isso de Task(...); use o nome da ferramenta
agent/subagent atual exposta pelo harness ativo.
Atalhos de Busca por Categoria
Ferramentas de Desenvolvimento
- Linting →
eslint,ruff,textlint,markdownlint - Formatação →
prettier,black,gofmt - Testes →
jest,pytest,go test - Pré-commit →
husky,lint-staged,pre-commit
Integração AI/LLM
- SDK Claude → Context7 para as documentações mais recentes
- Gerenciamento de prompts → Verifique servidores MCP
- Processamento de documentos →
unstructured,pdfplumber,mammoth
Dados e APIs
- Clientes HTTP →
httpx(Python),ky/undici(Node) - Validação →
zod(TS),pydantic(Python) - Banco de dados → Verifique servidores MCP primeiro
Conteúdo e Publicação
- Processamento Markdown →
remark,unified,markdown-it - Otimização de imagens →
sharp,imagemin
Pontos de Integração
Com agente planejador
O planejador deve invocar o pesquisador antes da Fase 1 (Revisão de Arquitetura):
- Pesquisador identifica ferramentas disponíveis
- Planejador as incorpora no plano de implementação
- Evita "reinventar a roda" no plano
Com agente arquiteto
O arquiteto deve consultar o pesquisador para:
- Decisões de pilha tecnológica
- Descoberta de padrões de integração
- Arquiteturas de referência existentes
Com habilidade de recuperação iterativa
Combine para descoberta progressiva:
- Ciclo 1: Busca ampla (npm, PyPI, MCP)
- Ciclo 2: Avalie os principais candidatos em detalhes
- Ciclo 3: Teste compatibilidade com restrições do projeto
Exemplos
Exemplo 1: "Adicionar verificação de links quebrados"
Necessidade: Verificar arquivos markdown em busca de links quebrados
Busca: npm "markdown dead link checker"
Encontrado: textlint-rule-no-dead-link (pontuação: 9/10)
Ação: ADOTAR — npm install textlint-rule-no-dead-link
Resultado: Zero código personalizado, solução testada em batalha
Exemplo 2: "Adicionar wrapper de cliente HTTP"
Necessidade: Cliente HTTP resiliente com retentativas e tratamento de timeout
Busca: npm "http client retry", PyPI "httpx retry"
Encontrado: got (Node) com plugin de retry, httpx (Python) com retry embutido
Ação: ADOTAR — usar got/httpx diretamente com configuração de retry
Resultado: Zero código personalizado, bibliotecas testadas em produção
Exemplo 3: "Adicionar linter de arquivos de configuração"
Necessidade: Validar arquivos de configuração do projeto contra um esquema
Busca: npm "config linter schema", "json schema validator cli"
Encontrado: ajv-cli (pontuação: 8/10)
Ação: ADOTAR + ESTENDER — instalar ajv-cli, escrever esquema específico do projeto
Resultado: 1 pacote + 1 arquivo de esquema, nenhuma lógica de validação personalizada
Anti-Padrões
- Pular para o código: Escrever um utilitário sem verificar se um existe
- Ignorar MCP: Não verificar se um servidor MCP já fornece a capacidade
- Ignorar silenciosamente: Relatar "nada encontrado" quando um canal de busca estava indisponível
- Personalizar em excesso: Encapsular uma biblioteca tão pesadamente que ela perde seus benefícios
- Inchaço de dependências: Instalar um pacote enorme para um pequeno recurso