Communitygithub.com

majiayu000/claude-skill-registry

Investigation systématique et analyse des causes racines. À utiliser pour déboguer des problèmes persistants, comprendre des systèmes complexes ou avant de prendre des décisions architecturales.

Qu'est-ce que claude-skill-registry ?

Cette compétence de recherche fournit un cadre structuré pour mener des enquêtes approfondies, en particulier lorsque les tentatives de correction précédentes ont échoué. Elle est conçue pour les développeurs utilisant des agents IA comme Claude Code, Cursor ou Codex, et s'applique à des scénarios tels que le débogage de bugs persistants, la compréhension de codebases inconnues, l'analyse d'incidents de production et les décisions architecturales. L'approche met l'accent sur la recherche avant l'itération, la consultation de sources primaires (documentation officielle, code source) et la reproduction locale des problèmes. Elle inclut un arbre de décision pour guider le choix de la méthode, des principes comme l'inspection des données réelles, et des workflows spécifiques pour la vérification des limites d'exécution dans les systèmes distribués (Lambda, Aurora, S3). La compétence est détaillée dans un fichier SKILL.md qui décrit les patterns, les principes, les scénarios courants et les listes de vérification, s'intégrant à une architecture de boucles de rétroaction pour éviter les cycles de correction aveugles.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence de Recherche

Stack Technique : AWS CLI, Git, ripgrep, jq, curl, DevTools du navigateur

Source : Extrait des principes d'investigation et des patterns de débogage de CLAUDE.md.


Quand Utiliser Cette Compétence

Utilisez la compétence de recherche quand :

  • ✓ Un même bug persiste après 2 tentatives de correction
  • ✓ Vous devez comprendre une codebase non familière
  • ✓ Vous enquêtez sur des incidents de production
  • ✓ Vous prenez des décisions architecturales
  • ✓ Vous déboguez des interactions système complexes
  • ✓ Vous apprenez une nouvelle technologie/bibliothèque

N'utilisez PAS cette compétence pour :

  • ✗ Première tentative de correction (essayez d'abord la solution évidente)
  • ✗ Problèmes bien compris (corrigez simplement)
  • ✗ Incidents critiques en temps (corrigez d'abord, enquêtez plus tard)

Arbre de Décision Rapide pour la Recherche

Quel est le problème ?
├─ Vous voyez ce problème pour la première fois ?
│  ├─ OUI → Essayez la correction évidente (itération)
│  └─ NON → Même bug après 2 tentatives ? → RECHERCHE
│
├─ Incident de production ?
│  ├─ Affecte les utilisateurs MAINTENANT ? → Rollback/hotfix d'abord, recherche plus tard
│  └─ Analyse post-incident ? → Recherche approfondie
│
├─ Besoin de comprendre la codebase ?
│  ├─ Fonction/module spécifique ? → Lire le code + les tests
│  ├─ Architecture système ? → Tracer le flux de requêtes
│  └─ Contexte historique ? → Git blame + historique des commits
│
├─ Décision technologique ?
│  ├─ Lire la documentation officielle (pas les articles de blog)
│  ├─ Comparer les alternatives (compromis)
│  ├─ Prototyper avec un cas d'usage réel
│  └─ Documenter la décision (ADR)
│
└─ Intégration d'API/bibliothèque ?
   ├─ Lire les exigences de type (ne pas supposer)
   ├─ Vérifier la compatibilité des versions
   ├─ Tester un exemple minimal
   └─ Vérifier avec des données réelles

Pattern de Boucle : Méta-Boucle → Boucle Initiale-Sensible

Déclencheur d'Escalade :

  • /reflect révèle : « J'ai essayé 3 corrections, toutes ont échoué avec la même erreur »
  • La sortie de /trace est identique entre les tentatives
  • Pattern : Bloqué dans une boucle de réessai (l'exécution change, le résultat non)
  • Action : Utilisez /hypothesis pour remettre en question les hypothèses (passez en mode initial-sensible)

Outils Utilisés :

  • /observe - Remarquer le comportement du système (ce qui échoue)
  • /hypothesis - Générer des explications alternatives (pourquoi pourrait-il échouer différemment de ce que je pense ?)
  • /research - Tester les hypothèses systématiquement
  • /validate - Vérifier si la nouvelle compréhension est correcte
  • /reflect - Synthétiser les apprentissages après l'enquête

Pourquoi Cela Fonctionne : La compétence de recherche s'intègre naturellement à la boucle initiale-sensible — vous remettez en question les hypothèses, pas seulement l'exécution.

Voir Architecture du Processus de Pensée - Boucles de Rétroaction pour une vue d'ensemble structurelle.


Principes Fondamentaux de la Recherche

Principe 1 : Rechercher avant d'Itérer

Extrait de CLAUDE.md :

« Quand le même bug persiste après 2 tentatives de correction, ARRÊTEZ d'itérer et COMMENCEZ à rechercher. Investissez 30 à 60 minutes pour comprendre la cause racine au lieu de déployer plus de suppositions. »

Pourquoi C'est Important :

  • ❌ Itération : Retour rapide, mais inefficace après 2+ tentatives échouées
  • ✅ Recherche : Coût initial, mais évite 3+ cycles de déploiement échoués

Pattern :

Tentative 1 : Hypothèse + Déploiement (8 minutes)
  ↓ Échec
Tentative 2 : Hypothèse différente + Déploiement (8 minutes)
  ↓ Échec
Tentative 3 : ❌ ARRÊT - Ne déployez pas une autre supposition

PASSEZ EN MODE RECHERCHE :
  - Lire les spécifications/documentation (15 minutes)
  - Inspecter les données réelles (10 minutes)
  - Reproduire localement (20 minutes)
  - Identifier la cause racine (15 minutes)
  ↓ Total : 60 minutes de recherche

Tentative 3 (avec cause racine) : Déployer la correction (8 minutes)
  ✅ Succès

Temps total : 76 minutes (contre 120+ minutes avec itération aveugle)

Principe 2 : Lire les Sources Primaires

Hiérarchie de la Qualité de l'Information :

Type de SourceFiabilitéQuand l'Utiliser
Documentation OfficielleLa plus élevéePremier recours pour le comportement des API, les exigences de type
Code SourceTrès élevéeQuand la documentation n'est pas claire ou incomplète
Problèmes GitHubÉlevéePour les bugs connus, les cas limites, les solutions de contournement
Stack OverflowMoyennePour les problèmes courants, après avoir lu la documentation
Articles de BlogFaiblePour les concepts généraux, pas les détails d'implémentation
ChatGPT/IALa plus faiblePoint de départ uniquement, toujours vérifier

Exemple : Intégration d'un Système de Types

# ❌ NE FAITES PAS : Demander à ChatGPT « Est-ce que PyMySQL accepte les dicts pour les colonnes JSON ? »
# ChatGPT pourrait halluciner ou donner une réponse obsolète

# ✅ FAITES : Lire la documentation PyMySQL
open https://pymysql.readthedocs.io/en/latest/

# ✅ FAITES : Tester avec un exemple minimal
python3 << 'EOF'
import pymysql
import json

# Test : Est-ce que PyMySQL accepte un dict pour une colonne JSON ?
data = {'key': 'value'}

try:
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    print("✅ Dict accepté")
except TypeError as e:
    print(f"❌ Dict rejeté : {e}")
    # Essayer une chaîne JSON à la place
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("✅ Chaîne JSON acceptée")
EOF

Principe 3 : Reproduire Localement

Avant de déployer des corrections, reproduisez le problème localement.

Avantages :

  • ✅ Itération rapide (secondes contre minutes)
  • ✅ Possibilité de déboguer avec des points d'arrêt
  • ✅ Pas de coûts cloud
  • ✅ Facile à tester les cas limites

Pattern :

# Étape 1 : Extraire le cas d'échec minimal
# Au lieu de tester toute une fonction Lambda...

# ❌ MAUVAIS : Déployer sur AWS, vérifier les logs, répéter
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Attendez 30 secondes pour les logs CloudWatch...

# ✅ BON : Reproduire localement
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher

# Exactement le même code que la Lambda
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result)  # Retour immédiat
EOF

Principe 4 : Inspecter les Données Réelles

Ne supposez pas la forme des données—vérifiez avec des exemples réels.

Erreurs Courantes :

  • Supposer que l'API retourne un dict (elle pourrait retourner une liste)
  • Supposer qu'un champ existe (il pourrait être null/manquant)
  • Supposer un type (il pourrait être une chaîne, pas un entier)

Pattern :

# ❌ NE FAITES PAS : Supposer
# « L'API retourne une liste de tickers »

# ✅ FAITES : Vérifier
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json

# Inspecter la structure :
# - Est-ce une liste ou un dict ?
# - Quels champs sont présents ?
# - Quels sont leurs types ?
# - Y a-t-il des valeurs nulles ?
# - Y a-t-il des structures imbriquées ?

Exemple : Investigation du Schéma Aurora

# Se connecter à Aurora via un tunnel SSM
aws ssm start-session \
  --target i-1234567890abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'

# Inspecter le schéma réel (ne pas supposer)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;

-- Vérifier les types de données réels
SELECT
  symbol,
  report_json,
  typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G

-- Vérifier les valeurs nulles
SELECT COUNT(*) as total,
       SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL

Flux de Travail de Recherche

Voir WORKFLOW.md pour un processus de recherche détaillé étape par étape.


Liste de Vérification d'Investigation

Voir INVESTIGATION-CHECKLIST.md pour une liste de vérification de débogage systématique.


Vérification des Limites

Quand : Enquêter sur des systèmes distribués (Lambda, Aurora, S3, SQS, Step Functions)

Problème : Le code semble correct mais échoue en production en raison de limites d'exécution non vérifiées

Questions critiques :

  • OÙ ce code s'exécute-t-il ? (Lambda, EC2, local ?)
  • QUEL environnement nécessite-t-il ? (variables d'environnement, réseau, permissions ?)
  • QUELS systèmes externes appelle-t-il ? (schéma Aurora, bucket S3, format d'API ?)
  • QUELLES sont les propriétés des entités ? (timeout/mémoire Lambda, limites de connexion Aurora, utilisation prévue)
  • COMMENT vérifier le contrat ? (configuration Terraform, SHOW COLUMNS, test d'accès ?)

Cinq couches de correction :

  1. Syntaxique : Le code se compile (syntaxe Python valide)
  2. Sémantique : Le code fait ce qu'il prétend (logique correcte)
  3. Limite : Le code peut atteindre ce dont il a besoin (réseau, permissions)
  4. Configuration : La configuration de l'entité correspond aux exigences du code (timeout, mémoire)
  5. Intentionnelle : L'utilisation correspond à l'objectif de conception (Lambda synchrone pas pour du travail asynchrone)

Quand appliquer :

  • Bugs « Le code semble correct mais ne fonctionne pas »
  • Workflows multi-services (Lambda → Aurora → S3)
  • Après 2 tentatives de déploiement échouées (problèmes d'infrastructure)
  • Avant de conclure « le code est correct » (vérifier le contexte d'exécution)

Flux de travail de vérification :

1. Identifier les limites d'exécution (code → runtime, code → base de données, service → service)
2. Identifier les entités physiques (QUELLE Lambda, QUEL Aurora, QUEL bucket S3)
3. Vérifier que la configuration correspond aux exigences (timeout, mémoire, concurrence)
4. Vérifier que l'intention correspond à l'utilisation (Lambda asynchrone pas pour API synchrone)
5. Progresser à travers les couches de preuves (code → configuration → runtime → vérité terrain)

Intégration avec le flux de travail de recherche :

  • Phase 1 (Observer) : Remarquer un échec lié aux limites (timeout, permission refusée, incohérence de schéma)
  • Phase 2 (Hypothèse) : Identifier quelle limite pourrait être violée
  • Phase 3 (Recherche) : Appliquer la liste de vérification des limites systématiquement
  • Phase 4 (Valider) : Vérifier le contrat via la vérité terrain (tester l'exécution réelle)

Voir : Liste de Vérification des Limites d'Exécution pour un flux de travail de vérification complet

Principes connexes :

  • Principe #20 (Discipline des Limites d'Exécution) - CLAUDE.md
  • Principe #2 (Renforcement Progressif des Preuves) - Vérifier à travers toutes les couches
  • Principe #15 (Contrat Infrastructure-Application) - Synchroniser le code et l'infrastructure

Enquêtes Architecturales

Quand : Choisir entre des technologies, des modèles ou des approches architecturales

Problème : Les comparaisons « X vs Y » obtiennent des réponses vagues « ça dépend » sans analyse structurée

Solution : Appliquer un cadre d'analyse des relations basé sur OWL pour une comparaison systématique

Étapes :

  1. Définir les concepts comparés

    • Qu'est-ce que X ? (définition, emplacement, objectif, exemples)
    • Qu'est-ce que Y ? (définition, emplacement, objectif, exemples)
  2. Appliquer les 4 types de relations :

    • Partie-Tout : L'un fait-il partie de l'autre, ou sont-ils des pairs ?
    • Complément : Gèrent-ils des préoccupations non chevauchantes qui fonctionnent ensemble ?
    • Substitution : L'un peut-il remplacer l'autre ? Sous quelles conditions ?
    • Composition : Peuvent-ils être superposés/composés en un système multicouche ?
  3. Documenter avec des exemples concrets

    • Fournir des scénarios réels, pas de la théorie abstraite
    • Inclure une analyse des compromis (ce que vous gagnez vs ce que vous perdez)
  4. Faire une recommandation basée sur l'analyse

    • Ancré dans l'analyse des relations, pas dans l'intuition
    • Inclure les anti-patterns à éviter

Voir : Guide d'Analyse des Relations pour une méthodologie complète

Exemples de Cas d'Utilisation :

  • « Dois-je utiliser Redis ou DynamoDB pour le cache ? » → Appliquer l'analyse de substitution et de composition
  • « Comment le CDN et le cache d'application sont-ils liés ? » → Appliquer l'analyse de complément et de composition
  • « Microservices vs Monolithe ? » → Appliquer l'analyse partie-tout et des compromis

Scénarios de Recherche Courants

Scénario 1 : Inadéquation du Système de Types

Symptôme : Même erreur après 2 tentatives, échec silencieux

Étapes de Recherche :

  1. Lire la Documentation du Système Cible

    # Documentation PyMySQL
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # Chercher : Quels types execute() accepte-t-il ?
    
  2. Tester un Exemple Minimal

    import pymysql
    import json
    
    # Tester l'hypothèse : Dict vs chaîne JSON
    data = {'key': 'value'}
    
    # Test 1 : Dict
    try:
        cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    except TypeError as e:
        print(f"Dict a échoué : {e}")
    
    # Test 2 : Chaîne JSON
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("Chaîne JSON réussie")
    
  3. Appliquer la Correction en Toute Confiance

    # Maintenant nous SAVONS que json.dumps() est requis
    def store_report(symbol: str, report_json: dict):
        cursor.execute(
            "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)",
            (symbol, json.dumps(report_json))  # Convertir en chaîne
        )
    

Scénario 2 : Incident de Production

Symptôme : Les utilisateurs signalent des erreurs, le tableau de bord montre un pic

Étapes de Recherche :

  1. Triage (< 5 minutes)

    # Vérifier le nombre d'erreurs
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $(($(date +%s) - 600))000 \
      --filter-pattern "ERROR" \
      --query 'length(events)'
    
    # Vérifier quand ça a commencé
    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. Atténuation Immédiate (< 10 minutes)

    # Revenir à la version précédente
    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 "Revenu de v$CURRENT à v$PREVIOUS"
    
  3. Analyse Post-Incident (30-60 minutes)

    # Collecter les preuves
    mkdir incident-$(date +%Y%m%d-%H%M%S)
    cd incident-*
    
    # Exporter les logs d'erreur
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $INCIDENT_START \
      --end-time $INCIDENT_END \
      --filter-pattern "ERROR" > errors.json
    
    # Exporter les métriques
    aws cloudwatch get-metric-statistics ... > metrics.json
    
    # Obtenir le diff de déploiement
    git diff v$PREVIOUS v$CURRENT > deployment.diff
    
    # Analyser (analyse des causes racines)
    # - Qu'est-ce qui a changé ?
    # - Qu'est-ce qui a échoué ?
    # - Pourquoi a-t-il échoué ?
    # - Comment l'empêcher ?
    

Scénario 3 : Codebase Non Familière

Tâche : Ajouter une fonctionnalité à un module que vous n'avez jamais vu

Étapes de Recherche :

  1. Trouver le Point d'Entrée
    # Rechercher la fonction principale
    rg "def main" 
    

[La suite du fichier SKILL.md est tronquée pour la traduction.]

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.

Skills associés