Claude Code Review-Workflow-Checkliste: PR-Risiken vor dem Release finden

Die ersten drei Zeilen bestimmen die Tiefe der Review

Wenn eine Claude-Code-Review oberflächlich wirkt, liegt es selten nur am Modell. Häufig fehlen Scope, riskante Nutzerflüsse, ausgeführte Prüfungen und die Entscheidung, die ein Mensch danach treffen muss.

Ein Review-Workflow bedeutet hier nicht, Claude Code um eine allgemeine Meinung zu bitten. Es geht um eine wiederholbare Abfolge: Diff begrenzen, Risiko benennen, Nachweise anhängen, Findings zuerst verlangen und die finale Release-Entscheidung beim Menschen lassen.

Für Einsteiger: Ein Diff ist die konkrete Änderung im PR. Ein Review Gate ist die Prüfung vor Merge oder Veröffentlichung. Ein Verification Receipt ist der kurze Nachweis aus Commands, Ergebnissen, Screenshots, Logs und Restrisiko. Offizielle Grundlagen stehen in Claude Code overview, common workflows, GitHub pull request reviews und npm scripts. Intern passen die Claude Code Code-Review-Checkliste und der verification receipt workflow dazu.

Kontext vorbereiten, bevor Claude Code den Diff sieht

Claude Code findet mehr Fehler, wenn die Eingabe Scope, Risk, Evidence und Handoff enthält. Ohne diese vier Teile entsteht oft eine gute Zusammenfassung, aber kein belastbarer Release-Check.

Eingabe	Zweck	Schwach	Stark
Scope	Änderung begrenzen	Mehreres korrigiert	Nur Artikel-CTA, Text und mobiler Abstand
Risk	Auswirkung nennen	Sollte passen	Produkt-, Beratungs- und interne Links beeinflussen Umsatz
Evidence	Prüfung zeigen	Lokal angesehen	npm run build erfolgreich, CTA bei 360px geklickt
Handoff	Ausgabe definieren	Bitte prüfen	P1/P2/P3 Findings, Restrisiko und nächste Checks

flowchart LR
  A["Diff"] --> B["Scope and risk"]
  B --> C["Claude Code review"]
  C --> D["Human decision"]
  D --> E["Fix, verify, or ship"]
  E --> F["Review receipt"]

Die wichtigste Grenze: Claude Code ist kein Approver. Es reduziert blinde Flecken, schlägt Tests vor und zeigt schwache Annahmen. Ob gefixt, erneut geprüft oder veröffentlicht wird, entscheidet der PR-Verantwortliche.

Checkliste vor der Review

Sammle zuerst Arbeitsbaum, Diff und Prüfkommandos. Das Beispiel passt zu Node-Projekten; in anderen Stacks ersetzt du die letzten Zeilen durch pytest, go test ./..., bundle exec rspec oder den CI-Standard.

git status --short
git diff --stat
git diff --name-only
npm run build
npm run test -- --runInBand

Diese Checkliste kann in die PR-Beschreibung, nach .github/review-checklist.md oder ins Team-Wiki.

# Claude Code Review Checklist

## Scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] No unrelated formatting, dependency, or generated files are mixed in.

## Risk
- [ ] Risk level is marked as low, medium, or high.
- [ ] User-facing routes, forms, auth, billing, analytics, and CTA paths are named.
- [ ] Rollback or recovery steps are written for high-risk changes.

## Evidence
- [ ] Build, test, lint, or typecheck commands are listed with results.
- [ ] Manual checks include browser width, account state, and actual URL when relevant.
- [ ] Screenshots, logs, or console output are attached for UI and integration changes.

## Review output
- [ ] Findings come first, ordered by severity.
- [ ] Each finding has file reference, reproduction condition, and expected fix.
- [ ] Residual risk is written even when no blocker is found.

Damit prüft Claude Code nicht nur Lesbarkeit, sondern Release-Risiko.

Direkt nutzbarer Review-Prompt

Der Prompt darf kurz sein, solange die Ausgabe streng ist. Wichtig sind bug-finding mindset, findings first und do not rewrite code yet.

Review this diff with a bug-finding mindset.

Scope:
- Only review the files changed in this PR.
- Do not rewrite code yet.

Prioritize:
1. behavioral regressions
2. security, privacy, or permission mistakes
3. missing tests or weak verification
4. broken mobile layout, internal links, product CTA, or training CTA

Return:
- Findings first, ordered by P1/P2/P3 severity
- File and line references when possible
- Why each issue matters to users or revenue
- Checks I should run next
- Residual risk if no blocker is found

Die erste Runde bleibt bewusst read-only. Wenn Claude Code während der Review schon editiert, verliert das Team die klare Liste der Probleme und Prioritäten.

Vier praktische Einsatzfälle

Erster Fall: CTA oder Umsatzpfad. Wenn Artikel-Footer, Produktkarte, Preistext oder Beratungslink geändert werden, prüfe Ziel-URL, Produktzuordnung, Button-Reihenfolge, mobile Darstellung und Analytics-Event. Ein typischer Fehler ist ein Button mit “Templates”, der noch auf ein altes Gumroad-Produkt zeigt. Die Reise sollte konsistent zu /de/products/ und /de/training/ führen.

Zweiter Fall: Authentifizierung, Berechtigungen und private Daten. Ein versteckter UI-Button ist keine serverseitige Autorisierung. Claude Code soll prüfen, wer handeln darf, wer abgelehnt werden muss, ob Logs E-Mail oder Payment-ID enthalten und ob Tests den abgelehnten Nutzer abdecken.

Dritter Fall: mehrsprachige Veröffentlichung. Eine Sprache kann natürlich klingen, während eine andere ein altes updatedDate, einen offenen Code Fence, fehlenden Produktlink oder Mojibake enthält. Nenne die erlaubten Locale-Dateien, die zu erhaltenden Metadata und die Pflicht-Strings.

Vierter Fall: Build- oder Test-Triage. Übergib nicht den kompletten riesigen Log. Besser sind fehlgeschlagenes Kommando, letzte relevante Zeilen, jüngster Diff und bereits getestete Ansätze. Die Falle ist, einen kleinen Build-Fix in Dependency-Churn zu verwandeln.

Häufige Fehler

“Bitte alles reviewen” ist zu breit. Claude Code reagiert dann mit allgemeinen Hinweisen. Besser sind Dateien, Risiken und klare Ausschlüsse.

Der zweite Fehler ist fehlende Evidence. Wenn unklar ist, ob npm run build, Typecheck, Browserpfad oder mobile Ansicht geprüft wurden, rät die Review. Nicht ausgeführte Checks sollten mit Grund genannt werden.

Bei Umsatzpfaden reicht Desktop nicht. CTA-Zeilenumbruch, horizontales Scrollen, echte Zielseiten und die Reihenfolge von /products/ und /training/ müssen sichtbar geprüft werden.

Bei Security gehören API Keys, Tokens, Kunden-E-Mails, Payment IDs und private Inhalte nicht in den Prompt. Logs sollten vorher auf die kleinste reproduzierbare Form reduziert werden.

Verification Receipt per Script prüfen

Dieses Node-Script prüft, ob ein Review Receipt die Pflichtabschnitte und mindestens ein abgehaktes Kommando enthält. Es ersetzt keine menschliche Review, verhindert aber Releases ohne Mindestnachweis.

{
  "requiredSections": ["Scope", "Risk", "Checks run", "Findings", "Residual risk"]
}

#!/usr/bin/env node
const fs = require("node:fs");

const receiptPath = process.argv[2] || "review-receipt.md";
const policyPath = process.argv[3] || "review-policy.json";
const receipt = fs.readFileSync(receiptPath, "utf8");
const policy = fs.existsSync(policyPath)
  ? JSON.parse(fs.readFileSync(policyPath, "utf8"))
  : { requiredSections: ["Scope", "Risk", "Checks run", "Findings", "Residual risk"] };

const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const missingSections = policy.requiredSections.filter((name) => {
  const heading = new RegExp(`^## ${escapeRegExp(name)}\\b`, "m");
  return !heading.test(receipt);
});

const hasCheckedCommand = /^- \[(x|X)\] `(npm|pnpm|yarn|node|pytest|go test|cargo test)/m.test(receipt);

if (missingSections.length || !hasCheckedCommand) {
  for (const section of missingSections) console.error(`Missing section: ${section}`);
  if (!hasCheckedCommand) console.error("Missing checked command evidence such as - [x] `npm run build`");
  process.exit(1);
}

console.log("Review receipt passed.");

# Review receipt

## Scope
Article CTA links and mobile layout only.

## Risk
Medium: product and training links affect revenue.

## Checks run
- [x] `npm run build` passed
- [x] mobile CTA path checked at 360px

## Findings
- P2: Product CTA text and destination mismatch on one locale.

## Residual risk
Analytics event names were not checked in production.

Dasselbe Muster kann in PR-Templates, Claude-Code-Prompts oder leichte CI-Checks wandern.

Nächster Schritt

Einzelne Entwickler starten mit dem kostenlosen Claude Code Cheatsheet, um tägliche Commands und sichere Review-Prompts zu stabilisieren. Wer Review-, Debugging- und Triage-Prompts ständig neu schreibt, nutzt Prompt Templates und /de/products/.

Teams brauchen mehr als einen guten Prompt: CLAUDE.md, Permission-Grenzen, Review Gates, Verification Receipts und klare Approval-Verantwortung. Für die Anpassung an ein echtes Repository ist /de/training/ der passende Einstieg.