Communitygithub.com

majiayu000/claude-skill-registry

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 é claude-skill-registry?

Esta habilidade de pesquisa foi projetada para desenvolvedores e agentes de IA que precisam investigar e resolver problemas complexos de forma sistemática. Ela é particularmente útil quando o mesmo bug persiste após duas tentativas de correção, quando é necessário entender um código desconhecido, investigar incidentes de produção ou tomar decisões arquiteturais importantes. A habilidade se baseia em princípios fundamentais como pesquisar antes de iterar, ler fontes primárias (documentação oficial e código-fonte), reproduzir localmente e inspecionar dados reais. Ela oferece suporte a dezenas de ferramentas e plataformas, incluindo AWS CLI, Git, ripgrep, jq, curl e DevTools do navegador. O fluxo de trabalho inclui um loop de investigação que alterna entre hipóteses e validação, com gatilhos de escalada para evitar iterações cegas. Também fornece listas de verificação para investigações arquiteturais, verificação de limites de execução e análise de causa raiz, tudo documentado no formato SKILL.md e acessível através de comandos como `/observe`, `/hypothesis`, `/research` e `/validate`.

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

Perguntar na sua IA favorita

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

Documentação

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:

  • /reflect revela: "Já 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 (execução muda, resultado não)
  • Ação: Use /hypothesis para 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 FonteConfiabilidadeQuando Usar
Documentação OficialMais AltaPrimeiro passo para comportamento de API, requisitos de tipo
Código FonteMuito AltaQuando a documentação não está 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 BaixaPonto 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:

  1. Sintática: Código compila (sintaxe Python válida)
  2. Semântica: Código faz o que alega (lógica correta)
  3. Limite: Código pode alcançar o que precisa (rede, permissões)
  4. Configuração: Configuração da entidade corresponde aos requisitos do código (timeout, memória)
  5. 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:

  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 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?
  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 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:

  1. 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?
    
  2. 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")
    
  3. 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:

  1. 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
    
  2. 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"
    
  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 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:

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

Individual skills in this repo

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

majiayu000/claude-skill-registry

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

Habilidades Relacionadas