Code-Reviews mit Claude Code im Team

Claude Code bringt im Code-Review dann Wert, wenn es Teil eines wiederholbaren Ablaufs ist. Es ersetzt keine menschlichen Reviewer. Es sortiert den PR, markiert Risikobereiche, stellt bessere Fragen und gibt Menschen mehr Zeit für Architektur, Produktabsicht und Ownership.

Für Teams besteht der praktische Ablauf aus PR-Template, Review-Regeln in CLAUDE.md, einem Diff-Größen-Gate, GitHub Actions, CODEOWNERS und einem Prompt, der Belege verlangt. Offizielle Quellen dazu sind Claude Code common workflows, GitHub Pull-Request-Dokumentation, CODEOWNERS, GitHub Actions workflow syntax und der OWASP Code Review Guide.

Review-System

Risikobasiertes Review bedeutet: Nicht jede Zeile wird gleich streng geprüft. Authentifizierung, Autorisierung, Abrechnung, Datenmigration, Performance und fehlende Tests bekommen mehr Aufmerksamkeit. Diff scope ist der Bereich, der in diesem PR tatsächlich geändert wurde. Ein CI gate ist eine automatische Prüfung, die warnen oder blockieren kann. Ein hallucinated finding ist ein KI-Hinweis, der plausibel klingt, aber keine Evidenz im Diff hat.

flowchart LR
  A["PR template"] --> B["Diff size gate"]
  B --> C["Claude Code review"]
  C --> D["Code owner review"]
  D --> E["CI tests and merge"]
  C --> F["Questions before fixes"]

Die wichtigste Regel: Claude Code soll im Review nicht still Code umschreiben. Wenn Business-Absicht, Datenvertrag oder Berechtigungsregel unklar sind, soll es fragen.

Praxisfälle

Erster Fall: Authentifizierung und Autorisierung. Bei Login, Sessions, Rollen, Admin-Bereichen und API keys soll Claude Code fehlende Autorisierung, Privilegienausweitung, Secret-Leaks und fehlende Audit-Logs prüfen. Die Business-Regel entscheidet weiterhin ein Mensch. Mehr dazu steht in Security-Audits mit Claude Code.

Zweiter Fall: Performance-relevante Änderungen. Suche, Listen, Caches, Bilder und Batch-Jobs verstecken oft N+1-Abfragen, wiederholte Render-Arbeit, falsche Cache-Keys oder große Payloads. Ein guter Review-Kommentar nennt die Eingabegröße und die Messmethode.

Dritter Fall: Tests und Datenmigrationen. Schema-Änderungen, migrations, seeds, Validierung und backfills brauchen Rollback-Denken, vorhandene Daten, nullable Felder, unique constraints und Wiederholbarkeit nach Fehlern. Claude Code kann die fehlenden Tests und Randfälle vorbereiten.

Vierter Fall: zu große PRs. Ab 800 bis 1000 geänderten Zeilen sinkt die Review-Qualität. CI kann warnen oder blockieren, Claude Code kann eine Aufteilung nach Verhalten, Migration, UI und Tests vorschlagen.

PR-Template

Legen Sie .github/pull_request_template.md an.

## Change summary
- What changed:
- Why it changed:
- User-visible impact:

## Risk review
- [ ] Security impact checked
- [ ] Performance impact checked
- [ ] Test coverage added or explained
- [ ] Data migration or rollback plan checked
- [ ] No secrets, tokens, or personal data included

## Claude Code review request
Please review this PR by diff scope only.

Focus on:
- Security: auth, authorization, injection, secret leakage
- Performance: N+1 queries, cache keys, unnecessary work
- Tests: missing unit, integration, and migration tests
- Data: schema changes, rollback, backfill safety

For each finding, include:
- file and line
- why it matters
- evidence from the diff
- suggested fix or question for the author

diff scope only verhindert generische Kommentare zum gesamten Repository. Das Review soll diesen PR verbessern.

Regeln in CLAUDE.md

Schreiben Sie die Teamregeln in CLAUDE.md. Diese Datei ist die lokale Projekt-Erinnerung für Claude Code. Weitere Strukturideen stehen in CLAUDE.md Best Practices.

## Code review rules

Review only the current diff unless the user asks for wider context.

Severity:
- Must fix: security bug, data loss, broken build, failed test, migration risk
- Should fix: likely production bug, missing important test, measurable performance issue
- Nice to have: naming, small cleanup, optional refactor

Evidence rule:
- Every finding must cite a file and line.
- If the evidence is uncertain, ask a question instead of asserting a bug.
- Do not invent dependencies, routes, database columns, or team policies.

Security checks:
- Authentication and authorization
- SQL or command injection
- XSS and unsafe HTML
- Secret leakage
- Missing audit log for privileged actions

Data checks:
- Migration rollback path
- Backfill failure behavior
- Existing nullable and unique constraints
- PII handling and retention

Die Evidenz-Regel ist entscheidend. Ohne Datei, Zeile und Begründung gehört ein Punkt in die Fragen, nicht in Must fix.

Diff-Gate-Skript

Speichern Sie das Skript als scripts/review-diff-gate.mjs.

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

const baseRef = process.env.BASE_REF || "origin/main";
const maxFiles = Number(process.env.MAX_REVIEW_FILES || 25);
const maxLines = Number(process.env.MAX_REVIEW_LINES || 800);

function git(command) {
  return execSync(command, { encoding: "utf8" }).trim();
}

const files = git(`git diff --name-only ${baseRef}...HEAD`)
  .split(/\r?\n/)
  .filter(Boolean);

const numstat = git(`git diff --numstat ${baseRef}...HEAD`);
const changedLines = numstat
  .split(/\r?\n/)
  .filter(Boolean)
  .reduce((total, line) => {
    const [added, deleted] = line.split(/\s+/);
    return total + (Number(added) || 0) + (Number(deleted) || 0);
  }, 0);

const riskyPatterns = [
  /^src\/auth\//,
  /^src\/billing\//,
  /^db\/migrations\//,
  /^infra\//,
  /^\.github\/workflows\//,
];

const riskyFiles = files.filter((file) =>
  riskyPatterns.some((pattern) => pattern.test(file))
);

let failed = false;

if (files.length > maxFiles) {
  console.error(`Too many files changed: ${files.length} > ${maxFiles}`);
  failed = true;
}

if (changedLines > maxLines) {
  console.error(`Too many changed lines: ${changedLines} > ${maxLines}`);
  failed = true;
}

if (riskyFiles.length > 0) {
  console.log("Risk-sensitive files changed:");
  for (const file of riskyFiles) console.log(`- ${file}`);
}

if (failed) {
  console.error("Split the PR or add a reviewer-approved exception.");
  process.exit(1);
}

console.log(`Review gate passed: ${files.length} files, ${changedLines} lines.`);

Lokal ausführen:

BASE_REF=origin/main MAX_REVIEW_FILES=25 MAX_REVIEW_LINES=800 node scripts/review-diff-gate.mjs

GitHub Actions und CODEOWNERS

Fügen Sie .github/workflows/review-gate.yml hinzu.

name: review-gate

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

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

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

      - name: Run diff size gate
        env:
          BASE_REF: origin/${{ github.base_ref }}
          MAX_REVIEW_FILES: "25"
          MAX_REVIEW_LINES: "800"
        run: node scripts/review-diff-gate.mjs

Risikobereiche routen Sie mit CODEOWNERS.

# .github/CODEOWNERS
/src/auth/ @example-org/security
/src/billing/ @example-org/payments
/db/migrations/ @example-org/backend-leads
/.github/workflows/ @example-org/platform
/infra/ @example-org/platform

Machen Sie KI-Ausgaben nicht sofort zum harten Merge-Blocker. Stabilisieren Sie zuerst lint, typecheck, tests und Diff-Größe. Danach helfen der CI/CD-Leitfaden und PR-Qualität mit Claude Code.

Review-Prompt

Review the current PR diff against main.

Rules:
1. Stay inside the diff scope unless a referenced file is required.
2. Do not rewrite code silently.
3. For each finding, include file, line, severity, evidence, and suggested action.
4. If business intent or data contract is unclear, ask a question instead of guessing.
5. Ignore style-only preferences unless they break CLAUDE.md or project conventions.

Focus areas:
- Security: auth, authorization, injection, XSS, secrets, audit logs
- Performance: N+1 queries, cache invalidation, repeated rendering, large payloads
- Tests: missing coverage for changed behavior, migrations, and edge cases
- Data migration: rollback, backfill, nullable fields, unique constraints
- CI and ownership: required checks, CODEOWNERS, risky paths

Output:
## Must fix
## Should fix
## Questions
## No issue found in

Fallen und Prüfung

Erste Falle: Review und Fix in einem Schritt. Dadurch wächst der Diff, bevor das Team die Hinweise bestätigt hat. Erst reviewen, dann Fixes auswählen, dann Tests ausführen.

Zweite Falle: Hinweise ohne Evidenz akzeptieren. Wenn Claude Code keine Datei, Zeile und geändertes Verhalten nennt, ist es eine Frage.

Dritte Falle: Migrationen unterschätzen. Grüne Tests beweisen nicht, dass Produktionsdaten sicher sind. Prüfen Sie NULL-Werte, Duplikate, Locks, Rollback-Grenzen und Backfill-Wiederholung.

Ich habe die Beispiele als minimalen Repo-Workflow geprüft: Das Skript braucht Git und Node 22, die Action führt dasselbe Skript aus, und die Templates halten Claude Code im Diff. Für Teams würde ich eine Woche mit Warnungen starten, Schwellenwerte anpassen und dann nur zuverlässige Checks verpflichtend machen. Der nächste Schritt ist die Review-Gate-Checkliste vor dem Commit.