Diagnostic d'erreurs avec Claude Code : des logs aux tests de régression

Diagnostiquer une erreur ne consiste pas à lire la dernière ligne rouge du terminal puis à modifier le code au hasard. C’est transformer un échec en preuve reproductible par une autre personne, un runner de tests ou Claude Code.

Trois notions suffisent pour commencer. Un log est la trace produite par une commande ou une application. Une stack trace montre le chemin des appels de fonctions qui ont mené à l’erreur. Une reproduction minimale est le plus petit exemple qui échoue encore après avoir retiré l’interface, les données et la configuration inutiles.

Claude Code est plus fiable si vous ne lui demandez pas seulement “corrige”. Donnez-lui la commande en échec, la première ligne pertinente, quelques hypothèses et la commande qui devra passer après le correctif.

Pour compléter, lisez aussi la boucle de triage des erreurs de build, le décodeur de messages d’erreur et le modèle de rapport de bug.

Flux de diagnostic

flowchart LR
  A["Sauver la commande en échec"] --> B["Trouver la première erreur"]
  B --> C["Limiter à trois hypothèses"]
  C --> D["Créer une reproduction minimale"]
  D --> E["Ajouter un test de régression"]
  E --> F["Appliquer le plus petit correctif"]
  F --> G["Vérifier avec la même commande"]
  G --> H["Écrire une note de passation"]

Cet ordre évite de modifier avant de prouver. Claude Code peut lire beaucoup de fichiers; une consigne trop large peut produire du nettoyage sans rapport. Le but du diagnostic n’est pas d’ajouter des changements, mais de réduire l’espace des causes.

Commencez par quatre éléments.

Preuve	Rôle	Exemple pour Claude Code
Commande en échec	Fixe la reproduction	npm run build, node --test
Première ligne d’erreur	Évite le bruit en fin de log	TypeError, ERR_MODULE_NOT_FOUND
Contexte d’exécution	Isole les différences d’environnement	Version Node.js, OS, CI
Comportement attendu	Définit le bon correctif	null devient tableau vide, 404 non retenté

Pour les noms d’erreurs JavaScript, consultez MDN JavaScript error reference. Côté Node.js, Node.js Errors docs aide à privilégier error.code plutôt que des messages textuels fragiles. Pour les tests E2E, Playwright debugging docs explique Inspector, Trace Viewer et le débogage VS Code.

Workflow pratique avec Claude Code

Utilisez ce prompt comme unité de travail.

claude -p "
Diagnose the following error.

1. Confirm the failing command
2. Separate the first failure from unrelated log noise
3. List up to three root-cause hypotheses
4. Create a minimal reproduction
5. Add a regression test
6. Apply the smallest fix
7. Verify with the same command and write a handoff note

Constraints:
- Do not perform unrelated refactors
- Explain any public API change before making it
- Do not call the fix complete if verification still fails
"

“Trois hypothèses maximum” est volontaire. Pour Cannot read properties of undefined, les causes utiles sont souvent une forme de réponse API modifiée, une valeur initiale absente ou un rendu avant la fin du chargement asynchrone.

Cas 1 : erreur undefined dans React

Un cas fréquent : l’API renvoie null et l’UI appelle users.map(...). L’erreur ressemble à un problème React, mais la cause est souvent le contrat de données.

// user-list.mjs
export function names(users) {
  if (!Array.isArray(users)) {
    return [];
  }

  return users.map((user) => user.name ?? "(no name)");
}

// user-list.test.mjs
import assert from "node:assert/strict";
import test from "node:test";
import { names } from "./user-list.mjs";

test("names returns an empty array when the API returns null", () => {
  assert.deepEqual(names(null), []);
});

test("names keeps valid user names", () => {
  assert.deepEqual(names([{ name: "Masa" }]), ["Masa"]);
});

node --test user-list.test.mjs

Si l’ancien code faisait seulement return users.map(...), le premier test échoue. Demandez à Claude Code d’ajouter le test qui échoue, puis d’appliquer le plus petit correctif.

Cas 2 : ENOENT et imports Node.js

ENOENT signifie généralement qu’un fichier ou dossier est introuvable. Le piège classique : config/local.json existe sur votre machine, mais pas dans CI ni dans l’image Docker.

Regardez la commande en échec, error.code, error.path, le COPY du Dockerfile, .gitignore et le working directory CI.

claude -p "
Diagnose this Node.js ENOENT failure.
Inspect error.code, error.path, current working directory, Dockerfile, and CI config.
Suggest only fixes that do not depend on a local-only file.
"

Ne vous contentez pas de créer le fichier manquant. Si la configuration est obligatoire, échouez tôt avec un message clair. Si elle est optionnelle, ajoutez une valeur par défaut. Si CI a besoin d’un exemple, copiez un fichier sample versionné.

Cas 3 : Playwright échoue seulement en CI

Les timeout Playwright mélangent bug applicatif, mauvaise condition d’attente, CI plus lente, session expirée ou réseau différent. Augmenter le timeout cache souvent la cause.

Conservez les traces en cas d’échec.

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  use: {
    screenshot: "only-on-failure",
    trace: "retain-on-failure",
    video: "retain-on-failure",
  },
});

Donnez à Claude Code le spec en échec, le locator, l’état attendu de l’écran, l’emplacement du trace et la commande CI. La consigne : “avant d’augmenter les timeouts, sépare l’état UI, la réponse API, l’authentification et le locator”.

Cas 4 : erreurs TypeScript en cascade

Vingt erreurs TypeScript peuvent venir d’un seul type d’API modifié.

npx tsc --noEmit --pretty false 2>&1 | tee tsc.log
claude -p "
Read tsc.log and choose the first type error to fix.
Separate derived errors from the likely root cause.
After the fix, verify with npx tsc --noEmit --pretty false.
"

Ne corrigez pas tout en même temps. Corrigez le type racine, relancez la même commande, puis regardez ce qui reste. Ce cycle limite les as any inutiles.

Classer les logs avant de tout lire

Ce petit script est exécutable tel quel et donne une première catégorie.

// triage-log.mjs
import fs from "node:fs";

const sample = `
TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (src/ProductList.tsx:42:18)
`;

const input = process.argv[2]
  ? fs.readFileSync(process.argv[2], "utf8")
  : sample;

const rules = [
  [/ERR_MODULE_NOT_FOUND|Cannot find module/i, "dependency or import path"],
  [/ENOENT/i, "file path or working directory"],
  [/TypeError:.*undefined|Cannot read properties/i, "data shape or initial value"],
  [/Timeout.*expect|locator/i, "E2E wait condition or screen state"],
  [/TS\d{4}/, "TypeScript type error"],
];

const matches = rules
  .filter(([pattern]) => pattern.test(input))
  .map(([, label]) => label);

console.log(matches.length ? matches.join("\n") : "Unclassified: inspect first failure");

node triage-log.mjs
node triage-log.mjs tsc.log

Ce n’est pas un diagnostic complet. Il sépare simplement dépendances, chemins, forme des données, attente E2E et types TypeScript avant la discussion.

Modèle de rapport de bug reproductible

Avant de demander l’enquête, reformatez le bug ainsi. Avec GitHub Issues, la syntaxe officielle GitHub issue forms permet d’en faire un formulaire.

## Summary
Describe the broken behavior in one sentence.

## Failed command
`npm run build`

## Expected result
The build succeeds and creates `dist/`.

## Actual result
The command fails with `TypeError: Cannot read properties of undefined`.

## First failing line
`src/components/ProductList.tsx:42:18`

## Reproduction steps
1. `npm ci`
2. `npm run build`

## Environment
- Node.js: 22.x
- OS: Windows 11 / GitHub Actions ubuntu-latest
- Branch: feature/product-list

## Already tried
- Regenerated lockfile
- Checked API response fixture

## Verification after fix
- `node --test`
- `npm run build`

La phrase clé n’est pas “ça ne marche pas”, mais “ces étapes reproduisent le même échec”.

Pièges fréquents

Premier piège : coller seulement la dernière ligne du log. Gardez la première erreur et les lignes proches.

Deuxième piège : dépendre du texte du message. Dans Node.js, préférez error.code ou name quand ils existent.

Troisième piège : ignorer la reproduction minimale. Dans une page complète, il est difficile de savoir si la cause est vraiment corrigée.

Quatrième piège : corriger sans test de régression. Le bug peut revenir au prochain refactor.

Cinquième piège : donner trop de portée à Claude Code. Demandez le plus petit changement qui fait passer cet échec précis. Pour les limites de revue, voyez la checklist de workflow de revue.

Note de passation

Quand la vérification passe, laissez une note courte.

## Diagnosis note
- Failure: `npm run build`
- Cause: `users.map` was called when the API returned null
- Fix: Normalize non-array input to an empty array in `names()`
- Regression test: `node --test user-list.test.mjs`
- Verification: `npm run build` passed
- Remaining risk: Confirm separately whether API null is intentional

claude -p "
Write a Markdown diagnosis note for this fix.
Include cause, changed files, regression test, verification command,
and remaining risk. Keep it short enough for a reviewer to read in five minutes.
"

Templates et conseil

Pour un projet solo, les commandes et modèles de cet article suffisent. En équipe, il faut définir quels logs peuvent être partagés, quels secrets ne doivent jamais être collés dans Claude Code, où placer les reproductions minimales, quels artifacts CI conserver et quelles preuves la revue exige.

ClaudeCodeLab propose des produits et templates Claude Code ainsi que de la formation et du conseil Claude Code pour standardiser rapports de bugs, prompts de triage CI, tests de régression et notes de passation.

En appliquant ce workflow à la maintenance de ClaudeCodeLab, Masa a surtout gagné grâce à trois habitudes : conserver la première ligne d’échec, créer une reproduction minimale et relancer la même commande. Les suggestions de Claude Code sont devenues vérifiables, avec preuve, hypothèse, test et résultat.