Modèle de bug report Claude Code : transformer un bug vague en correctif reproductible

Si vous dites seulement à Claude Code « la page est cassée » ou « les tests échouent », il doit deviner. Le premier patch peut sembler plausible, mais il risque d’ignorer la cause racine, la commande de vérification et le contexte attendu par la personne qui relit la PR. Un bon bug report transforme un problème flou en tâche reproductible.

Ce guide donne un modèle concret pour Claude Code : symptôme, comportement attendu, comportement réel, reproduction minimale, logs, environnement, test en échec, contraintes et passation de PR. Utilisez-le après le runbook de première tâche, complétez avec les techniques de debugging et terminez avec la checklist de qualité PR.

Gardez aussi les documents officiels à portée de main : CLI reference, commands reference, common workflows et GitHub Actions guide. Ils clarifient l’usage de --verbose, /debug, /feedback, /bug et des automatisations PR.

Ce qu’un rapport utile doit contenir

Champ	À écrire	Utilité pour Claude Code
Symptôme	Page, commande, route ou API concernée	Point d’entrée
Attendu	Règle métier ou UI correcte	Définition de “corrigé”
Réel	Message d’erreur, statut, rendu cassé, sortie fausse	Faits, pas hypothèses
Reproduction	Chemin minimal qui échoue vite	Vérifier les hypothèses
Environnement	OS, runtime, navigateur, branche, noms d’env	Différences local/CI
Preuves	Logs, captures, stack trace, test en échec	Avant/après
Contraintes	Ce qu’on peut modifier ou non	Diff plus petit
Passation	Cause, vérification, risque, suite	Review plus rapide

L’oubli le plus fréquent est le comportement attendu. « Supprimer l’erreur » n’est pas une règle. L’API doit-elle renvoyer une liste vide, un 400, un message utilisateur ou refaire une tentative ? Écrivez une phrase vérifiable.

Modèle à copier

Enregistrez ceci dans bug-report.md, remplissez-le, puis donnez-le à Claude Code avant de demander une modification.

# Bug report for Claude Code

## Goal
- Bug to fix:
- Desired outcome:
- Out of scope:

## Environment
- OS:
- Node / package manager:
- Browser / device:
- Branch:
- Relevant env var names, not values:

## Symptom
- Where it happens:
- Who sees it:
- Frequency: always / intermittent / unknown

## Expected behavior
-

## Actual behavior
-

## Minimum reproduction
1.
2.
3.

## Evidence
- Error message:
- Logs:
- Screenshot:
- Failing command:

## Recent changes
- PR / commit:
- Likely files:

## Constraints
- Allowed scope:
- Do not touch:
- Do not paste secrets or customer data:

## Request to Claude Code
1. Do not patch immediately
2. List the top three hypotheses
3. Propose the smallest check that could disprove each hypothesis
4. Create a minimum reproduction or failing test first
5. Apply the smallest useful fix
6. Report verification commands and remaining risk

Ce format fonctionne pour tickets internes, support et commentaires de PR. L’objectif est de définir le succès avant l’édition.

Script exécutable pour collecter le contexte

On oublie vite la branche, la version Node ou le diff actuel. Ce script Node sans dépendance collecte l’essentiel et masque les secrets évidents.

// scripts/collect-bug-context.mjs
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { platform, release } from "node:os";
import { cwd } from "node:process";

function run(command, args) {
  try {
    return execFileSync(command, args, {
      cwd: cwd(),
      encoding: "utf8",
      stdio: ["ignore", "pipe", "pipe"],
    }).trim();
  } catch (error) {
    return `(failed: ${command} ${args.join(" ")})`;
  }
}

function maskSecrets(text) {
  return text
    .replace(/(api[_-]?key|token|secret|password)=([^\\s]+)/gi, "$1=***")
    .replace(/Bearer\\s+[A-Za-z0-9._-]+/g, "Bearer ***");
}

function readPackageScripts() {
  if (!existsSync("package.json")) return "package.json not found";
  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
  return JSON.stringify(pkg.scripts ?? {}, null, 2);
}

const report = {
  generatedAt: new Date().toISOString(),
  cwd: cwd(),
  os: `${platform()} ${release()}`,
  node: process.version,
  branch: run("git", ["branch", "--show-current"]),
  status: run("git", ["status", "--short"]),
  lastCommit: run("git", ["log", "-1", "--oneline"]),
  diffStat: run("git", ["diff", "--stat"]),
  packageScripts: readPackageScripts(),
};

console.log(maskSecrets(JSON.stringify(report, null, 2)));

Exécution :

mkdir -p scripts
# Enregistrez le code ci-dessus dans scripts/collect-bug-context.mjs
node scripts/collect-bug-context.mjs > bug-context.json

Le masquage reste une protection légère. Ne collez pas de vraies clés API, données clients ou logs de production complets.

Cas 1 : CTA mobile qui déborde

Mauvais rapport :

La page mobile est cassée.

Rapport utile :

Symptom:
  À 390px de largeur, le CTA pricing dépasse à droite.

Expected behavior:
  Les deux CTAs se placent en colonne, sans scroll horizontal.

Minimum reproduction:
  1. Ouvrir Chrome DevTools à 390px
  2. Ouvrir la page concernée
  3. Aller à la section pricing

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  Ne pas modifier les liens ni le texte produit. Inspecter seulement CSS/layout.

Claude Code peut alors vérifier width, gap, texte du bouton et conteneurs parents. Sur une page monétisée, vérifiez aussi les chemins vers products et training.

Cas 2 : API checkout en 500

Pour une API, il faut la forme de requête, la réponse attendue, l’erreur réelle et les noms de configuration.

Symptom:
  POST /api/checkout renvoie 500 seulement avec plan=pro.

Expected behavior:
  Renvoie 200 avec une payment URL. Si la configuration manque, erreur de setup explicite.

Actual behavior:
  TypeError: Cannot read properties of undefined (reading 'prices')

Minimum reproduction:
  curl -X POST http://localhost:3000/api/checkout \
    -H "content-type: application/json" \
    -d '{"plan":"pro"}'

Environment:
  Utilise STRIPE_SECRET_KEY et PRICE_PRO_ID. Ne pas coller les valeurs.

Constraints:
  Ne pas ajouter d'appels réels au provider. Vérifier d'abord configuration et validation.

Demandez à Claude Code de comparer trois hypothèses : chargement config, validation request, mapping des prix. Si la reproduction est locale, le test en échec peut souvent être au niveau handler ou module de config.

Cas 3 : régression de limite de date

Pour les bugs de timezone et fin de mois, un test en échec vaut mieux qu’une capture.

import { describe, expect, it } from "vitest";
import { exportMonthlyOrderIds } from "../src/export-orders";

describe("exportMonthlyOrderIds", () => {
  it("includes March orders and excludes April 1 UTC", () => {
    const orders = [
      { id: "mar-start", createdAt: "2026-03-01T00:00:00.000Z" },
      { id: "mar-end", createdAt: "2026-03-31T23:59:59.999Z" },
      { id: "apr-start", createdAt: "2026-04-01T00:00:00.000Z" },
    ];

    expect(exportMonthlyOrderIds(orders, "2026-03")).toEqual(["mar-start", "mar-end"]);
  });
});

La consigne doit être claire : « Fais échouer ce test d’abord, puis corrige sans dépendre de la timezone locale. » Le piège est de corriger seulement le libellé UI en laissant le calcul faux.

Prompt d’investigation

Read bug-report.md and bug-context.json.

Process:
1. Do not edit yet
2. Separate facts from guesses
3. Rank the top three root-cause hypotheses
4. Propose the smallest check that could disprove each one
5. Create a minimum reproduction or failing test first
6. After approval, make the smallest useful fix

Done means:
- The expected/actual gap is explained
- A failing test or reproduction command remains
- Verification commands are reported
- The PR handoff includes root cause, fix, risk, and follow-up

Les common workflows officiels recommandent de donner l’erreur, la commande de reproduction, les étapes et le caractère intermittent ou non. /debug sert à diagnostiquer une session Claude Code. /feedback et /bug servent à remonter un problème du produit Claude Code, pas de votre application.

Modèle de passation PR

## Root cause
-

## Fix
-

## Regression coverage
- Added failing test:
- Manual reproduction checked:

## Verification
- [ ] npm test
- [ ] npm run typecheck
- [ ] npm run build
- [ ] mobile / desktop visual check if UI changed

## Risk
-

## Claude Code notes
- Hypotheses rejected:
- Files intentionally not touched:
- Follow-up issue:

Ce modèle complète bien le handoff de session et les stratégies de test.

Pièges à éviter

Ne mélangez pas des bugs sans lien. Login, checkout et layout demandent des reproductions séparées.

Ne collez pas des logs complets. Vingt lignes autour de l’erreur, request ID et commande de reproduction suffisent souvent.

Ne terminez pas sans test en échec quand le bug touche des limites, mappings de données, contrats API ou permissions.

Ne demandez pas à Claude Code de « tout regarder ». Une petite reproduction vaut mieux qu’un droit large de modifier.

Ne sautez pas la passation PR. Le reviewer a besoin de la cause, de la preuve et du risque restant.

Inclure le chemin de monétisation

Sur ClaudeCodeLab, un correctif peut casser CTA, cartes produit, formulaire PDF gratuit, liens Gumroad ou consultation. Si vous modifiez le layout ou les chemins produit, incluez-les dans la vérification.

Pour un usage individuel, adaptez la checklist gratuite à votre dépôt. Pour des prompts réutilisables, review gates et supports de setup, consultez products. Pour une équipe qui doit standardiser bug reports, permissions Claude Code, PR review et handoff CI, commencez par training.

Résultat pratique

En test réel, les rapports avec reproduction, attendu, test en échec et passation PR ont donné des diffs plus petits et moins de questions en review qu’un simple « corrige ça ». Le meilleur gain vient de la demande de trois hypothèses avant l’édition : les mauvaises pistes sont éliminées vite, et la session devient un debugging fondé sur des preuves.