Boucle de triage des erreurs de build avec Claude Code en 15 minutes

Trier avant de demander la correction

Quand un build Node, Astro, Vite ou Next.js échoue, le réflexe est de coller tout le log dans Claude Code et de demander une correction complète. Ce réflexe produit souvent un patch bruyant: première ligne d’échec, stack traces secondaires, sortie du package manager et nettoyage sans rapport se retrouvent mélangés.

Cette boucle applique le modèle de bug report, la checklist de review et le workflow de receipt de vérification aux erreurs de build. Le but n’est pas de tout réparer d’un coup. Le but est de réduire la cause à une hypothèse en 15 minutes, puis de laisser une preuve vérifiable.

Un harness est l’échafaudage de l’agent. Claude Code peut lire le dépôt et raisonner, mais vous décidez quel log compte, quelle hypothèse est autorisée et quelle commande prouve le correctif. Cet échafaudage évite qu’un build fix devienne un refactor large.

flowchart LR
  A[State] --> B[Build log]
  B --> C[First failing line]
  C --> D[One hypothesis]
  D --> E[Small fix]
  E --> F[Proof command]
  F --> G[Receipt]

La boucle de 15 minutes

Découpez le travail en trois blocs de cinq minutes. Le premier bloc capture les preuves sans modifier de fichier: git status, commande de build en échec, première ligne en échec et fichiers liés. Le deuxième bloc choisit une seule hypothèse: dépendance, import path, frontmatter, shape de données, permission, réseau ou attente de test.

Le troisième bloc seulement autorise une modification de code ou de configuration. Après la modification, relancez la commande en échec et gardez la preuve. Pour un site de contenu ou de revenus, un build vert ne suffit pas. Vérifiez aussi URL de l’article, h1, canonical, image hero, CTA, lien produit et lien training. Si le build passe mais casse la conversion, le problème reste réel.

Dans la pratique de Masa, la note finale tient en trois lignes: cause, changement, preuve. Le reviewer doit comprendre pourquoi cette hypothèse a été retenue, ce qui a changé et quelle commande ou URL l’a prouvé. Demander ces trois lignes à Claude Code rend la review plus courte.

Capturer les preuves dans un ordre fixe

Utilisez toujours le même ordre. Sur macOS, Linux ou WSL, cet exemple shell conserve le log et le code de sortie.

git status --short
npm run build 2>&1 | tee build.log
status=${PIPESTATUS[0]}
if [ "$status" -ne 0 ]; then
  grep -Ein "error|failed|ERR_|Cannot|TypeError" build.log | head -n 20
  exit "$status"
fi
npm test -- --runInBand

Sous Windows PowerShell, appelez npm.cmd explicitement afin de limiter les différences entre shells.

$ErrorActionPreference = "Continue"
git status --short
npm.cmd run build *> build.log
$buildExit = $LASTEXITCODE

if ($buildExit -ne 0) {
  Select-String -Path build.log -Pattern "error|failed|ERR_|Cannot|TypeError" |
    Select-Object -First 20
  exit $buildExit
}

npm.cmd test -- --runInBand

Le premier essai n’a pas besoin de réussir. Il doit conserver la première erreur utile. La dernière trace peut être un effet secondaire; la première ligne d’erreur est souvent plus proche de la racine.

Classer la première erreur avec Node

Enregistrez ce script dans scripts/triage-build-log.mjs, puis lancez node scripts/triage-build-log.mjs build.log. Il ne corrige rien; il réduit un grand log à une famille et à une prochaine action.

#!/usr/bin/env node
import { readFileSync } from "node:fs";

const logPath = process.argv[2];

if (!logPath) {
  console.error("Usage: node scripts/triage-build-log.mjs build.log");
  process.exit(1);
}

const rules = [
  { name: "dependency or import path", regex: /Cannot find module|ERR_MODULE_NOT_FOUND|Cannot resolve/i },
  { name: "runtime null or shape mismatch", regex: /TypeError:.*undefined|undefined is not|Cannot read/i },
  { name: "test expectation drift", regex: /Expected.*received|AssertionError|Snapshot/i },
  { name: "permission or sandbox boundary", regex: /EACCES|EPERM|permission denied/i },
  { name: "Astro content or frontmatter", regex: /frontmatter|content collection|InvalidContentEntry|MDX/i },
];

const lines = readFileSync(logPath, "utf8").split(/\r?\n/);
const firstFailure = lines.find((line) => /error|failed|ERR_|Cannot|TypeError/i.test(line));
const matchedRule = rules.find((rule) => firstFailure && rule.regex.test(firstFailure));

console.log(JSON.stringify({
  firstFailure: firstFailure || "No obvious failure line found",
  bucket: matchedRule ? matchedRule.name : "needs manual reading",
  nextDiagnostic: matchedRule
    ? "Run one command that proves or disproves this bucket before editing files."
    : "Read the 30 lines before the first failure and classify manually.",
}, null, 2));

Cette classification n’a pas besoin d’être parfaite. Elle transforme le prompt de “répare le build” en “prouve ou élimine cette famille avant d’éditer”. Cela limite les upgrades de dépendances, les null checks trop larges et les nettoyages qui masquent la cause.

Fixer les frontières avec les docs officielles

Les problèmes de connexion, authentification, quotas ou messages runtime de Claude Code relèvent de Claude Code Error reference. Si CLAUDE.md, settings, hooks ou MCP ne semblent pas chargés, consultez Debug your configuration.

Pour un site Astro, les erreurs de frontmatter et de content collections doivent être comparées à Astro Content Collections. Pour les codes Node comme ERR_MODULE_NOT_FOUND, utilisez Node.js Errors. Cette séparation évite de traiter un problème de build applicatif comme un problème Claude Code, ou l’inverse.

Première action selon le log

Forme du log	Suspicion initiale	Première action
Cannot find module	import path, fichier généré, dépendance	Vérifier fichier et chemin avant d’installer
ERR_MODULE_NOT_FOUND	ESM/CJS, extension, package exports	Comparer erreur Node et configuration package
undefined is not	data shape, frontmatter, réponse API	Afficher un vrai enregistrement avant les null checks
Expected ... received	changement de spec, fixture, snapshot	Classer changement voulu ou régression
permission denied	sandbox, utilisateur CI, chemin d’écriture	Vérifier working directory et permissions
seulement Build failed	première erreur en amont	Extraire le premier error, pas la dernière trace

Dans un site Astro, undefined is not an object peut venir d’un heroImage, pubDate ou lang absent dans une locale. Un guard global peut faire passer le build tout en cachant un problème éditorial.

Prompt copiable pour Claude Code

Lis ce build log en échec.
Ne propose pas de refactors larges.
N'édite pas encore les fichiers.

Retourne:
1. première ligne en échec
2. une cause la plus probable
3. commande diagnostic minimale pour cette cause
4. plus petit changement code ou config autorisé
5. commande de preuve après correction
6. trois lignes pour PR: cause, changement, preuve

Dans un dépôt partagé, ajoutez le périmètre: inspecter seulement ce slug, ne pas toucher aux reports, ne pas revenir sur les changements non liés et préserver les champs d’identité du frontmatter. Ce cadre évite les conflits avec d’autres travailleurs.

Quatre cas d’usage pratiques

Premier cas: un site Astro multilingue. Une locale avec frontmatter invalide, une code fence MDX non fermée, une image hero manquante ou un lien interne faux peut casser le build. Demandez à Claude Code de comparer seulement les dix fichiers du slug et de valider YAML, fences et longueur du corps.

Deuxième cas: un import Node CLI ou package qui échoue. Cannot find module ne signifie pas toujours dépendance manquante. Cela peut être une faute de frappe, un fichier généré absent, une règle exports ou un mélange ESM/CJS. Avant de changer les dépendances, lancez node -p "require.resolve('package-name')" ou une vérification de fichier.

Troisième cas: échec seulement en CI. Les causes fréquentes sont permissions, chemins sensibles à la casse, version Node différente, secret mal nommé ou proxy absent. Avant de toucher au code applicatif, listez OS CI, working directory, version Node, variables et chemins d’écriture.

Quatrième cas: dérive d’attente de test. Expected ... received se masque facilement avec un snapshot update, mais cela peut valider une régression. Pour CTA, prix, liens Gumroad, formulaires training ou metadata, vérifiez d’abord si le changement est voulu.

Pièges concrets

Premier piège: lire seulement la fin du log. La trace finale peut être une conséquence. Gardez la première ligne d’échec et les 30 lignes avant.

Deuxième piège: mettre à jour les dépendances trop tôt. Un update touche lockfile, cache CI et compatibilité runtime. Si la cause était un import path, le patch devient inutilement lourd.

Troisième piège: s’arrêter au build vert. Un site public doit aussi confirmer /en/products/, /en/training/, le formulaire PDF gratuit, h1 et canonical.

Quatrième piège: accepter le nettoyage opportuniste. Un PR de build-fix doit garder son hypothèse visible. Si formatting, refactor, dépendances et contenu se mélangent, la preuve disparaît.

CTA produits et formation

Pour transformer cette boucle en prompts, checklists et matériel réutilisable, commencez par ClaudeCodeLab products. Si votre équipe doit définir CI gates, CLAUDE.md, règles de permissions, receipts de review et vérification de production sur un vrai dépôt, utilisez Claude Code training and consultation.

À lire ensuite: permission audit checklist et CI/CD setup. En solo, un PDF gratuit suffit pour fixer les commandes. En équipe, il faut un prompt commun, un format de preuve commun et un responsable clair des approbations.

Résultat après essai

Avec cette boucle, le diff devient plus petit. Au lieu de donner tout le log à Claude Code, la session commence par une ligne d’échec, une hypothèse et une commande de preuve. Cela sépare plus vite frontmatter manquant, fichier généré absent, import path erroné et permission CI. La vraie valeur est le receipt bref qui reste pour la prochaine erreur.