Décodeur d'erreurs Claude Code : transformer les logs en correctifs reproductibles

Quand on débute avec Claude Code, on a vite envie de coller une grosse erreur et de demander : “corrige ça”. Parfois cela marche, mais ce n’est pas une méthode fiable. Claude Code ne connaît pas automatiquement la commande exécutée, les variables d’environnement, les versions installées ni les différences entre votre machine et la CI. La bonne méthode consiste à transformer l’erreur en rapport reproductible, puis à demander des hypothèses, les prochaines commandes et un plan de vérification.

Ce guide couvre les stack traces, les erreurs TypeScript, les logs runtime Node.js, Docker/Kubernetes et les échecs GitHub Actions. Pour les références officielles, gardez sous la main Claude Code common workflows, Claude Code troubleshooting et Claude Code settings.

Le principe : reproduire avant de conclure

Un message d’erreur est une preuve, pas une devinette. Il faut préserver le signal et réduire le bruit sans supprimer l’information utile.

flowchart TD
  A["Sauver la sortie de la commande échouée"] --> B["Réduire le bruit sans supprimer le log complet"]
  B --> C["Demander hypothèses et étapes de reproduction"]
  C --> D["Créer le plus petit cas qui échoue"]
  D --> E["Corriger puis relancer la même commande"]
  E --> F["Ajouter prévention : test, checklist ou CLAUDE.md"]

Source	Ce qu’on donne à Claude Code	Ce qu’on demande	Ce qu’on vérifie
TypeScript	Sortie complète `tsc --noEmit --pretty false` et chemins	Contrat de types cassé, correctif sûr, piège à éviter	Pas de `any`, pas de `ts-ignore`
Stack trace Node.js	Première ligne Error, frames applicatifs, entrée utilisée	Premier frame utile, état nécessaire	Même entrée reproduit localement
Docker/Kubernetes	`describe`, logs précédents, events	OOM, env, probe, image ou erreur applicative	Ligne de preuve et commande `kubectl`
GitHub Actions	Log du job échoué et fichiers modifiés	Step échouée, commande locale, différences CI	Local et CI passent

Cas 1 : sauvegarder les erreurs npm et tsc

Ne copiez pas seulement les dernières lignes. Sauvegardez d’abord la sortie complète.

mkdir -p tmp/error-cases
npm test 2>&1 | tee tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | tee tmp/error-cases/tsc.log

Puis demandez un plan de diagnostic.

claude -p "
I need a reproducible fix, not a guess.

Read these files if they exist:
- tmp/error-cases/test.log
- tmp/error-cases/tsc.log

Return:
1. One-line failure summary
2. Likely root cause with confidence level
3. Minimal reproduction steps
4. Next 3 commands to run
5. Smallest safe code change to try
6. Verification command after the fix

Do not hide TypeScript errors with any or ts-ignore.
"

Le niveau de confiance est important. Si Claude Code n’est sûr qu’à 60%, la prochaine commande de vérification vaut mieux qu’un patch affirmatif.

Cas 2 : réduire une stack trace Node.js

Les stack traces Node.js sont souvent noyées par node_modules. Gardez le log original, puis créez une copie courte.

// scripts/minimize-stacktrace.mjs
import { readFileSync } from "node:fs";

const input = readFileSync(0, "utf8");
const lines = input.split(/\r?\n/);
const kept = [];
let dependencyFrames = 0;

for (const line of lines) {
  const isStackFrame = /^\s+at /.test(line);
  const isDependencyFrame = line.includes("node_modules");

  if (!isStackFrame || !isDependencyFrame || dependencyFrames < 3) {
    kept.push(line);
  }

  if (isStackFrame && isDependencyFrame) {
    dependencyFrames += 1;
  }
}

const important = kept.filter((line) =>
  /Error:|TypeError:|ReferenceError:|SyntaxError:|Caused by:|^\s+at |src\/|app\/|packages\//.test(line)
);

console.log(important.slice(0, 80).join("\n"));

node scripts/minimize-stacktrace.mjs < tmp/error-cases/test.log > tmp/error-cases/test.min.log

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask for the full log instead of guessing.

Explain:
- Which application frame is the first useful frame
- What input or state is needed to reproduce it
- Whether this looks like async timing, null data, missing env, or dependency mismatch
- The smallest test that would fail before the fix
"

Ce script ne remplace pas l’analyse. Il rend simplement le premier frame applicatif plus visible.

Cas 3 : lire TypeScript comme un contrat cassé

Type X is not assignable to type Y signifie souvent qu’un appelant fournit une forme de données différente de celle attendue par la fonction appelée. C’est un contrat cassé.

claude -p "
Explain this TypeScript error as a broken contract between caller and callee.

Use this output:
$(npx tsc --noEmit --pretty false 2>&1)

Return a table with:
- Error location
- Plain French explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

Do not suggest any, ts-ignore, or disabling strict mode unless there is no other option.
"

Cette demande sépare le vrai correctif de la simple suppression d’erreur. Avec User | null, il faut souvent gérer l’état déconnecté, valider l’API ou corriger les données de test, pas forcer un cast.

Cas 4 : transformer les logs Kubernetes en commandes de confirmation

CrashLoopBackOff est un symptôme. Collectez description, logs précédents et événements.

kubectl get pod -n app
kubectl describe pod web-abc123 -n app > tmp/error-cases/pod.describe.txt
kubectl logs web-abc123 -n app --previous > tmp/error-cases/pod.previous.log
kubectl get events -n app --sort-by=.lastTimestamp > tmp/error-cases/events.log

claude -p "
Triage this Kubernetes crash.

Files:
- tmp/error-cases/pod.describe.txt
- tmp/error-cases/pod.previous.log
- tmp/error-cases/events.log

Return:
1. Most likely category: OOMKilled, missing env, image pull, app exception, probe failure, or dependency outage
2. Evidence lines from the logs
3. One kubectl command to confirm each remaining hypothesis
4. Temporary mitigation
5. Permanent fix
6. Rollback check

If evidence is insufficient, say what command is missing.
"

Sans ligne de preuve, la réponse reste une hypothèse.

Cas 5 : trier les échecs GitHub Actions

Les logs CI cachent souvent la première erreur derrière des sorties secondaires. Récupérez le log et demandez la reproduction locale.

gh run list --limit 5
gh run view RUN_ID --log > tmp/error-cases/github-actions.log

claude -p "
You are triaging a GitHub Actions failure.

Analyze tmp/error-cases/github-actions.log and return:
1. Failed job and failed step
2. Exact command that failed
3. Whether this should reproduce locally
4. Local reproduction command
5. CI-only differences to inspect: Node version, env vars, cache, timezone, OS, permissions
6. Smallest patch to try
7. Verification plan for local and CI

Do not assume the root cause if the log only shows a downstream symptom.
"

Le prompt aide pour les tests intermittents, les fuseaux horaires, les secrets absents, le cache et les permissions.

Modèle de rapport de bug

# Bug report: short title

## Goal
What I was trying to do:

## Environment
- OS:
- Node version:
- Package manager:
- Branch:
- Commit:

## Exact command
```bash
paste the exact command here
```

## Expected result
What should have happened:

## Actual result
What happened instead:

## Logs
Paste the full error or attach the saved log file path.

## Minimal reproduction
Smallest steps that still fail:

## What I already tried
- Attempt 1:
- Attempt 2:

## Verification plan
Command that must pass after the fix:

Pièges fréquents

Ne collez pas seulement les trois dernières lignes. La cause réelle se trouve souvent au milieu.

N’oubliez pas la commande exacte. npm test, npm run build et vitest --run src/foo.test.ts ne racontent pas la même histoire.

N’acceptez pas any, ts-ignore ou la suppression de tests comme correctif TypeScript par défaut. Ce sont parfois des rustines, pas une stratégie.

Ne collez pas de secrets. Retirez clés API, cookies, JWT et URLs de base de données. En équipe, vérifiez les permissions dans settings.

Après le correctif, relancez d’abord la commande qui échouait. Ensuite seulement, élargissez à lint, build et CI.

Formation, templates et conseil

Pour un usage individuel, ces prompts suffisent pour commencer. En équipe, le vrai sujet est de standardiser les logs partageables, les correctifs interdits, le triage CI et les preuves attendues en review.

ClaudeCodeLab propose des produits et templates Claude Code ainsi que de la formation et du conseil Claude Code pour formaliser prompts de debug, modèles de bug report, checklists CI et règles CLAUDE.md.

Conclusion

Le but n’est pas de faire deviner Claude Code plus fort. Le but est de fournir assez de preuves pour obtenir une prochaine étape reproductible. Sauvegardez la commande, conservez le log complet, réduisez le bruit, demandez le niveau de confiance et vérifiez avec la même commande.

Après avoir testé ce flux dans la maintenance réelle de ClaudeCodeLab, Masa a constaté le plus gros gain dans les dix premières minutes de débogage. Sauvegarder tsc --pretty false, réduire les stack traces sans supprimer le log original et découper les échecs CI en job, step, command et reproduction rend les suggestions de Claude Code vérifiables au lieu de simplement plausibles.