Claude Code Code-Review-Checkliste für Teams

Mit Risiko starten, nicht mit “review this”

Wenn du Claude Code nur “review this PR” gibst, bekommst du meistens hilfreiche, aber zu allgemeine Hinweise.

Ein Team braucht zuerst die harten Fragen: Was kann brechen, welche Daten werden berührt, welche Testnachweise gibt es, und welche Punkte müssen vor dem Merge blockieren?

Dieser Artikel liefert eine kopierbare Review-Checkliste, einen Claude-Code-Review-Prompt, ein GitHub-PR-Template und einen CI-Guard mit GitHub Actions.

Claude Code ersetzt keine menschliche Verantwortung. Es ist ein zweites Paar Augen, das Lücken reduziert und Review-Standards stabiler macht. Offizielle Grundlagen sind der Claude-Code-Guide zumcode review setup, dieClaude Code GitHub Actions docs, GitHub-Dokumente zuPR-Templates, protected branches undActions workflows. Für Security-Reviews eignet sich dieOWASP Secure Code Review Cheat Sheet.

Was risikobasiertes Review bedeutet

Risikobasiertes Review bedeutet, dass nicht jeder PR denselben Prozess bekommt. Eine Textkorrektur, ein CSS-Abstand, ein Payment-Webhook und eine destruktive Datenbankmigration haben sehr unterschiedliche Folgen. Wenn alles schwergewichtig ist, werden kleine Änderungen langsam. Wenn alles leichtgewichtig ist, gehen gefährliche Änderungen durch.

Diese drei Stufen reichen als Start:

Risiko	Beispiele	Pflichtreview
Low	Text, einfaches CSS, Docs, Log-Text	Ein Reviewer, klare Summary, Screenshot oder Diff-Erklärung
Medium	Formulare, UI-State, Search, API Response Shape, read-only Datenzugriff	Ein Reviewer, Testnachweis, Claude-Code-Review
High	Auth, Autorisierung, Billing, personenbezogene Daten, Migration, Delete, Webhook	Zwei Reviewer, Rollback-Plan, Pflicht-CI, Security/Privacy-Review

Eine Migration ist jede Änderung an Struktur oder Form von Daten. Code lässt sich oft revertieren. Gelöschte Spalten, überschriebene Records oder fehlgeschlagene Backfills sind deutlich schwerer zu reparieren. Deshalb fragt ein Migrationsreview zuerst: “Wie kommen wir zurück?”

Gib Claude Code immer die Risikostufe. Ein vager Prompt erzeugt oft Stilhinweise. Ein Prompt wie “High risk: billing webhook and customer email changed” lenkt die Prüfung auf Signaturvalidierung, Idempotenz, Retries, Privacy, Logging und Testnachweise.

Aus Masas Teamnotizen war der häufigste Fehler, nur abstrakte Wörter wie Qualität, Sicherheit und Wartbarkeit zu nutzen. Als Überschriften sind sie okay, als Review-Fragen zu schwach. Ein gutes PR-Template verlangt Dateien, Datentypen, Risikogründe, Testnachweise und Rollback-Schritte.

Kopierbare Review-Checkliste

Lege diese Checkliste in .github/review-checklist.md, ins Team-Wiki oder in den Review-Abschnitt von CLAUDE.md. Die Punkte sind bewusst konkret, damit Claude Code und Menschen Fakten prüfen.

# Code Review Checklist

## 0. PR scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] Generated or AI-written files are marked in the PR description.
- [ ] No unrelated formatting, dependency, or config changes are mixed in.

## 1. Risk level
- [ ] Risk level is marked as low, medium, or high.
- [ ] High-risk PRs have two human reviewers.
- [ ] High-risk PRs include rollback or recovery steps.

## 2. Security and privacy
- [ ] User input is validated on the server side.
- [ ] Authorization is checked near the data access point.
- [ ] Secrets are not printed, committed, or sent to Claude prompts.
- [ ] Logs do not include email, tokens, addresses, payment IDs, or private content.
- [ ] OWASP-relevant risks such as injection, XSS, broken access control, and SSRF were considered.

## 3. Tests
- [ ] Unit or integration tests cover the changed behavior.
- [ ] Regression tests cover the bug that motivated the PR.
- [ ] Manual verification steps are written with actual result, not "works locally".
- [ ] Snapshot changes are explained.

## 4. Performance
- [ ] New loops, queries, and network calls are bounded.
- [ ] N+1 queries were checked.
- [ ] Large lists, images, and bundles have a budget.
- [ ] Metrics or before/after evidence are attached for performance-sensitive changes.

## 5. Accessibility
- [ ] Keyboard operation works for interactive UI.
- [ ] Focus order and visible focus state are preserved.
- [ ] Form fields have labels and errors that screen readers can understand.
- [ ] Color contrast and reduced-motion behavior are checked where relevant.

## 6. Migration and data risk
- [ ] Migration is backward compatible during rollout.
- [ ] Destructive changes have backup or recovery steps.
- [ ] Old and new app versions can run during deployment.
- [ ] Data cleanup jobs are idempotent.

## 7. AI-generated diff hygiene
- [ ] AI-generated code was read by a human before approval.
- [ ] The diff does not remove tests, monitoring, analytics, or CTA links by accident.
- [ ] New dependencies are justified.
- [ ] Comments do not claim verification that was not actually done.

Wichtig ist Prüfbarkeit. “Security berücksichtigt” ist schwach. “Logs enthalten keine E-Mails, Tokens, Adressen, Payment IDs oder privaten Inhalte” ist prüfbar. “Accessibility passt” ist schwach. “Keyboard, sichtbarer Fokus, Labels und verständliche Fehlermeldungen funktionieren” ist konkret.

Claude-Code-Review-Prompt

Der Prompt braucht Rolle, Kontext, Risiko und eine klare Grenze: erst Findings, noch keine Änderungen. Sonst vermischen sich Review und Implementierung, der Diff wächst, und niemand weiß mehr, welche Punkte wirklich akzeptiert wurden.

You are reviewing a pull request for a production team.

Goal:
- Find concrete risks before merge.
- Prioritize correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
- Do not rewrite code yet. Produce review findings first.

Context:
- Risk level: <low | medium | high>
- Business area: <auth | billing | content | search | admin | analytics | other>
- Sensitive data touched: <none | email | payment | address | health | private content | other>
- Rollout plan: <flag | migration | immediate deploy | other>

Review method:
1. Read the PR summary and changed files.
2. List the top risks by severity.
3. For each finding, include file, line or function, why it matters, and a minimal fix.
4. Separate "must fix before merge" from "follow-up".
5. Check whether tests prove the changed behavior.
6. Check whether any AI-generated code, dependency, config, or formatting change is unrelated to the PR goal.

Output format:
- Findings first, ordered by severity.
- Then missing evidence.
- Then questions for the author.
- Then a short merge recommendation: block, approve with fixes, or approve.

Das passt gut zuCodebase Navigation undTeststrategie. Vor dem Review kann Claude Code den betroffenen Domänenbereich kurz erklären. Dadurch endet die Review seltener bei Namen und Formatierung.

GitHub Pull Request Template

Mit .github/pull_request_template.md füllt GitHub den PR-Body vor. Ziel ist nicht Bürokratie, sondern dieselbe Evidenz für Reviewer, Claude Code und Branch Protection.

## Summary
- TODO

## Risk
Risk level: low | medium | high

Risk reasons:
- Data touched:
- Users affected:
- Rollout:

## Review focus
- [ ] Correctness
- [ ] Security/privacy
- [ ] Tests
- [ ] Performance
- [ ] Accessibility
- [ ] Migration/data risk
- [ ] AI-generated diff hygiene

## Test evidence
- Automated:
- Manual:
- Not tested because:

## Security and privacy notes
- Secrets changed: no | yes
- Personal data in logs: no | yes
- Authorization boundary changed: no | yes

## Migration / rollback
- Migration included: no | yes
- Backward compatible: no | yes | not applicable
- Rollback plan:

## Claude Code review prompt
Paste this into Claude Code after the PR is ready:

Review this PR as risk level "<low|medium|high>".
Focus on correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
Return findings first with file/function references and minimal fixes.

Ein Template nur aus Checkboxen wird schnell mechanisch abgehakt. Felder wie Risk reasons, Test evidence und Rollback plan verlangen Nachweise und lassen sich später auch automatisch prüfen.

CI-Guard mit GitHub Actions

Der folgende Workflow und das Node-Script prüfen PR-Body und geänderte Dateien. Das beweist nicht, dass der Code korrekt ist, verhindert aber Reviews ohne Mindestkontext.

name: PR review guard

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

permissions:
  contents: read
  pull-requests: read

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

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Check PR review evidence
        run: node scripts/pr-review-guard.mjs
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";

const eventPath = process.env.GITHUB_EVENT_PATH;
if (!eventPath) throw new Error("GITHUB_EVENT_PATH is missing.");

const event = JSON.parse(readFileSync(eventPath, "utf8"));
const pr = event.pull_request;
const body = pr?.body ?? "";
const base = process.env.BASE_SHA ?? pr?.base?.sha;
const head = process.env.HEAD_SHA ?? pr?.head?.sha;

function safeRef(value, name) {
  if (!value || !/^[a-f0-9]{40}$/i.test(value)) throw new Error(`${name} must be a full git SHA.`);
  return value;
}

const changedFiles = execSync(`git diff --name-only ${safeRef(base, "BASE_SHA")} ${safeRef(head, "HEAD_SHA")}`, {
  encoding: "utf8",
}).split(/\r?\n/).filter(Boolean);

const hasRisk = /Risk level:\s*(low|medium|high)/i.test(body);
const hasTests = /## Test evidence[\s\S]*(Automated|Manual):\s*\S/i.test(body);
const hasRollback = /Rollback plan:\s*\S/i.test(body);
const highRisk = /Risk level:\s*high/i.test(body);
const migrationChanged = changedFiles.some((file) => /migrations?|schema|prisma|drizzle/i.test(file));
const sensitiveChanged = changedFiles.some((file) => /auth|session|permission|billing|payment|webhook/i.test(file));
const failures = [];

if (!hasRisk) failures.push("Add Risk level.");
if (!hasTests) failures.push("Add automated or manual test evidence.");
if ((highRisk || migrationChanged) && !hasRollback) failures.push("Add rollback plan.");
if (sensitiveChanged && !/Security and privacy notes/i.test(body)) failures.push("Add security/privacy notes.");

if (failures.length) {
  console.error("PR review guard failed:");
  for (const failure of failures) console.error(`- ${failure}`);
  process.exit(1);
}

console.log("PR review guard passed.");

Starte advisory, nicht sofort als Pflicht. Danach kannst du den Check für High-Risk-Änderungen und Migrationen in protected branches erzwingen. Low-Risk-PRs sollten leicht bleiben.

Security, Privacy, Tests, Performance und Accessibility

Security-Review wird einfacher, wenn du in Input, Autorisierung, Output, Logs und externe Calls teilst. Gibt es serverseitige Validierung? Liegt Autorisierung nahe am Datenzugriff? Kann Output XSS erzeugen? Enthalten Logs private Daten? Kann ein Webhook oder eine externe URL zu SSRF oder Signature Bypass führen?

Privacy ist mehr als Secrets. E-Mail, Payment ID, Adresse, Kontakttext, Analytics-ID und privater Content brauchen Schutz. Klebe keine echten API Keys, Kundenmails, Verträge oder Zahlungs-IDs in Prompts. Maskiere Werte und gib Claude Code nur die Struktur.

Bei Tests zählt Evidenz. “Works locally” reicht nicht. Ein guter PR nennt den automatisierten Test, den manuellen Flow und das beobachtete Ergebnis. Ohne Test muss die Begründung im PR stehen.

Bei Performance sucht Claude Code nach unbounded loops, N+1 queries, wiederholten Network Calls, Bundle-Wachstum, schweren Bildern und teurem Client Rendering. Ein einfacher Vorher/Nachher-Wert hilft sehr.

Accessibility endet nicht beim Screenshot. Prüfe Keyboard, Focus Order, sichtbaren Fokus, Labels, Fehlermeldungen, Modal Focus Trap und Reduced Motion. KI-generierte UI sieht oft sauber aus und vergisst genau diese Details.

Praktische Use Cases

Erster Use Case: Auth und Admin Screens. Userlisten, Rollenänderungen und Audit Logs müssen in API oder Data Layer geschützt sein. Prüfe Autorisierung, Audit Trail, private Daten in Logs und Tests für unautorisierten Zugriff.

Zweiter Use Case: Billing und Webhooks. Ein Payment Webhook braucht Signaturvalidierung, Idempotenz, Retry Handling, Schutz vor doppelten Events, Cancellation Handling und datensparsame Logs.

Dritter Use Case: Datenbankmigration. Eine neue Spalte kann Production brechen, wenn alte und neue App-Versionen während des Deployments parallel laufen. Prüfe defaults, not null, index, backfill, rollback und expand-contract.

Vierter Use Case: großer AI-generierter UI-Diff. Wenn Claude Code Seiten, Forms, Modals oder Tabellen generiert, prüfe versehentlich entfernte CTAs, geänderte Analytics Events, Accessibility-Lücken, unerklärte Snapshots und neue Dependencies.

Fünfter Use Case: Content-Site mit Umsatzpfad. Review für Artikel-, Produkt- oder Lead-Seiten muss Conversion schützen. Wenn ein Link zuProdukten, ein Gratis-PDF-Formular oder Consultation Tracking bricht, ist es ein Business-Bug.

Fallen und CTA

Erste Falle: Claude-Code-Findings ungeprüft glauben. KI kann plausibel klingen. Prüfe jedes Finding gegen Diff, Tests, offizielle Docs oder Reproduktion.

Zweite Falle: Review und Implementierung mischen. Lass zuerst Findings erzeugen, entscheide must-fix, und ändere erst danach. So bleibt der PR lesbar.

Dritte Falle: unrelated AI cleanup. Formatierung, Dependencies, Config und gelöschte Tests können sich in einem großen Diff verstecken. Bitte Claude Code explizit um unrelated changes.

Vierte Falle: Daten-Rollback mit Code-Revert verwechseln. Ein Revert stellt gelöschte Daten nicht wieder her. High-Risk-Migrationen brauchen Backup, Recovery SQL, Feature Flag oder Phasenplan.

Review schützt auch Umsatz. Billing, Produktseiten, Gratis-PDFs, Gumroad, Analytics und Consultation CTAs sind Teil des Systems. Für Praxis nutze diekostenlose Checkliste. Für Templates, Prompts, CLAUDE.md und CI-Guard sieheProdukte und Vorlagen. Für Rollout in einem echten Repo passtTraining und Beratung.

Ich habe die Struktur auf drei kleine Szenarien angewendet: Next.js UI Change, Datenbankmigration und Claude-Code-generierter UI-Diff. Am stärksten halfen Risk level und Rollback plan. Mehr Checkboxen halfen weniger als kurze, konkrete Evidenz.

Zusammenfassung

Eine Claude-Code-Review-Checkliste ist nicht nur ein Prompt. Sie verbindet Risikoklassifikation, PR-Evidenz, menschliches Review, CI und protected branches.

Starte klein: PR-Template hinzufügen, Guard advisory laufen lassen, dann für High-Risk required machen. Kombiniere das mitAI Pair Programming undCLAUDE.md Best Practices, damit der Standard im Repository lebt.