# Recherche et correction de bugs avec Claude Code : guide pratique

> Guide pratique complet pour le débogage du code via Claude Code : analyse des traces de pile, examen des journaux serveur, résolution des erreurs TypeScript, correction des tests et élimination des goulots d'étranglement de performance.

## 1. Pourquoi le débogage avec Claude Code est plus efficace que la méthode traditionnelle

Le processus classique de recherche d'erreurs se transforme souvent en une routine épuisante : le développeur passe des heures à décrypter des stack traces obscures dans le terminal, insère manuellement des dizaines de `console.log` ou de points d'arrêt dans le debugger, et tente de corréler les données provenant de plusieurs modules.

L'agent terminal Claude Code change radicalement cette approche : ayant un accès direct au système de fichiers, il peut instantanément suivre la chaîne d'exécution depuis l'interface client (UI), via les contrôleurs backend, jusqu'aux requêtes vers la base de données.

```mermaid
flowchart TD
    A["Симптом: Помилка або аварійний лог"] --> B["Claude Code CLI"]
    B --> C["Аналіз Stack Trace & Виділення файлів"]
    C --> D["Read & Grep по кодовій базі"]
    D --> E["Локалізація джерела збою"]
    E --> F["Генерація гіпотези та виправлення"]
    F --> G["Автоматичний прогін тестів / збірки"]
    G -->|Успіх| H["Коміт виправлення"]
    G -->|Помилка| E
```

### Comparaison entre le débogage manuel et le débogage avec Claude Code

| Critère | Débogage manuel traditionnel | Débogage avec Claude Code |
| :--- | :--- | :--- |
| **Localisation de l'erreur** | Navigation ligne par ligne dans la stack trace via l'IDE | Correspondance automatique de l'erreur avec le contexte du projet |
| **Analyse des logs** | Recherche visuelle d'anomalies parmi des milliers de lignes | Analyse autonome des logs structurés via des pipelines CLI |
| **Dépendances complexes** | Nécessité de garder en mémoire le graphe d'appels sur 5-10 fichiers | Traçage sémantique étape par étape des flux de données |
| **Erreurs TypeScript** | Tentatives de correction rapide via `as any` | Correction précise du narrowing de types sans compromettre le système |
| **Vérification du fix** | Redémarrage manuel de l'application ou des tests dans la console | Relance cyclique automatique des tests jusqu'à succès complet |

> [!NOTE]
> Claude Code ne remplace pas la compréhension du code par le développeur, mais réduit le temps entre l'incident et l'identification de sa cause racine d'un facteur 3 à 5.

---

## 2. Anatomie d'un bug report idéal pour un assistant IA

La qualité et la rapidité de résolution dépendent directement de l'exhaustivité de la description du bug dans la requête initiale.

### Requête vague contre description structurée

> [!WARNING]
> **Requête inefficace :**
> *« L'application est cassée, le formulaire d'inscription ne fonctionne pas, regarde ce qui ne va pas. »*
> 
> Avec une telle description, l'agent est contraint de parcourir des dizaines de fichiers au hasard, gaspillant la fenêtre de contexte dans des suppositions.

> [!TIP]
> **Description d'ingénierie professionnelle :**
> *« Lors de la soumission du formulaire sur `/register`, l'utilisateur reçoit un statut HTTP 500. La console du navigateur affiche l'erreur suivante : `TypeError: Cannot read properties of undefined (reading 'email')`. La requête envoie un JSON contenant les champs `username` et `mailAddress`. Vérifiez le schéma de validation dans `src/api/auth.ts` et harmonisez les noms des champs. »*

### Quatre règles pour une description exhaustive du défaut

1. **Comportement attendu (Expected Behavior) :** Ce qui devait se produire dans un scénario nominal.
2. **Comportement réel (Actual Behavior) :** Le texte exact de l'erreur, le code de statut ou le résultat inattendu du calcul.
3. **Étapes de reproduction (Reproduction Steps) :** Quels boutons ont été cliqués, quels paramètres ont été passés dans l'URL ou quel corps de requête a été envoyé.
4. **Contexte de localisation (Context & File Paths) :** Sur quelle page, quel composant ou quel endpoint l'exécution échoue.

---

## 3. Analyse des Stack Traces et interprétation des messages d'erreur

Les messages d'erreur et les stacks d'appels peuvent être transmis à l'agent sous forme brute. Claude filtrera automatiquement le bruit généré par les bibliothèques système (`node_modules`) et se concentrera sur le code de votre projet.

### Transmission d'une stack trace brute

```text
I am getting this runtime error when rendering the user table:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserTable (src/components/UserTable.tsx:34:22)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:15486:18)
    at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20103:13)

What is causing this, and how should we properly handle loading and empty states?
```

### Comment Claude analyse cet incident

1. **Lecture ciblée :** Ouvre `src/components/UserTable.tsx` à la ligne 34 via l'outil `Read`.
2. **Analyse de la source de données :** Examine les props et les hooks d'état (`useState`, `useQuery`) pour déterminer pourquoi le tableau d'utilisateurs est `undefined` au moment du rendu.
3. **Correction sécurisée :** Ajoute une vérification de présence des données (Optional Chaining `users?.map(...)`), un état de chargement (Skeleton/Spinner) ou une valeur par défaut (`users = []`).

---

## 4. Traitement des logs serveur et analyse via pipeline CLI

Pour investiguer les pannes serveur ou les erreurs sur les environnements de staging, Claude Code peut être connecté directement aux flux standards d'entrée/sortie Unix.

### Analyse des logs via un pipeline console

```bash
# Передати останні 100 рядків серверного логу в Claude для швидкої діагностики
tail -n 100 /var/log/nginx/error.log | claude -p "Find critical errors and explain their root cause. Provide actionable fix instructions."

# Пошук помилок із конкретного сервісу Docker
docker logs --tail 200 api-service 2>&1 | claude -p "Analyze database connection failures and timeout exceptions."
```

### Investigation interactive des fichiers de log

Dans une session interactive, vous pouvez diriger l'agent vers des logs sauvegardés :

```text
Read logs/production-error.log and focus on entries with status 500 from the last two hours. Group related exceptions and trace which external service call failed.
```

Claude identifiera les motifs récurrents d'échec, détectera les défaillances d'authentification des API externes ou l'épuisement du pool de connexions à la base de données.

---

## 5. Instrumentation stratégique : logging ciblé et tracing

Les bugs les plus complexes sont les « Silent Bugs » (défauts silencieux), où l'application ne lève aucune exception mais retourne un résultat incorrect (par exemple, le montant total d'une commande calculé comme `$0.00` au lieu de `$42.50`).

Dans ces cas, on utilise la méthode d'instrumentation stratégique.

### Algorithme d'investigation étape par étape

1. **Demandez l'insertion de logs :**
   ```text
   The order total calculation is returning 0 for items with promo codes. Add targeted diagnostic logging to calculateOrderTotal and its call sites to log input arguments, discount factors, and return values.
   ```
2. **Reproduisez le bug dans l'application :** Passez une commande avec un code promo dans l'environnement de test.
3. **Transmettez les logs diagnostiques obtenus à l'agent :**
   ```text
   Here is the diagnostic log from the checkout attempt:
   [DEBUG] Item subtotal: 42.50
   [DEBUG] Promo code applied: 'SPRING20' -> parsed discount: '0.2' (string)
   [DEBUG] Applying formula: 42.50 * (1 - '0.2') -> NaN -> coerced to 0

   What went wrong?
   ```
4. **Correction et nettoyage :**
   Claude identifie immédiatement l'incohérence de type (chaîne de caractères au lieu d'un nombre), corrige la fonction de parsing et **supprime automatiquement tous les logs de débogage temporaires**.

---

## 6. Correction des erreurs de types complexes en TypeScript

Les erreurs du compilateur TypeScript peuvent être déroutantes, notamment lors de l'utilisation de generics, d'unions de types ou d'objets imbriqués.

### Pourquoi il est dangereux de « bâillonner » le compilateur

Beaucoup de développeurs pressés utilisent des casts forcés (`as unknown as TargetType`), ce qui masque le problème à la compilation mais conduit à des crashs runtime.

:::tabs
@tab Approche dangereuse (Type Casting)
```typescript
// Погано: примусове ігнорування проблеми типів
const userEmail = (response.data as any).user.email;
// Якщо user виявиться null, додаток впаде в продакшені!
```
@tab Narrowing correct (Type Narrowing)
```typescript
// Добре: безпечне звуження типів через захисники
if (!response.data || typeof response.data !== 'object' || !('user' in response.data)) {
  throw new Error('Invalid API response structure');
}
const userEmail = response.data.user?.email ?? 'anonymous';
```
:::

### Instruction pour Claude afin d'obtenir une solution propre

```text
I am encountering this TypeScript compiler error in src/services/payment.ts:48:

Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Fix this issue properly using strict type narrowing or safe fallback values. Do NOT use type assertions ('as') or 'any'.
```

Claude analysera tout le cycle de vie de la variable et ajoutera une vérification appropriée de nullité/undefined.

---

## 7. Réparation automatisée des builds et des tests en boucle

L'une des capacités les plus puissantes de Claude Code est son fonctionnement autonome en boucle « Lancement → Analyse → Modification → Vérification ».

```mermaid
flowchart TD
    A["Команда: 'Fix all failing tests'"] --> B["Запуск npm test через Bash"]
    B --> C{"Всі тести пройдено?"}
    C -->|Так| D["Звіт про успішне завершення"]
    C -->|Ні| E["Аналіз помилок у звіті тестувальника"]
    E --> F{"Де баг: у коді чи в тесті?"}
    F -->|У коді| G["Виправлення бізнес-логіки"]
    F -->|У тесті| H["Оновлення застарілих очікувань тесту"]
    G & H --> B
```

### Templates de commandes prêts à l'emploi pour éliminer les défauts

:::tabs
@tab Réparation des tests unitaires (Jest / Vitest)
```text
Run the test suite with npm test. For each failing test:
1. Determine if the failure is caused by a real bug or an outdated test expectation.
2. Fix the underlying issue cleanly.
3. Re-run tests until all test suites pass.
```
@tab Correction des erreurs de compilation du build
```text
Run npm run build. Inspect the compiler and bundler error output. Fix all type and syntax errors, then verify with a clean build.
```
@tab Résolution des erreurs de linting (ESLint)
```text
Run npx eslint src/ --max-warnings=0. Fix all reportable style and syntax errors without disabling ESLint rules.
```
:::

---

## 8. Identification des goulots d'étranglement de performance et des fuites de ressources

Les erreurs ne se limitent pas aux crashs. Une lenteur de page, une charge excessive sur la base de données ou un gel de l'interface sont des défauts critiques de performance.

### Demande d'audit de performance

```text
The /dashboard page takes over 6 seconds to load. Analyze the server-side data fetching and client components:
1. Check for N+1 query patterns in our Prisma calls.
2. Identify missing database indices on frequently queried foreign keys.
3. Look for unnecessary client component re-renders caused by unstable object references.
```

### Ce que Claude recherche lors de l'analyse de performance

- **Requêtes N+1 :** Remplacement des requêtes séquentielles dans une boucle par une seule requête utilisant l'opérateur `IN` ou une jointure `include`.
- **Mémoïsation dans React :** Détection de calculs lourds sans `useMemo` ou de gestionnaires d'événements instables sans `useCallback`.
- **Payloads excessifs :** Ajout de pagination (`limit`/`offset`) ou de projection sélective des champs (`select: { id: true, name: true }`) au lieu de charger toute la table.

---

## 9. Atelier pratique : investigation pas à pas d'un bug réel

Examinons un scénario concret : les utilisateurs signalent que lorsqu'ils appliquent un coupon de réduction de 15% dans un panier contenant trois articles, le montant total débité est incorrect.

### Étape 1. Localisation du code de calcul

Ouvrez Claude Code et trouvez le module concerné :

```text
Find where the cart discount calculation is implemented and inspect the file.
```

Claude utilisera `Grep` sur le mot-clé `discount` et ouvrira le fichier `src/domain/cart.ts`.

### Étape 2. Analyse du code défectueux

```typescript
// Знайдений фрагмент у src/domain/cart.ts:
export function applyCoupon(total: number, discountPercent: number): number {
  return total - total * (discountPercent / 100);
}
```

À première vue, la formule semble correcte. Cependant, en JavaScript, les opérations à virgule flottante entraînent souvent des problèmes d'arrondi : `100 - 100 * (15 / 100)` donne `85.00000000000001`, ce qui casse la passerelle de paiement Stripe qui attend des cents entiers.

### Étape 3. Formulation de la demande de correction et des tests

```text
In src/domain/cart.ts, the applyCoupon function causes floating-point precision issues that fail payment validation. Refactor it to calculate prices in integer cents, add rounding via Math.round, and create a comprehensive unit test in src/domain/cart.test.ts covering edge cases.
```

### Étape 4. Vérification du résultat

L'agent corrige la fonction :

```typescript
export function applyCouponInCents(totalCents: number, discountPercent: number): number {
  const discountAmount = Math.round(totalCents * (discountPercent / 100));
  return Math.max(0, totalCents - discountAmount);
}
```

Ensuite, Claude lance automatiquement `npm test src/domain/cart.test.ts` et confirme que tous les tests passent.

---

## 10. Auto-vérification rapide et checklist finale de débogage

Testez vos compétences en matière de débogage avec Claude Code.

### Questions de contrôle

> **1. Quelle est la méthode la plus efficace pour investiguer une panne serveur survenue en staging ?**
>
> > [!TIP]
> > **Réponse :** Transmettre les dernières lignes du log directement en mode autonome de Claude Code via un pipeline console : `tail -n 150 /var/log/app.log | claude -p "Find errors and diagnose causes"`.

> **2. Pourquoi faut-il interdire à l'assistant l'utilisation de l'opérateur `as` lors de la correction des erreurs de types TypeScript ?**
>
> > [!TIP]
> > **Réponse :** Le cast via `as` masque uniquement le problème pour le compilateur, mais ne protège pas l'application des crashs runtime si les données attendues sont absentes. Il faut exiger un narrowing de type correct (Type Narrowing) ou des valeurs par défaut.

> **3. Comment organiser correctement la réparation d'une dizaine de tests échoués après un refactoring ?**
>
> > [!TIP]
> > **Réponse :** Lancer Claude Code en mode boucle avec des instructions claires : exécuter les tests, analyser les erreurs, distinguer les attentes obsolètes des vrais défauts de logique métier, et itérer jusqu'à 100% de succès.

### Checklist pour une chasse aux bugs systématique

- [ ] Fournissez à l'agent les 4 éléments obligatoires : Comportement attendu, Comportement réel, Étapes de reproduction et Chemins des fichiers.
- [ ] Transmettez les stack traces complètes sans abréviations — Claude trouvera lui-même les lignes de code pertinentes.
- [ ] Utilisez les pipes Unix (`tail | claude -p`) pour un diagnostic rapide des logs serveur.
- [ ] Exigez une suppression automatique des logs de débogage temporaires après la correction.