Habilidade de Pesquisa
Stack Tecnológico: AWS CLI, Git, ripgrep, jq, curl, DevTools do navegador
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 um código desconhecido
- ✓ Estiver investigando incidentes de produção
- ✓ Estiver tomando decisões arquiteturais
- ✓ Depurando interações complexas de sistemas
- ✓ 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 o problema pela primeira vez?
│ ├─ SIM → Tente correção óbvia (iteração)
│ └─ NÃO → Mesmo bug após 2 tentativas? → PESQUISA
│
├─ Incidente de produção?
│ ├─ Afetando usuários AGORA? → Reversão/hotfix primeiro, pesquise depois
│ └─ Análise pós-incidente? → Pesquisa profunda
│
├─ Precisa entender o código?
│ ├─ Função/módulo específico? → Leia código + testes
│ ├─ Arquitetura do sistema? → Rastreie fluxo de requisição
│ └─ Contexto histórico? → Git blame + histórico de commits
│
├─ Decisão tecnológica?
│ ├─ Leia documentação oficial (não posts de blog)
│ ├─ Compare alternativas (trade-offs)
│ ├─ Prototipe com caso de uso real
│ └─ Documente a decisão (ADR)
│
└─ Integração de API/Biblioteca?
├─ Leia os requisitos de tipo (não assuma)
├─ Verifique compatibilidade de versão
├─ Teste com exemplo mínimo
└─ Verifique com dados reais
Padrão de Loop: Meta-Loop → Sensível ao Inicial
Gatilho de Escalada:
/reflectrevela: "Já tentei 3 correções, todas falharam com o mesmo erro"- Saída de
/traceidêntica entre tentativas - Padrão: Preso em loop de repetição (execução muda, resultado não)
- Ação: Use
/hypothesispara questionar suposições (mude para sensível ao inicial)
Ferramentas Utilizadas:
/observe- Observe 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 funciona: A habilidade de pesquisa se encaixa naturalmente no loop sensível ao inicial—você está questionando suposições, não apenas corrigindo a execução.
Veja Arquitetura do Processo de Pensamento - Loops de Feedback 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 persistir 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 suposições."
Por que isso é importante:
- ❌ Iteração: Feedback rápido, mas inútil após 2+ tentativas falhas
- ✅ Pesquisa: Custo inicial, previne 3+ ciclos de implantação falhos
Padrão:
Tentativa 1: Hipótese + Implantação (8 minutos)
↓ Falhou
Tentativa 2: Hipótese diferente + Implantação (8 minutos)
↓ Falhou
Tentativa 3: ❌ PARE - Não implante outra suposição
MUDE PARA MODO DE PESQUISA:
- Leia especificações/documentação (15 minutos)
- Inspecione dados reais (10 minutos)
- Reproduza localmente (20 minutos)
- Identifique causa raiz (15 minutos)
↓ Total: 60 minutos de pesquisa
Tentativa 3 (com causa raiz): Implante 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 Fonte | Confiabilidade | Quando Usar |
|---|---|---|
| Documentação Oficial | Mais Alta | Primeiro passo para comportamento de API, requisitos de tipo |
| Código Fonte | Muito Alta | Quando a documentação não está clara ou está incompleta |
| Issues do GitHub | Alta | Para bugs conhecidos, casos extremos, workarounds |
| Stack Overflow | Média | Para problemas comuns, após ler a documentação |
| Posts de Blog | Baixa | Para conceitos gerais, não detalhes de implementação |
| ChatGPT/IA | Mais Baixa | Ponto de partida apenas, sempre verifique |
Exemplo: Integração com Sistema de Tipos
# ❌ NÃO FAÇA: Pergunte ao ChatGPT "O PyMySQL aceita dicts para colunas JSON?"
# ChatGPT pode alucinar ou dar resposta desatualizada
# ✅ FAÇA: Leia a documentação do PyMySQL
open https://pymysql.readthedocs.io/en/latest/
# ✅ FAÇA: Teste com exemplo mínimo
python3 << 'EOF'
import pymysql
import json
# Teste: 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
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 de falha mínimo
# Em vez de testar a função Lambda inteira...
# ❌ 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
# Exato mesmo código da 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 API retorna dict (pode retornar lista)
- Assumir que campo existe (pode ser nulo/ausente)
- Assumir 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-se 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 tipos de dados reais
SELECT
symbol,
report_json,
typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G
-- Verifique 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
Veja WORKFLOW.md para o processo detalhado passo a passo de pesquisa.
Lista de Verificação de Investigação
Veja 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: 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 da Lambda, limites de conexão Aurora, uso pretendido)
- COMO verifico o contrato? (configuração Terraform, SHOW COLUMNS, acesso de teste?)
Cinco camadas de correção:
- Sintática: Código compila (sintaxe Python válida)
- Semântica: Código faz o que alega (lógica correta)
- Limite: Código pode alcançar o que precisa (rede, permissões)
- Configuração: Configuração da entidade corresponde aos requisitos do código (timeout, memória)
- Intencional: Uso corresponde ao propósito projetado (Lambda síncrona não para trabalho assíncrono)
Quando aplicar:
- Bugs do tipo "código parece correto, mas não funciona"
- Fluxos de trabalho multi-serviço (Lambda → Aurora → S3)
- Após 2 tentativas de implantação falhas (problemas de infraestrutura)
- Antes de concluir que "o código está correto" (verifique o contexto de execução)
Fluxo de trabalho de verificação:
1. Identifique limites de execução (código → runtime, código → banco de dados, serviço → serviço)
2. Identifique 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 pesquisa:
- Fase 1 (Observar): Note falhas relacionadas a limites (timeout, permissão negada, incompatibilidade de esquema)
- Fase 2 (Hipótese): Identifique qual limite pode estar sendo violado
- Fase 3 (Pesquisa): 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: Lista de Verificação de Limites de Execução para 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" obtêm respostas vagas do tipo "depende" sem análise estruturada
Solução: Aplique estrutura de análise de relacionamento baseada em OWL para comparação sistemática
Passos:
-
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)
-
Aplique 4 tipos de relacionamento:
- Parte-Todo: Um é parte do outro, ou são pares?
- Complemento: Eles lidam com preocupações não sobrepostas que trabalham juntas?
- Substituição: Um pode substituir o outro? Sob quais condições?
- Composição: Eles podem ser em camadas/compostos em um sistema de várias camadas?
-
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)
-
Faça recomendação baseada na análise
- Fundamentada na análise de relacionamento, não na intuição
- Inclua anti-padrões a evitar
Veja: Guia de Análise de Relacionamento para metodologia abrangente
Exemplos 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:
-
Leia a Documentação do Sistema Alvo
# Documentação PyMySQL open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # Procure: Quais tipos o execute() aceita? -
Teste Exemplo Mínimo
import pymysql import json # Teste 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 teve sucesso") -
Aplique 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 reportando erros, dashboard mostra pico
Passos de Pesquisa:
-
Triagem (< 5 minutos)
# Verifique 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 -
Mitigação Imediata (< 10 minutos)
# Reverta para 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" -
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 da implantação 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: Código Desconhecido
Tarefa: Adicionar funcionalidade a um módulo que você nunca viu
Passos de Pesquisa:
- Encontre o Ponto de Entrada
# Pesquise pela função principal rg "def main"