Claude-Code-Bug-Report-Vorlage: Vage Fehler reproduzierbar machen

Wenn Claude Code nur “die Seite ist kaputt” oder “Tests schlagen fehl” bekommt, muss es raten. Der erste Patch wirkt vielleicht plausibel, überspringt aber oft Root Cause, Prüfkommando und die Erklärung für Reviewer. Ein guter Bug Report macht aus einem vagen Problem eine reproduzierbare Debugging-Aufgabe.

Diese Vorlage sammelt Symptom, erwartetes Verhalten, tatsächliches Verhalten, minimale Reproduktion, Logs, Umgebung, fehlenden Test, Einschränkungen und PR-Handoff. Sie passt nach dem First Task Runbook, lässt sich mit Debugging-Techniken vertiefen und mit der PR-Qualitätscheckliste abschließen.

Offizielle Referenzen sind die CLI reference, commands reference, common workflows und der GitHub Actions guide. Dort wird klar, wann --verbose, /debug, /feedback, /bug oder PR-Automation sinnvoll sind.

Was ein nützlicher Report enthält

Feld	Inhalt	Nutzen für Claude Code
Symptom	Seite, Befehl, Route oder API	Einstieg in die Suche
Erwartet	Korrekte Produkt- oder UI-Regel	Definition von “behoben”
Tatsächlich	Fehlertext, Status, Layoutbruch, falsche Ausgabe	Fakten statt Vermutung
Reproduktion	Kürzester Weg zum Fehler	Hypothesen prüfen
Umgebung	OS, Runtime, Browser, Branch, Env-Namen	Local-vs-CI-Abweichung
Evidenz	Logs, Screenshot, Stack Trace, fehlender Test	Vorher/Nachher-Beweis
Einschränkung	Erlaubte und verbotene Dateien	Kleinerer Diff
Handoff	Ursache, Prüfung, Risiko, Follow-up	Schnellere Review

Der häufigste Fehler ist fehlendes erwartetes Verhalten. “Fehler weg” ist keine Anforderung. Soll die API eine leere Liste, 400, eine Warnung oder einen Retry liefern? Schreibe eine prüfbare Regel.

Kopierbare Vorlage

Speichere sie als bug-report.md, fülle sie aus und gib sie Claude Code vor der Bearbeitung.

# 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

Das funktioniert für interne Tickets, Support-Handoffs und PR-Kommentare. Wichtig ist, Erfolg zu definieren, bevor Claude Code editiert.

Kontext per Skript sammeln

Branch, Node-Version oder aktueller Diff werden leicht vergessen. Dieses Node-Skript hat keine externen Abhängigkeiten und maskiert offensichtliche Secrets.

// 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)));

Ausführen:

mkdir -p scripts
# Code oben als scripts/collect-bug-context.mjs speichern
node scripts/collect-bug-context.mjs > bug-context.json

Maskierung ist nur Schutzschicht. Keine echten API-Keys, Kundendaten oder vollständigen Produktionslogs einfügen.

Use Case 1: Mobile CTA läuft über

Schwach:

Die mobile Seite ist kaputt.

Nützlich:

Symptom:
  Bei 390px Breite läuft der Pricing-CTA rechts aus dem Viewport.

Expected behavior:
  Beide CTAs stehen untereinander, kein horizontaler Scroll.

Minimum reproduction:
  1. Chrome DevTools auf 390px setzen
  2. Betroffene Seite öffnen
  3. Zum Pricing-Abschnitt scrollen

Evidence:
  document.documentElement.scrollWidth is 412
  Screenshot attached

Constraints:
  Produktlinks und Copy nicht ändern. Nur CSS/Layout prüfen.

Claude Code kann so width, gap, Button-Text und Parent-Container prüfen. Bei monetarisierten Seiten gehören auch products und training zur Verifikation.

Use Case 2: Checkout API liefert 500

Bei APIs braucht Claude Code Payload, erwartete Antwort, echten Fehler und relevante Konfigurationsnamen.

Symptom:
  POST /api/checkout liefert nur bei plan=pro einen 500.

Expected behavior:
  200 mit Payment URL. Wenn Konfiguration fehlt, klare Setup-Fehlermeldung.

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:
  Nutzt STRIPE_SECRET_KEY und PRICE_PRO_ID. Werte nicht einfügen.

Constraints:
  Keine zusätzlichen echten Provider-Calls. Zuerst Config Loading und Input Validation prüfen.

Lass Claude Code drei Hypothesen vergleichen: Config Loading, Request Validation, Price Mapping. Wenn lokal reproduzierbar, gehört der fehlende Test meist in Handler oder Config-Modul.

Use Case 3: Datumsgrenze

Bei Timezone- und Monatsende-Bugs ist ein fehlender Test stärker als ein Screenshot.

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"]);
  });
});

Die Anweisung sollte klar sein: “Lass diesen Test zuerst fehlschlagen und korrigiere ohne lokale Timezone-Abhängigkeit.” Die Falle ist, nur das UI-Label zu ändern und die Aggregationsgrenze falsch zu lassen.

Prompt für die Untersuchung

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

Die offiziellen common workflows empfehlen, Fehler, Reproduktionskommando, Schritte und Intermittenz anzugeben. /debug diagnostiziert die Claude-Code-Sitzung. /feedback und /bug melden Probleme am Claude-Code-Produkt, nicht an deiner App.

PR-Handoff

## 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:

Das passt gut zur Session-Handoff-Vorlage und zu den Testing-Strategien.

Häufige Fallen

Unverbundene Bugs nicht bündeln. Login, Checkout und Layout brauchen getrennte Reproduktionen.

Keine vollständigen Logs einfügen. Zwanzig Zeilen um den Fehler, Request ID und Repro-Kommando reichen oft.

Bei Grenzen, Datenmapping, API-Verträgen oder Permissions nicht ohne fehlenden Test abschließen.

Claude Code nicht “alles anschauen” lassen. Kleine Reproduktion schlägt breite Editierfreigabe.

PR-Handoff nicht überspringen. Reviewer brauchen Ursache, Beweis und Restrisiko.

Monetarisierungspfad mitprüfen

Auf ClaudeCodeLab kann ein Fix CTAs, Produktkarten, Free-PDF-Formulare, Gumroad-Links oder Consultation-Links beschädigen. Wenn Layout oder Produktpfade betroffen sind, gehören sie zur Verifikation.

Einzelne Entwickler passen die kostenlose Checkliste an ihr Repository an. Für wiederverwendbare Prompts, Review Gates und Setup-Materialien siehe products. Teams, die Bug Reports, Claude-Code-Permissions, PR Review und CI-Handoff standardisieren wollen, starten mit training.

Praxisergebnis

Im praktischen Test führten Reports mit Repro-Schritten, erwartetem Verhalten, fehlendem Test und PR-Handoff zu kleineren Diffs und weniger Review-Rückfragen als ein bloßes “bitte fixen”. Der größte Gewinn entstand dadurch, vor dem Editieren drei Hypothesen zu verlangen. Falsche Spuren wurden schnell verworfen, und die Sitzung wurde zu evidenzbasiertem Debugging.