Communitygithub.com

Habilidade de Pesquisa

Investigação sistemática e análise de causa raiz. Use ao depurar problemas persistentes, entender sistemas complexos ou antes de tomar decisões arquiteturais.

O que é Habilidade de Pesquisa?

A Habilidade de Pesquisa é uma abordagem estruturada para investigação e depuração em profundidade, projetada para desenvolvedores que lidam com problemas recorrentes, sistemas complexos ou decisões arquiteturais. Ela é extraída de princípios documentados em sistemas como Claude Code, Cursor e Codex, e é acionada quando um mesmo bug persiste após duas tentativas de correção. A habilidade enfatiza a pesquisa antes da iteração cega, o uso de fontes primárias (documentação oficial, código fonte) em vez de suposições ou IA não verificada, a reprodução local de problemas, e a inspeção de dados reais. Ela fornece um fluxo de trabalho sistemático que inclui observação, geração de hipóteses, teste, validação e reflexão, além de checklists específicos para investigação de limites de execução em sistemas distribuídos e análises arquiteturais. A habilidade é útil para economizar tempo e evitar ciclos de deploy falhos, promovendo uma abordagem metódica e baseada em evidências.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/research-awannaphasch2016-jousef-landing

Perguntar na sua IA favorita

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

Documentação

O que Habilidade de Pesquisa faz?

Stack Tecnológica: AWS CLI, Git, ripgrep, jq, curl, browser DevTools

Fonte: Extraído dos princípios de investigação e padrões de depuração do CLAUDE.md.


Quando Usar Esta Habilidade

Use a habilidade de pesquisa quando:

  • ✓ O mesmo bug persiste após 2+ tentativas de correção
  • ✓ Precisar entender uma base de código desconhecida
  • ✓ Estiver investigando incidentes de produção
  • ✓ Estiver tomando decisões arquiteturais
  • ✓ Estiver depurando interações complexas de sistemas
  • ✓ Estiver aprendendo uma nova tecnologia/biblioteca

NÃO use esta habilidade para:

  • ✗ Primeira tentativa de correção (tente a solução óbvia primeiro)
  • ✗ Problemas bem compreendidos (apenas corrija)
  • ✗ Incidentes críticos de tempo (corrija primeiro, investigue depois)

Árvore de Decisão Rápida para Pesquisa

Qual é o problema?
├─ Está vendo este problema pela primeira vez?
│  ├─ SIM → Tente a correção óbvia (iteração)
│  └─ NÃO → Mesmo bug após 2 tentativas? → PESQUISE
│
├─ Incidente de produção?
│  ├─ Afetando usuários AGORA? → Reversão/hotfix primeiro, pesquise depois
│  └─ Análise pós-incidente? → Pesquisa aprofundada
│
├─ Precisa entender a base de código?
│  ├─ Função/módulo específico? → Leia o código + testes
│  ├─ Arquitetura do sistema? → Trace o fluxo de requisições
│  └─ Contexto histórico? → Git blame + histórico de commits
│
├─ Decisão tecnológica?
│  ├─ Leia a documentação oficial (não posts de blog)
│  ├─ Compare alternativas (trade-offs)
│  ├─ Faça um protótipo com caso de uso real
│  └─ Documente a decisão (ADR)
│
└─ Integração com API/Biblioteca?
   ├─ Leia os requisitos de tipo (não assuma)
   ├─ Verifique a compatibilidade de versão
   ├─ Teste um exemplo mínimo
   └─ Verifique com dados reais

Padrão de Loop: Meta-Loop → Sensível a Inicialização

Gatilho de Escalação:

  • /reflect revela: "Tentei 3 correções, todas falharam com o mesmo erro"
  • Saída de /trace idêntica entre tentativas
  • Padrão: Preso em loop de repetição (a execução muda, o resultado não)
  • Ação: Use /hypothesis para questionar suposições (mude para sensível a inicialização)

Ferramentas Utilizadas:

  • /observe - Perceba o comportamento do sistema (o que está falhando)
  • /hypothesis - Gere explicações alternativas (por que pode estar falhando de forma diferente do que penso?)
  • /research - Teste hipóteses sistematicamente
  • /validate - Verifique se o novo entendimento está correto
  • /reflect - Sintetize aprendizados após a investigação

Por que Isso Funciona: A habilidade de pesquisa se encaixa naturalmente no loop sensível a inicialização—você está questionando suposições, não apenas corrigindo a execução.

Consulte Thinking Process Architecture - Feedback Loops para uma visão geral estrutural.


Princípios Centrais de Pesquisa

Princípio 1: Pesquise Antes de Iterar

Do CLAUDE.md:

"Quando o mesmo bug persiste após 2 tentativas de correção, PARE de iterar e COMECE a pesquisar. Invista 30-60 minutos entendendo a causa raiz em vez de implantar mais palpites."

Por que Isso Importa:

  • ❌ Iteração: Feedback rápido, mas desperdiçador após 2+ tentativas fracassadas
  • ✅ Pesquisa: Custo inicial, evita 3+ ciclos de deploy fracassados

Padrão:

Tentativa 1: Hipótese + Deploy (8 minutos)
  ↓ Falhou
Tentativa 2: Hipótese diferente + Deploy (8 minutos)
  ↓ Falhou
Tentativa 3: ❌ PARE - Não implante outro palpite

MUDE PARA MODO DE PESQUISA:
  - Leia especificações/documentação (15 minutos)
  - Inspecione dados reais (10 minutos)
  - Reproduza localmente (20 minutos)
  - Identifique a causa raiz (15 minutos)
  ↓ Total: 60 minutos de pesquisa

Tentativa 3 (com causa raiz): Implante a correção (8 minutos)
  ✅ Sucesso

Tempo total: 76 minutos (vs 120+ minutos com iteração cega)

Princípio 2: Leia Fontes Primárias

Hierarquia de Qualidade da Informação:

Tipo de FonteConfiabilidadeQuando Usar
Documentação OficialMais AltaPrimeiro passo para comportamento de API, requisitos de tipo
Código FonteMuito AltaQuando a documentação não é clara ou está incompleta
Issues do GitHubAltaPara bugs conhecidos, casos extremos, workarounds
Stack OverflowMédiaPara problemas comuns, após ler a documentação
Posts de BlogBaixaPara conceitos gerais, não detalhes de implementação
ChatGPT/IAMais BaixaApenas como ponto de partida, sempre verifique

Exemplo: Integração de Sistema de Tipos

# ❌ NÃO FAÇA: Pergunte ao ChatGPT "O PyMySQL aceita dicionários para colunas JSON?"
# ChatGPT pode alucinar ou dar uma resposta desatualizada

# ✅ FAÇA: Leia a documentação do PyMySQL
open https://pymysql.readthedocs.io/en/latest/

# ✅ FAÇA: Teste com um exemplo mínimo
python3 << 'EOF'
import pymysql
import json

# Teste: O PyMySQL aceita dict para coluna JSON?
data = {'key': 'value'}

try:
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    print("✅ Dict aceito")
except TypeError as e:
    print(f"❌ Dict rejeitado: {e}")
    # Tente string JSON em vez disso
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("✅ String JSON aceita")
EOF

Princípio 3: Reproduza Localmente

Antes de implantar correções, reproduza o problema localmente.

Benefícios:

  • ✅ Iteração rápida (segundos vs minutos)
  • ✅ Pode depurar com breakpoints
  • ✅ Sem custos de nuvem
  • ✅ Pode testar casos extremos facilmente

Padrão:

# Passo 1: Extraia caso mínimo de falha
# Em vez de testar toda a função Lambda...

# ❌ RUIM: Implante no AWS, verifique logs, repita
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Espere 30 segundos pelos logs do CloudWatch...

# ✅ BOM: Reproduza localmente
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher

# Exatamente o mesmo código do Lambda
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result)  # Feedback imediato
EOF

Princípio 4: Inspecione Dados Reais

Não assuma a forma dos dados—verifique com exemplos reais.

Erros Comuns:

  • Assumir que a API retorna dict (pode retornar lista)
  • Assumir que o campo existe (pode ser nulo/ausente)
  • Assumir o tipo (pode ser string, não int)

Padrão:

# ❌ NÃO FAÇA: Assuma
# "A API retorna uma lista de tickers"

# ✅ FAÇA: Verifique
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json

# Inspecione a estrutura:
# - É uma lista ou dict?
# - Quais campos estão presentes?
# - Quais são os tipos?
# - Há valores nulos?
# - Há estruturas aninhadas?

Exemplo: Investigação de Esquema Aurora

# Conecte ao Aurora via túnel SSM
aws ssm start-session \
  --target i-1234567890abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'

# Inspecione o esquema real (não assuma)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;

-- Verifique os tipos de dados reais
SELECT
  symbol,
  report_json,
  typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G

-- Verifique se há valores nulos
SELECT COUNT(*) as total,
       SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL

Fluxo de Trabalho de Pesquisa

Consulte WORKFLOW.md para um processo de pesquisa detalhado passo a passo.


Lista de Verificação de Investigação

Consulte INVESTIGATION-CHECKLIST.md para uma lista de verificação sistemática de depuração.


Verificação de Limites

Quando: Investigando sistemas distribuídos (Lambda, Aurora, S3, SQS, Step Functions)

Problema: O código parece correto, mas falha em produção devido a limites de execução não verificados

Perguntas críticas:

  • ONDE este código é executado? (Lambda, EC2, local?)
  • QUAL ambiente ele requer? (variáveis de ambiente, rede, permissões?)
  • QUAIS sistemas externos ele chama? (esquema Aurora, bucket S3, formato de API?)
  • QUAIS são as propriedades da entidade? (timeout/memória do Lambda, limites de conexão do Aurora, uso pretendido)
  • COMO verifico o contrato? (config Terraform, SHOW COLUMNS, testar acesso?)

Cinco camadas de correção:

  1. Sintática: O código compila (sintaxe Python válida)
  2. Semântica: O código faz o que afirma (lógica correta)
  3. Limite: O código pode alcançar o que precisa (rede, permissões)
  4. Configuração: A configuração da entidade corresponde aos requisitos do código (timeout, memória)
  5. Intencional: O uso corresponde ao propósito projetado (Lambda síncrona não para trabalho assíncrono)

Quando aplicar:

  • Bugs "código parece correto, mas não funciona"
  • Fluxos de trabalho com múltiplos serviços (Lambda → Aurora → S3)
  • Após 2 tentativas de deploy fracassadas (problemas de infraestrutura)
  • Antes de concluir "o código está correto" (verifique o contexto de execução)

Fluxo de trabalho de verificação:

1. Identifique os limites de execução (código → runtime, código → banco de dados, serviço → serviço)
2. Identifique as entidades físicas (QUAL Lambda, QUAL Aurora, QUAL bucket S3)
3. Verifique se a configuração corresponde aos requisitos (timeout, memória, concorrência)
4. Verifique se a intenção corresponde ao uso (Lambda assíncrona não para API síncrona)
5. Avance pelas camadas de evidência (código → config → runtime → verdade fundamental)

Integração com o fluxo de trabalho de pesquisa:

  • Fase 1 (Observar): Perceba falhas relacionadas a limites (timeout, permissão negada, incompatibilidade de esquema)
  • Fase 2 (Hipótese): Identifique qual limite pode estar sendo violado
  • Fase 3 (Pesquisar): Aplique a lista de verificação de limites sistematicamente
  • Fase 4 (Validar): Verifique o contrato através da verdade fundamental (teste a execução real)

Veja: Execution Boundary Checklist para um fluxo de trabalho de verificação abrangente

Princípios relacionados:

  • Princípio #20 (Disciplina de Limites de Execução) - CLAUDE.md
  • Princípio #2 (Fortalecimento Progressivo de Evidências) - Verifique através de todas as camadas
  • Princípio #15 (Contrato Infraestrutura-Aplicação) - Sincronize código e infraestrutura

Investigações Arquiteturais

Quando: Escolhendo entre tecnologias, padrões ou abordagens arquiteturais

Problema: Comparações "X vs Y" geram respostas vagas do tipo "depende" sem análise estruturada

Solução: Aplique o framework de análise de relacionamento baseado em OWL para comparação sistemática

Passos:

  1. Defina os conceitos sendo comparados

    • O que é X? (definição, localização, propósito, exemplos)
    • O que é Y? (definição, localização, propósito, exemplos)
  2. Aplique os 4 tipos de relacionamento:

    • Parte-Todo: Um é parte do outro, ou são pares?
    • Complemento: Eles lidam com preocupações não sobrepostas que funcionam juntas?
    • Substituição: Um pode substituir o outro? Sob quais condições?
    • Composição: Eles podem ser em camadas/compostos em um sistema de múltiplas camadas?
  3. Documente com exemplos concretos

    • Forneça cenários reais, não teoria abstrata
    • Inclua análise de trade-off (o que você ganha vs perde)
  4. Faça uma recomendação baseada na análise

    • Fundamentada na análise de relacionamento, não na intuição
    • Inclua anti-padrões a serem evitados

Veja: Relationship Analysis Guide para uma metodologia abrangente

Exemplos de Casos de Uso:

  • "Devo usar Redis ou DynamoDB para cache?" → Aplique análise de substituição e composição
  • "Como CDN e cache de aplicação se relacionam?" → Aplique análise de complemento e composição
  • "Microsserviços vs Monólito?" → Aplique análise parte-todo e trade-off

Cenários Comuns de Pesquisa

Cenário 1: Incompatibilidade de Sistema de Tipos

Sintoma: Mesmo erro após 2 tentativas, falha silenciosa

Passos de Pesquisa:

  1. Leia a Documentação do Sistema Alvo

    # Docs do PyMySQL
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # Procure por: Quais tipos o execute() aceita?
    
  2. Teste um Exemplo Mínimo

    import pymysql
    import json
    
    # Teste a hipótese: Dict vs String JSON
    data = {'key': 'value'}
    
    # Teste 1: Dict
    try:
        cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    except TypeError as e:
        print(f"Dict falhou: {e}")
    
    # Teste 2: String JSON
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("String JSON bem-sucedida")
    
  3. Aplique a Correção com Confiança

    # Agora SABEMOS que json.dumps() é necessário
    def store_report(symbol: str, report_json: dict):
        cursor.execute(
            "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)",
            (symbol, json.dumps(report_json))  # Converta para string
        )
    

Cenário 2: Incidente de Produção

Sintoma: Usuários relatando erros, dashboard mostra pico

Passos de Pesquisa:

  1. Triagem (< 5 minutos)

    # Verifique a contagem de erros
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $(($(date +%s) - 600))000 \
      --filter-pattern "ERROR" \
      --query 'length(events)'
    
    # Verifique quando começou
    aws cloudwatch get-metric-statistics \
      --namespace AWS/Lambda \
      --metric-name Errors \
      --dimensions Name=FunctionName,Value=worker \
      --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \
      --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \
      --period 60 \
      --statistics Sum
    
  2. Mitigação Imediata (< 10 minutos)

    # Reverta para a versão anterior
    CURRENT=$(aws lambda get-alias --function-name worker --name live \
      --query 'FunctionVersion' --output text)
    
    PREVIOUS=$((CURRENT - 1))
    
    aws lambda update-alias \
      --function-name worker \
      --name live \
      --function-version $PREVIOUS
    
    echo "Revertido de v$CURRENT para v$PREVIOUS"
    
  3. Análise Pós-Incidente (30-60 minutos)

    # Colete evidências
    mkdir incident-$(date +%Y%m%d-%H%M%S)
    cd incident-*
    
    # Exporte logs de erro
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $INCIDENT_START \
      --end-time $INCIDENT_END \
      --filter-pattern "ERROR" > errors.json
    
    # Exporte métricas
    aws cloudwatch get-metric-statistics ... > metrics.json
    
    # Obtenha diff do deploy
    git diff v$PREVIOUS v$CURRENT > deployment.diff
    
    # Analise (análise de causa raiz)
    # - O que mudou?
    # - O que falhou?
    # - Por que falhou?
    # - Como prevenir?
    

Cenário 3: Base de Código Desconhecida

Tarefa: Adicionar funcionalidade a um módulo que você nunca viu

Passos de Pesquisa:

  1. Encontre o Ponto de Entrada
    # Pesquise pela função main
    rg "def main"
    

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Habilidades Relacionadas