Compétence de Recherche
Stack Technique : AWS CLI, Git, ripgrep, jq, curl, DevTools navigateur
Source : Extrait des principes d'investigation et des motifs 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 inconnue
- ✓ 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-les simplement)
- ✗ Incidents urgents (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 le correctif évident (itération)
│ └─ NON → Même bug après 2 tentatives ? → RECHERCHE
│
├─ Incident de production ?
│ ├─ Affecte des utilisateurs MAINTENANT ? → Rollback/hotfix d'abord, recherchez plus tard
│ └─ Analyse post-incident ? → Recherche approfondie
│
├─ Besoin de comprendre la codebase ?
│ ├─ Fonction/module spécifique ? → Lire le code + tests
│ ├─ Architecture système ? → Tracer le flux des 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'utilisation réel
│ └─ Documenter la décision (ADR)
│
└─ Intégration API/Bibliothèque ?
├─ Lire les exigences de type (ne pas supposer)
├─ Vérifier la compatibilité des versions
├─ Tester avec un exemple minimal
└─ Vérifier avec des données réelles
Modèle de Boucle : Méta-Boucle → Initial-Sensible
Déclencheur d'Escalade :
/reflectrévèle : "J'ai essayé 3 correctifs, tous ont échoué avec la même erreur"- La sortie de
/traceest identique à travers les tentatives - Modèle : Bloqué dans une boucle de réessai (l'exécution change, le résultat non)
- Action : Utilisez
/hypothesispour 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 cela pourrait-il échouer différemment de ce que je pense ?)/research- Tester les hypothèses de manière systématique/validate- Vérifier si la nouvelle compréhension est correcte/reflect- Synthétiser les apprentissages après l'investigation
Pourquoi Cela Fonctionne : La compétence de recherche s'adapte naturellement à la boucle initial-sensible—vous remettez en question les hypothèses, pas seulement en corrigeant l'exécution.
Voir Architecture du Processus de Pensée - Boucles de Rétroaction pour un aperçu structurel.
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 inutile après 2+ tentatives échouées
- ✅ Recherche : Coût initial, évite 3+ cycles de déploiement échoués
Modèle :
Tentative 1 : Hypothèse + Déploiement (8 minutes)
↓ Échec
Tentative 2 : Hypothèse différente + Déploiement (8 minutes)
↓ Échec
Tentative 3 : ❌ STOP - Ne déployez pas une autre supposition
PASSEZ EN MODE RECHERCHE :
- Lire les specs/docs (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éploiement du correctif (8 minutes)
✅ Succès
Temps total : 76 minutes (vs 120+ minutes avec itération aveugle)
Principe 2 : Lire les Sources Primaires
Hiérarchie de la Qualité de l'Information :
| Type de Source | Fiabilité | Quand l'Utiliser |
|---|---|---|
| Documentation Officielle | La plus élevée | Premier arrêt pour le comportement de l'API, les exigences de type |
| Code Source | Très élevée | Quand la documentation n'est pas claire ou incomplète |
| Problèmes GitHub | Élevée | Pour les bugs connus, cas limites, solutions de contournement |
| Stack Overflow | Moyenne | Pour les problèmes courants, après avoir lu la documentation |
| Articles de Blog | Faible | Pour les concepts généraux, pas les détails d'implémentation |
| ChatGPT/IA | La plus faible | Point de départ uniquement, toujours vérifier |
Exemple : Intégration d'un Système de Type
# ❌ NE FAITES PAS : Demandez à ChatGPT "Est-ce que PyMySQL accepte les dict 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 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 correctifs, reproduisez le problème localement.
Avantages :
- ✅ Itération rapide (secondes vs minutes)
- ✅ Possibilité de déboguer avec des points d'arrêt
- ✅ Pas de coûts cloud
- ✅ Possibilité de tester facilement les cas limites
Modèle :
# Étape 1 : Extraire le cas d'échec minimal
# Au lieu de tester toute la fonction Lambda...
# ❌ MAUVAIS : Déployer sur AWS, vérifier les logs, répéter
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Attendre 30 secondes pour les logs CloudWatch...
# ✅ BON : Reproduire localement
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher
# Exactement le même code que 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 nul/manquant)
- Supposer le type (il pourrait être une chaîne pas un entier)
Modèle :
# ❌ 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 types sont-ils ?
# - 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 le 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 le processus de recherche étape par étape détaillé.
Liste de Contrôle d'Investigation
Voir INVESTIGATION-CHECKLIST.md pour la liste de contrôle de débogage systématique.
Vérification des Limites
Quand : Enquêter sur les 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'env, réseau, permissions ?)
- QUELS systèmes externes appelle-t-il ? (schéma Aurora, bucket S3, format API ?)
- QUELLES sont les propriétés de l'entité ? (timeout/mémoire Lambda, limites de connexion Aurora, utilisation prévue)
- COMMENT vérifier le contrat ? (configuration Terraform, SHOW COLUMNS, accès test ?)
Cinq couches de correction :
- Syntaxique : Le code compile (syntaxe Python valide)
- Sémantique : Le code fait ce qu'il prétend (logique correcte)
- Limite : Le code peut atteindre ce dont il a besoin (réseau, permissions)
- Configuration : La configuration de l'entité correspond aux exigences du code (timeout, mémoire)
- Intentionnelle : L'utilisation correspond à l'objectif conçu (Lambda synchrone pas pour le travail asynchrone)
Quand appliquer :
- Bugs "le code semble correct mais ne fonctionne pas"
- Flux de travail 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, QUELLE 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 preuve (code → config → runtime → réalité du terrain)
Intégration avec le flux de travail de recherche :
- Phase 1 (Observer) : Remarquer un échec lié aux limites (timeout, permission refusée, incompatibilité de schéma)
- Phase 2 (Hypothèse) : Identifier quelle limite pourrait être violée
- Phase 3 (Recherche) : Appliquer la liste de contrôle de vérification des limites systématiquement
- Phase 4 (Valider) : Vérifier le contrat par la réalité du terrain (tester l'exécution réelle)
Voir : Liste de Contrôle des Limites d'Exécution pour un flux de travail de vérification complet
Principes associés :
- 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
Investigations 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 de type "ça dépend" sans analyse structurée
Solution : Appliquer un cadre d'analyse relationnelle basé sur OWL pour une comparaison systématique
Étapes :
-
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)
-
Appliquer les 4 types de relations :
- Partie-Tout : L'un fait-il partie de l'autre, ou sont-ils 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 ?
-
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 perdez)
-
Faire une recommandation basée sur l'analyse
- Fondée sur l'analyse relationnelle, pas sur l'intuition
- Inclure les anti-modèles à éviter
Voir : Guide d'Analyse Relationnelle pour une méthodologie complète
Exemples de Cas d'Utilisation :
- "Dois-je utiliser Redis ou DynamoDB pour la mise en cache ?" → Appliquer l'analyse de substitution & composition
- "Comment se relient le CDN et la mise en cache applicative ?" → Appliquer l'analyse de complément & composition
- "Microservices vs Monolithe ?" → Appliquer l'analyse partie-tout & compromis
Scénarios de Recherche Courants
Scénario 1 : Incompatibilité du Système de Type
Symptôme : Même erreur après 2 tentatives, échec silencieux
Étapes de Recherche :
-
Lire la Documentation du Système Cible
# Docs PyMySQL open https://pymysql.readthedocs.io/en/latest/modules/cursors.html # Chercher : Quels types execute() accepte-t-il ? -
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("La chaîne JSON a réussi") -
Appliquer le Correctif 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 :
-
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 cela 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 -
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" -
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 cela a-t-il échoué ? # - Comment l'empêcher ?
Scénario 3 : Codebase Inconnue
Tâche : Ajouter une fonctionnalité à un module que vous n'avez jamais vu
Étapes de Recherche :
- Trouver le Point d'Entrée
# Rechercher la fonction principale rg "def main"
…
[truncated for translation]