Maîtrise du débogage avec Claude Code : des erreurs aux solutions en quelques minutes

1. The Trinity : puissance maximale de débogage

Pour les bugs complexes, combinez trois techniques dans ce qu'on appelle The Trinity :

Quand utiliser The Trinity

Workflow Trinity

2. La formule du prompt de débogage

Un prompt de débogage bien structuré améliore considérablement les résultats. Utilisez cette formule :

La formule

<problem>
[Ce qui se passe vs. ce qui devrait se passer]
</problem>

<error>
[Message d'erreur complet et stack trace]
</error>

<context>
[Quand ça se produit, ce qui le déclenche, environnement]
</context>

<attempted>
[Ce que vous avez déjà essayé]
</attempted>

<constraints>
[Toute limitation sur la solution]
</constraints>

Exemple : rapport de bug réel

<problem>
Users report being logged out after 5-10 minutes of activity,
but session timeout is configured for 24 hours.
</problem>

<error>
No explicit error - JWT verification just fails silently.
Cookie is present but token is rejected.
</error>

<context>
- Next.js 14 App Router with next-auth
- PostgreSQL session store
- Load balanced across 3 servers
- Started after deploying v2.3.0 last week
</context>

<attempted>
- Verified JWT_SECRET is same across servers
- Checked cookie expiry (correct at 24h)
- Reviewed session table (sessions exist)
</attempted>

<constraints>
- Can't revert the deploy (contains critical security fix)
- Production issue, need quick resolution
- Must maintain session security
</constraints>

3. Boucles de feedback rapides

Le feedback rapide est le secret d'un débogage efficace. Plus vite vous pouvez valider des hypothèses, plus vite vous résolvez les bugs.

La pyramide des boucles de feedback

Implémenter un feedback rapide

Hook Claude Code pour validation instantanée

Configurez des hooks PostToolUse pour valider chaque modification :

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/validate.sh"
      }]
    }]
  }
}

validate.sh :

#!/bin/bash
FILE=$(echo "$TOOL_INPUT" | jq -r '.file_path // .file')

# TypeScript check
if [[ "$FILE" == *.ts || "$FILE" == *.tsx ]]; then
    npx tsc --noEmit "$FILE" 2>&1 | head -5
fi

# Run relevant tests
npm test -- --findRelatedTests "$FILE" 2>&1 | tail -10

4. Patterns d'analyse d'erreurs

Pattern 1 : Analyse de stack trace

Lorsque vous avez une stack trace, utilisez cette approche :

Analyze this stack trace:

[paste full stack trace]

Tell me:
1. Where exactly the error originates (file, line, function)
2. What the immediate cause is
3. What the root cause might be (the real bug)
4. How to fix it

Pattern 2 : La recherche binaire

Pour les bugs que vous ne pouvez pas localiser, utilisez la recherche binaire :

The bug appeared sometime in the last 10 commits.
Use git bisect logic:

1. Find the middle commit
2. Check if bug exists there
3. Narrow down to the half that introduced it
4. Repeat until found

Pattern 3 : L'escalade Canard en plastique

Commencez simple, escaladez si nécessaire :

Pattern 4 : Débogage par provocation

L'équipe Claude utilise des patterns de provocation pour un meilleur débogage :

L'exigence de preuve :

Prove to me this works — show me the diff in behavior 
between main and this branch.

Le défi :

Grill me on this fix. What edge cases would break it?
What would a senior engineer flag?

La remise à zéro :

Knowing everything you know now, scrap this approach
and implement the proper fix from scratch.

5. Catégories de bugs courants

Bugs Async/Await

Symptômes : Valeurs undefined, conditions de concurrence, rejections non gérées

Pattern de prompt :

I have an async bug. The symptom is [X].

Check for:
- Missing await keywords
- Race conditions between parallel operations
- Unhandled promise rejections
- Incorrect error propagation in async chains

Bugs de gestion d'état

Symptômes : UI qui ne se met pas à jour, données périmées, valeurs inattendues

Pattern de prompt :

State bug in [React/Vue/etc].

The issue: [describe symptom]
The expected: [what should happen]

Check for:
- Direct state mutation instead of immutable updates
- Stale closures capturing old values
- Missing dependency array items in useEffect
- Incorrect state initialization

Bugs d'intégration API

Symptômes : Données incorrectes, requêtes échouées, erreurs CORS

Pattern de prompt :

API integration issue with [endpoint].

Error: [error message]
Request: [method, URL, headers, body]
Response: [status, body]

Check for:
- Request/response format mismatches
- Authentication header issues
- CORS configuration
- Rate limiting or timeout problems

6. Le filet de sécurité Rewind

Vous avez fait un changement qui a empiré les choses ? Utilisez /rewind.

Comment fonctionne Rewind

/rewind

Cela annule les modifications récentes de fichiers effectuées par Claude, restaurant l'état précédent.

L'échelle de récupération

Quand les choses tournent mal, utilisez l'option de récupération la plus légère qui fonctionne :

Le pattern Checkpoint

Avant des changements risqués, créez un point de contrôle :

# Create checkpoint
git stash push -u -m "checkpoint-before-auth-refactor"

# Try risky refactor
# If it fails: restore checkpoint
git stash pop

7. Débogage CI/CD

Les pipelines CI/CD en échec sont des cibles courantes de débogage. Voici comment investiguer efficacement :

Workflow d'investigation rapide

# List recent workflow runs
gh run list --limit 10

# View specific run details
gh run view <run-id>

# View logs for failed run
gh run view <run-id> --log-failed

# Download logs for detailed analysis
gh run download <run-id>

Combinaison avec Claude Code

# Fetch failure logs and ask Claude to analyze
gh run view --log-failed | claude -p "
  Analyze these test failures.
  Identify the root cause.
  Propose fixes for each failing test.
  Output as actionable steps.
"

Commandes courantes de débogage CI

8. Checklist de débogage

Utilisez cette checklist pour tout bug non trivial :

Avant le débogage

• → Pouvez-vous reproduire le bug de manière cohérente ?
• → Avez-vous le message d'erreur complet et la stack trace ?
• → Savez-vous quand le bug a commencé à apparaître ?
• → Avez-vous vérifié si c'est un problème connu ?

Pendant le débogage

• → Commencez par l'hypothèse la plus simple
• → Utilisez le mode /plan pour l'exploration
• → Écrivez un test échouant qui démontre le bug
• → Ne faites pas plusieurs changements à la fois
• → Vérifiez chaque hypothèse avant de passer à la suivante

Après la correction

• → Le test échouant passe-t-il maintenant ?
• → Avez-vous introduit de nouveaux problèmes ?
• → Avez-vous documenté la cause racine ?
• → Cela devrait-il être ajouté à CLAUDE.md pour prévenir la récurrence ?

9. Avancé : bibliothèque de prompts de débogage

Prompt de débogage universel

I need to debug this issue:

**Symptom**: [what's happening]
**Expected**: [what should happen]
**Error**: [error message if any]
**Reproduction**: [steps to reproduce]

Analyze systematically:
1. What are the possible causes?
2. How can we narrow down?
3. What's the most likely root cause?
4. What's the fix?

Prompt de débogage de performance

Performance issue:
- Operation: [what's slow]
- Expected time: [target]
- Actual time: [current]
- Load: [concurrent users, data size]

Profile and identify bottlenecks:
1. Where is time being spent?
2. Are there N+1 queries?
3. Is there unnecessary computation?
4. What's the optimization?

Prompt de débogage de sécurité

Security concern in [file/feature]:

Audit for:
- Injection vulnerabilities (SQL, XSS, command)
- Authentication/authorization gaps
- Data exposure risks
- Input validation issues

Rate severity: Critical/High/Medium/Low
Provide remediation for each issue.

Résumé

Un débogage efficace avec Claude Code repose sur :

1. →Utilisez The Trinity pour les bugs complexes (mode Plan + réflexion étendue + analyse structurée)
2. →Fournissez un contexte complet dans vos prompts de débogage
3. →Construisez des boucles de feedback rapides pour une validation instantanée
4. →Connaissez vos options de récupération (/rewind, checkpoints, git)
5. →Utilisez les patterns de provocation pour obtenir une analyse plus approfondie

Continuez vers le Module 3 pour des exercices pratiques de débogage et des études de cas réelles.