Pull-Request-Qualität mit Claude Code verbessern

Ein Pull Request ist der Ort, an dem ein Team Änderungen vorschlägt, prüft und zusammenführt. Die GitHub-Dokumentation beschreibt PRs als zentrale Kollaborationsfläche. Genau das wird wichtiger, wenn Claude Code die Implementierung beschleunigt. Der Engpass verschiebt sich: Nicht das Schreiben von Code ist das Problem, sondern die saubere Verpackung der Änderung. Schwache Beschreibung, riesiger diff, fehlende Testnachweise, unklare Sicherheitsauswirkungen und wiederholte Review-Schleifen kosten dann Zeit.

Dieser Leitfaden nutzt Claude Code als Assistent für PR-Qualität, nicht nur als Textgenerator. diff bedeutet die geänderten Codezeilen, CI ist das automatische Build- und Testtor, ein diff-size budget ist eine Obergrenze für PR-Größe, und handoff meint die kurze Übergabenotiz für den nächsten Reviewer. Passende Grundlagen findest du in Claude Code Code Review und Claude Code Testing Strategies.

flowchart LR
  A["Mit Claude Code implementieren"] --> B["PR-Template ausfüllen"]
  B --> C["Diff-Größe in CI begrenzen"]
  C --> D["Testnachweise ergänzen"]
  D --> E["Review-Handoff vorbereiten"]
  E --> F["Release Notes entwerfen"]

Offizielle Quellen für diesen Workflow sind GitHub Pull Requests, Pull-Request-Templates, GitHub Actions Workflow Syntax, Protected Branches, Secrets in GitHub Actions, Claude Code Docs und, falls ihr Commit-Kategorien nutzt, Conventional Commits.

Den Qualitätsstandard ins PR-Template schreiben

Wenn du Claude Code jedes Mal bittest, “eine gute PR-Beschreibung” zu schreiben, schwankt das Ergebnis. Stabiler ist ein Template im Repository: .github/pull_request_template.md. GitHub kann diesen Inhalt beim Erstellen eines PR automatisch in den Body einfügen. Damit liegt der Review-Vertrag nicht in Chatverläufen, sondern im Codebestand.

## Was wurde geändert
<!-- Implementierung, Konfiguration, Dokumentation und generierte Dateien trennen. -->

## Warum ist die Änderung nötig
<!-- Issue, Incident, Nutzerwunsch oder Designentscheidung verlinken. -->

## Review-Fokus
- [ ] Fachlogik
- [ ] UI/UX
- [ ] API- oder Datenbankvertrag
- [ ] Sicherheit und Datenschutz

## Testnachweise
- [ ] Automatische Tests:
- [ ] Manuelle Prüfung:
- [ ] Screenshots oder Aufnahme:

## Diff-Größe
- Geänderte Dateien:
- Hinzugefügte/gelöschte Zeilen:
- Warum nicht aufgeteilt:

## Sicherheit und Betrieb
- [ ] Keine Secrets, Tokens oder personenbezogenen Daten
- [ ] Logs geben keine Zugangsdaten oder personenbezogenen Daten aus
- [ ] Berechtigungen, Umgebungsvariablen und Feature Flags geprüft
- [ ] Rollback-Plan dokumentiert

## Handoff für Reviewer
<!-- Zuerst zu lesende Dateien, offene Entscheidungen, Risiken und Folge-PRs. -->

Besonders wertvoll sind “warum nicht aufgeteilt” und “Rollback-Plan”. Sind diese Felder leer, ist der PR oft zu breit oder für den Betrieb nicht sauber erklärt. Claude Code darf das Template füllen; das Template bestimmt aber, was reviewfähig ist.

PR-Text aus Fakten generieren

Nach dem Template sollte Claude Code nur noch den diff auswerten und die Felder füllen. Der Prompt muss Spekulationen verbieten. Nicht ausgeführte Tests werden als “nicht ausgeführt” markiert, nicht als Erfolg formuliert.

git diff origin/main...HEAD | claude -p "
Lies diesen diff und erstelle den Pull-Request-Body nach .github/pull_request_template.md auf Deutsch.

Regeln:
- Keine Fakten erfinden, die im diff nicht sichtbar sind
- Wenn Testnachweise fehlen, 'nicht ausgeführt' schreiben
- Fachbegriffe beim ersten Auftreten kurz erklären
- Review-Fokus auf höchstens 3 wichtigste Dateien oder Bereiche begrenzen
- Secrets, Tokens, personenbezogene Daten und riskante Logs prüfen
- Am Ende offene Punkte nennen, die ein Mensch bestätigen muss
"

So wird aus der Beschreibung eine Lesekarte. Reviewer beginnen bei der Autorisierungsfunktion, dem geänderten Screen oder der Migration statt beim gesamten Branch. Claude Code liest schnell, aber die Verantwortung für die Aussage bleibt beim Autor.

PR-Größe in CI erzwingen

Große PRs senken die Review-Tiefe. Claude Code kann in einem Lauf umbenennen, formatieren, refactoren, Tests ergänzen und Dokumentation schreiben. Das ist praktisch, vermischt aber Ziele. Ein diff-size budget macht die Grenze messbar.

Für Node-Projekte eignet sich scripts/check-pr-size.mjs. Das Skript ignoriert Lockfiles und generierte Ausgaben und zählt nur die für Reviewer relevanten Änderungen.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";

const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
  process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);

const ignored = [
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^dist\//,
  /^coverage\//,
];

function numeric(value) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : 0;
}

const output = execFileSync("git", ["diff", "--numstat", range], {
  encoding: "utf8",
}).trim();

let files = 0;
let lines = 0;

for (const row of output.split(/\r?\n/).filter(Boolean)) {
  const [added, deleted, file] = row.split("\t");
  if (ignored.some((pattern) => pattern.test(file))) continue;
  files += 1;
  lines += numeric(added) + numeric(deleted);
}

if (files > maxFiles || lines > maxLines) {
  console.error(
    `PR is too large: ${files} files / ${lines} changed lines. ` +
      `Budget is ${maxFiles} files / ${maxLines} lines.`,
  );
  console.error("Split formatting, generated files, and behavior changes into separate PRs.");
  process.exit(1);
}

console.log(`PR size OK: ${files} files / ${lines} changed lines.`);

Danach kommt der GitHub-Actions-Workflow. Workflow-Dateien liegen unter .github/workflows. Später kannst du diesen Job als required status check für eine protected branch konfigurieren.

name: PR quality

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run project checks
        run: |
          npm run lint --if-present
          npm test --if-present

      - name: Enforce PR size budget
        run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35

Die Werte sind Teamentscheidung. Als Einstieg funktionieren 700 geänderte Zeilen und 35 Dateien gut. Migrationen oder mechanische Refactorings können Ausnahmen bekommen, müssen sie aber im PR erklären.

Testnachweise reproduzierbar machen

“Tests grün” ist zu ungenau. Reviewer brauchen Befehle, Resultate, manuelle Prüfungen, Screenshots bei UI-Änderungen und eine Liste offener Prüfungen. Claude Code kann diese Sektion formatieren, darf aber nicht so tun, als sei ein nicht ausgeführter Befehl erfolgreich gewesen.

claude -p "
Bereite die Testnachweise für den Pull Request dieses Branches vor.

Format:
## Automatische Tests
- Befehl:
- Ergebnis:
- Fehlerursache, falls vorhanden:

## Manuelle Prüfung
- Geprüfter Screen, API oder Job:
- Eingabedaten:
- Erwartetes Ergebnis:
- Tatsächliches Ergebnis:

## Nicht geprüft
- Noch offene Punkte:
- Wer sie vor dem Merge prüfen soll:

Nur Fakten schreiben. Nicht ausgeführte Befehle nicht als bestanden markieren.
"

Es gibt mindestens drei typische Fälle. UI-PRs brauchen Screenshots, Viewport-Größen und Accessibility-Hinweise. API-PRs brauchen Kompatibilität, Fehlerfälle und Logverhalten. Migrationen oder Batch-Jobs brauchen dry run, Rollback und Laufzeitabschätzung. Diese Einordnung spart Review-Zeit.

Sicherheit und Datenschutz pro PR prüfen

KI-unterstützte Änderungen können mehr Dateien berühren als erwartet. Secrets können in Beispielen, Logs, Fixtures oder Screenshots landen. GitHub Actions secrets sind für sensitive Workflow-Werte gedacht, aber nicht zum Ausgeben in Logs oder PR-Text.

Prüfe diesen diff auf Sicherheits- und Datenschutzrisiken.

Checkliste:
1. Secrets, Tokens, API Keys, Cookies und Session IDs
2. Personenbezogene Daten in Logs, Fixtures, Screenshots oder Fehlermeldungen
3. Berechtigungsprüfung serverseitig, nicht nur in der UI
4. Zu breite GitHub-Actions-permissions
5. Fehlermeldungen mit internen Pfaden oder Zugangsdaten
6. Feature Flags oder Umgebungsvariablen, die den Rollout ändern

Gib High/Medium/Low-Schweregrad und konkrete Dateinamen aus.
Liste auch verdächtige Bereiche, die du nicht bestätigen kannst.

Der letzte Satz ist wichtig. In Sicherheitsreviews ist eine saubere Liste unsicherer Stellen oft wertvoller als ein vorschnelles “keine Probleme gefunden”.

Review-Handoff und Antworten strukturieren

Ein gutes handoff verhindert, dass der nächste Reviewer die ganze Diskussion erneut lesen muss. Das hilft bei verteilten Teams, lang laufenden PRs und Review-Rotationen. Übergib Claude Code Kommentare und diff-Statistik.

PR_NUMBER=123
{
  gh pr view "$PR_NUMBER" --comments
  gh pr diff "$PR_NUMBER" --stat
} | claude -p "
Schreibe eine Review-Handoff-Notiz für diesen Pull Request.

Enthalten:
- Zweck in höchstens zwei Sätzen
- Bis zu 3 Dateien, die zuerst gelesen werden sollen
- Bereits erledigte Review-Kommentare
- Kommentare mit noch offener Entscheidung
- CI-, manuelle Test- und Release-Risiken

Die Notiz soll in unter fünf Minuten verständlich sein.
"

Auch Kommentarantworten brauchen Präzision. “Gefixt” reicht selten. Eine gute Antwort sagt, was geändert wurde, in welcher Datei, welcher Test es abdeckt und warum eine Empfehlung nicht übernommen wurde. Claude Code kann den Entwurf liefern; defensive oder spekulative Sätze streichst du.

Gemergte PRs in Release Notes überführen

PR-Qualität wirkt bis in den Release. Wenn ein PR-Body nicht in eine nutzerverständliche Notiz übersetzt werden kann, war der Impact wahrscheinlich nicht gut erklärt. Conventional Commits helfen beim Sortieren, ersetzen aber keine klare Sprache.

gh pr list --state merged --base main --limit 20 \
  --json number,title,body,mergedAt \
  | claude -p "
Erstelle deutsche Release-Notes aus diesen gemergten Pull Requests.

Abschnitte:
## Neue Funktionen
## Fehlerbehebungen
## Performance
## Dokumentation
## Entwickleränderungen

Regeln:
- PR-Nummern behalten
- Interne Änderungen kurz halten
- Breaking Changes, Migrationen und Feature Flags hervorheben
- Keine Wirkung erfinden, die im PR-Body nicht begründet ist
"

Dieser Schritt verbessert rückwirkend die PR-Beschreibung. Wer weiß, dass der PR später eine Release-Notiz speist, formuliert Motivation, Risiko und Tests früher sauberer.

Laute KI-PRs vermeiden

Der häufigste Fehler ist Rauschen. Unerbetenes Formatieren, breite Umbenennungen, spekulative Refactorings, doppelte Kommentare, Marketing-Prosa und nicht verifizierte Testbehauptungen machen Reviews langsamer.

Die Regeln sind einfach. Formatierung separat halten. Generierten Code auf den kleinsten sinnvollen diff begrenzen. Im PR-Body nur Fakten schreiben. Erklären, warum ein Claude-Code-Vorschlag übernommen wurde. Mechanische Änderungen, Verhaltensänderungen und Tests trennen, wenn es möglich ist.

Laute KI-PR	Reviewbare PR
”Claude hat das Modul verbessert"	"Autorisierungsprüfungen nach server/auth.ts verschoben”
Formatierung und Logik gemischt	Formatierungs-PR und Feature-PR getrennt
”Alles gut” ohne Belege	Befehle, Ergebnisse und Lücken gelistet
Kein Review-Fokus	Dateien und Risiken am Anfang genannt

In eine ClaudeCodeLab-Angebotsstrecke einbauen

Dieses Thema passt gut zu Templates, Training und Beratung. Teams brauchen nicht nur einen Prompt, sondern PR-Template, CLAUDE.md-Regeln, CI-Gates und Review-Routinen. Verlinke auf CLAUDE.md Templates, Team-Handoff-Regeln und Training oder Beratung, damit Leser den nächsten Umsetzungsschritt sehen.

Führe es schrittweise ein. Woche 1: PR-Template. Woche 2: diff-size Gate. Woche 3: Review-Handoff. Woche 4: Release Notes aus gemergten PRs. Zu viele Regeln auf einmal erzeugen Widerstand, bevor Qualität entsteht.

Praktisches Ergebnis

Ich habe diesen Ablauf in einem kleinen Node-Projekt getestet. Die Kombination aus PR-Template und Größenlimit hatte den größten Effekt. Claude Code allein schrieb lange, aber ungleichmäßige Beschreibungen. Das Template machte fehlende Tests, Sicherheitsprüfung, Review-Dateien und Rollback sichtbar. Das Budget von 700 Zeilen und 35 Dateien half außerdem, Formatierung und Verhaltensänderung vor der Review-Anfrage zu trennen.

Fazit

Claude Code verbessert Pull-Request-Qualität, wenn der Prozess klare Schienen hat: striktes Template, CI-Limit für diff-Größe, reproduzierbare Testnachweise, Sicherheits- und Datenschutzcheck, Review-Handoff und Release-Notes. Ziel ist nicht ein hübscher klingender PR, sondern ein KI-unterstützter Change, den Menschen zuverlässig prüfen und ausliefern können.