KI-Code-Review in die CI-Pipeline integrieren

1. Warum KI-Code-Review als CI-Schritt Sinn ergibt

Klassische statische Analyse-Tools wie PHPStan oder ESLint prüfen gegen feste Regelsätze: Typfehler, unbenutzte Variablen, Verstöße gegen einen Coding-Standard. Ein KI-Code-Review ergänzt das um eine Ebene, die klassische Linter strukturell nicht abdecken können, nämlich das Verstehen von Absicht und Kontext. Ein Sprachmodell kann erkennen, dass eine neue Methode denselben Zweck wie eine bereits existierende Methode in einer anderen Klasse erfüllt, dass ein Kommentar nicht mehr zum Code passt, oder dass eine Fehlerbehandlung zwar syntaktisch korrekt, aber semantisch unvollständig ist.

Der Wert entsteht vor allem durch den Zeitpunkt: Ein KI-Reviewer kommentiert einen Pull Request innerhalb weniger Minuten nach dem Push, lange bevor ein menschlicher Reviewer überhaupt Zeit findet, sich mit dem Diff zu befassen. Offensichtliche Probleme wie fehlende Null-Checks, inkonsistente Namenskonventionen oder vergessene Übersetzungen werden so behoben, bevor sie einen menschlichen Reviewer überhaupt erreichen. Das verschiebt die knappe Ressource menschliche Aufmerksamkeit auf die Fragen, die wirklich Fachwissen und Kontext erfordern: Architekturentscheidungen, Sicherheitsimplikationen und Geschäftslogik.

Wichtig ist die Erwartungshaltung von Anfang an: Ein KI-Reviewer ersetzt kein menschliches Review, er filtert und priorisiert es vor. Teams, die das als vollständigen Ersatz verkaufen, erleben schnell Enttäuschung, weil das Modell keine verbindliche Freigabeinstanz sein kann und auch keine Verantwortung für fehlerhafte Deployments übernimmt.

2. Architektur: Wie ein KI-Reviewer in die Pipeline eingreift

Technisch besteht die Integration aus drei Bausteinen: einem CI-Trigger auf Pull-Request-Events, einem Aufruf der Claude API mit dem Diff als Kontext und einem Schritt, der die Antwort als strukturierten Kommentar über die GitHub- oder GitLab-API zurückschreibt. Der CI-Job läuft parallel zu den bestehenden Schritten wie PHPStan, PHPCS und der Testsuite, nicht als deren Ersatz. Er blockiert im Regelfall auch nicht den Merge, sondern liefert einen informativen Kommentar, den ein menschlicher Reviewer in seine Entscheidung einbeziehen kann.

Für den Diff-Kontext ist Selektivität entscheidend. Wer den kompletten Pull-Request-Diff unkomprimiert an das Modell schickt, produziert bei großen Änderungen sowohl unnötig hohe Kosten als auch schlechtere Ergebnisse, weil relevante Änderungen in irrelevantem Rauschen untergehen. Bewährt hat sich, den Diff nach Dateityp zu filtern, generierte Dateien und Lockfiles auszuschließen und bei sehr großen Pull Requests nur die am stärksten veränderten Dateien mit vollem Kontext zu versehen, während der Rest als Zusammenfassung mitgegeben wird.

Eine zweite Architekturentscheidung betrifft die Persistenz der Kommentare. Bei jedem neuen Push aufs selbe PR sollte der KI-Reviewer vorherige eigene Kommentare aktualisieren statt neue anzuhängen, sonst sammeln sich nach fünf Iterationen zwanzig teils widersprüchliche Kommentarblöcke im PR-Verlauf an.

# .github/workflows/ai-review.yml
name: AI Code Review

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

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: diff
        run: |
          git diff --name-only origin/${{ github.base_ref }}...HEAD \
            -- '*.php' '*.phtml' ':!vendor' ':!var' > changed_files.txt
          echo "count=$(wc -l < changed_files.txt)" >> "$GITHUB_OUTPUT"

      - name: Run Claude review
        if: steps.diff.outputs.count != '0'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: php bin/ai-review.php --files=changed_files.txt --pr=${{ github.event.number }}

3. Was die KI zuverlässig prüfen kann

Am zuverlässigsten liefert ein KI-Reviewer Ergebnisse bei Konsistenzprüfungen, die menschliche Reviewer aus Zeitgründen oft überspringen: Folgt eine neue Klasse dem gleichen Namensmuster wie vergleichbare Klassen im Modul? Wurde ein PHPDoc-Block vergessen oder ist er veraltet, weil sich die Signatur geändert hat? Wurde eine neue Konfigurationsoption in der system.xml angelegt, aber die zugehörige acl.xml nicht aktualisiert? Solche strukturellen Abgleiche erfordern zwar kein tiefes Fachwissen, aber Aufmerksamkeit über viele Dateien hinweg, und genau das leistet ein Sprachmodell mit vollständigem Diff-Kontext zuverlässig.

Ebenfalls gut geeignet ist die Erkennung offensichtlicher Fehlerklassen: nicht behandelte Exceptions, fehlende Typangaben trotz Strict-Types-Deklaration, hartkodierte Werte, die eigentlich aus der Konfiguration kommen sollten, oder Sicherheitsmuster wie ungefilterte Benutzereingaben in SQL-Fragmenten. Diese Kategorie überschneidet sich teilweise mit dem, was PHPStan auf hohem Level ohnehin findet, aber ein KI-Reviewer kann zusätzlich den Kontext der Änderung einbeziehen und zum Beispiel erkennen, dass eine neue Methode zwar syntaktisch korrekt ist, aber die etablierte Fehlerbehandlung des restlichen Moduls ignoriert.

Schwächer wird die Zuverlässigkeit bei Fragen, die projektspezifisches Wissen jenseits des sichtbaren Diffs erfordern, etwa ob eine Änderung mit einer nicht im Repository dokumentierten Geschäftsregel kollidiert. Hier liefert die KI oft plausibel klingende, aber im Kontext falsche Einschätzungen, was ein Grund ist, jede Aussage als Vorschlag und nicht als Urteil zu behandeln.

4. Was weiterhin menschliches Review braucht

Architekturentscheidungen bleiben fest in menschlicher Hand. Ob ein neues Feature als eigenständiges Modul oder als Erweiterung eines bestehenden Moduls umgesetzt werden sollte, ob ein Plugin oder ein Preference die richtige Wahl ist, oder ob eine neue Abhängigkeit zwischen zwei Modulen langfristig tragbar ist, sind Entscheidungen, die Wissen über die Roadmap, das Team und vergangene Entscheidungen voraussetzen, das in keinem Diff sichtbar ist. Ein KI-Reviewer kann solche Fragen aufwerfen, aber nicht verbindlich beantworten.

Ebenso kritisch bleibt die Bewertung von Sicherheitsrisiken mit echten Konsequenzen: Authentifizierungslogik, Zahlungsabwicklung, Zugriff auf Kundendaten. Ein Modell kann bekannte Antipatterns erkennen, aber es kennt weder die konkrete Bedrohungslage des Shops noch kann es die Tragweite eines Fehlers im Kontext des Geschäftsmodells einschätzen. Bei solchem Code sollte ein KI-Kommentar höchstens ein zusätzlicher Hinweis sein, niemals die einzige Prüfinstanz vor dem Merge.

Auch Performance-Implikationen unter echter Produktionslast, etwa N+1-Query-Probleme, die erst bei tausenden Datensätzen sichtbar werden, oder Race Conditions in nebenläufigem Code, entziehen sich einer statischen Diff-Analyse weitgehend. Hier braucht es Lasttests, Profiling und Erfahrung mit dem konkreten System, keine Texteinschätzung eines Sprachmodells.

5. Review-Fatigue vermeiden: Weniger, aber relevantere Kommentare

Das größte praktische Risiko eines KI-Reviewers ist nicht falsche Einschätzung, sondern schiere Menge. Ein Modell, das zu jedem Diff zwanzig Stilhinweise produziert, von denen die meisten trivial oder bereits durch PHPCS abgedeckt sind, führt dazu, dass Entwickler die Kommentare nach kurzer Zeit ignorieren, egal wie wertvoll die vereinzelten wichtigen Hinweise darunter sind. Dieses Phänomen ist aus der Forschung zu Alarm-Fatigue in Monitoring-Systemen bekannt und überträgt sich eins zu eins auf automatisierte Code-Reviews.

Wirksame Gegenmaßnahmen sind ein explizites Schweregrad-System mit nur wenigen Stufen, eine harte Obergrenze an Kommentaren pro Pull Request, und ein Prompt, der das Modell explizit anweist, bei Unsicherheit lieber zu schweigen als eine vage Vermutung zu äußern. Ebenso wichtig: Stilfragen, die bereits durch PHPCS oder ESLint automatisch geprüft und im Idealfall automatisch korrigiert werden, sollten aus dem Zuständigkeitsbereich des KI-Reviewers explizit ausgeschlossen werden, damit keine doppelten Meldungen für dasselbe Problem entstehen.

Ein weiterer bewährter Kniff ist ein zusammenfassender Kommentar statt vieler Einzelkommentare pro Zeile: eine kurze Liste der wichtigsten drei bis fünf Punkte am Anfang, mit optionalen Detailkommentaren als eingeklappte Abschnitte für alle, die tiefer einsteigen wollen. Das respektiert die Aufmerksamkeit des Reviewers, statt sie mit Inline-Kommentaren zu fragmentieren.

# review_filter.py: collapse noisy findings before posting to the PR
SEVERITY_ORDER = {"blocker": 0, "warning": 1, "suggestion": 2, "nitpick": 3}
MAX_COMMENTS_PER_PR = 6

def filter_findings(findings: list[dict]) -> list[dict]:
    """Drop style-only and low-confidence findings, cap total comment count."""
    # Style issues are already covered by PHPCS/ESLint, skip duplicates
    findings = [f for f in findings if f["category"] != "style"]

    # Drop findings the model itself flagged as low confidence
    findings = [f for f in findings if f.get("confidence", 1.0) >= 0.6]

    findings.sort(key=lambda f: SEVERITY_ORDER.get(f["severity"], 9))
    return findings[:MAX_COMMENTS_PER_PR]

def build_summary_comment(findings: list[dict]) -> str:
    """Build one collapsed summary comment instead of many inline comments."""
    if not findings:
        return "AI review: no blocking issues found."
    lines = ["### AI Code Review Summary", ""]
    for f in findings[:5]:
        lines.append(f"- **[{f['severity']}]** {f['file']}:{f['line']}: {f['summary']}")
    return "\n".join(lines)

6. Praktische CI-Konfiguration mit GitHub Actions

Eine vollständige Integration braucht mehr als den reinen API-Aufruf: Sie muss den Diff sammeln, ihn an die Claude API senden, die Antwort parsen und über die GitHub-API als Kommentar oder Review posten. Das folgende Beispiel zeigt einen minimalen, aber produktionstauglichen Ablauf, der bestehende Kommentare desselben Bots aktualisiert statt neue anzuhängen, und der bei einem API-Fehler den restlichen CI-Lauf nicht blockiert, weil der KI-Review-Schritt nie ein Merge-Gate sein sollte.

Ein wichtiges Detail ist das Rate-Limiting: Bei Teams mit vielen parallelen Pull Requests kann ein KI-Review-Schritt, der bei jedem Push läuft, schnell erhebliche API-Kosten verursachen. Ein Debounce, der nur beim letzten Push innerhalb eines Zeitfensters reviewt, oder eine Begrenzung auf Pull Requests, die als „ready for review" markiert sind, reduziert unnötige Aufrufe deutlich, ohne den praktischen Nutzen zu schmälern.

{
  "review_config": {
    "trigger_events": ["opened", "synchronize", "ready_for_review"],
    "excluded_paths": ["vendor/**", "var/**", "pub/static/**", "*.lock"],
    "excluded_categories": ["style", "formatting"],
    "max_comments_per_pr": 6,
    "min_confidence": 0.6,
    "update_existing_comments": true,
    "blocking": false,
    "model": "claude-sonnet-4-5",
    "focus_areas": [
      "error-handling",
      "consistency-with-existing-patterns",
      "security-obvious-issues",
      "missing-config-updates"
    ]
  }
}

7. Prompt- und Regelwerk-Design für konsistente Reviews

Die Qualität eines KI-Reviews hängt stärker vom Prompt-Design als vom bloßen Modellaufruf ab. Ein Prompt ohne projektspezifischen Kontext führt zu generischen Hinweisen, die zwar technisch korrekt, aber praktisch wenig hilfreich sind, etwa der Standardhinweis „Erwäge Dependency Injection", obwohl das Projekt das längst konsequent umsetzt. Effektiver ist ein Systemprompt, der die tatsächlichen Coding-Standards, verbotenen Patterns und bevorzugten Architekturmuster des Projekts explizit auflistet, idealerweise generiert aus der bestehenden CLAUDE.md oder einer vergleichbaren Projektkonvention.

Ein zweiter Hebel ist Few-Shot-Prompting mit konkreten Beispielen aus dem eigenen Repository: zwei oder drei echte Codeausschnitte, die zeigen, was ein guter und was ein schlechter Kommentar in diesem Projekt ist. Das kalibriert den Ton und die Granularität der Rückmeldungen erheblich besser als eine rein abstrakte Anweisung. Ebenso wichtig ist, das Modell explizit zu bitten, Unsicherheit zu markieren, etwa mit einem Konfidenzwert pro Finding, damit die nachgelagerte Filterlogik aus Abschnitt 5 greifen kann.

{
  "role": "system",
  "content": "You are a code reviewer for a Magento 2 / Hyva project. Rules: use constructor property promotion, prefer ViewModels over Block classes, use plugins not preferences, flag only issues you are confident about (confidence >= 0.6), never repeat what PHPStan level 5 or PHPCS already catch, output at most 5 findings per diff as JSON with fields file, line, severity, summary, confidence."
}

8. Magento-spezifische Prüfregeln einbinden

Für Magento-Projekte lohnt es sich, dem KI-Reviewer projektspezifisches Wissen mitzugeben, das generische Linter nicht abbilden: die Regel, dass jedes neue Modul eine config.xml, system.xml und acl.xml braucht, dass addFieldToFilter niemals mit einem rohen Integer statt der Array-Form aufgerufen werden soll, oder dass PageInterface::getData() nur mit einem PHPStan-Ignore-Kommentar verwendet werden darf. Diese Regeln lassen sich als strukturierte Liste in den Systemprompt einspeisen und funktionieren dann zuverlässiger als eine freie Textbeschreibung.

Ein praktischer Anwendungsfall ist der Dual-Vendor-Workflow, bei dem jedes Modul parallel in zwei Vendor-Varianten gepflegt wird. Ein KI-Reviewer kann zuverlässig prüfen, ob eine neue Datei im einen Vendor-Pfad auch im anderen angelegt wurde, und das ist eine Prüfung, die in einem normalen menschlichen Review häufig übersehen wird, weil sie stures Abgleichen zweier Verzeichnisbäume erfordert. Ebenso lässt sich prüfen, ob PHPDoc-Blöcke mit @param und @return für jede neue öffentliche Methode vorhanden sind, was in vielen Teams eine dokumentierte, aber inkonsequent durchgesetzte Konvention ist.

# bin/ai-review.php runs after checkout, before merge is allowed to proceed
# It never fails the build itself, findings are informational only
bin/ai-review.php \
  --files=changed_files.txt \
  --pr=142 \
  --rules=magento-dual-vendor,phpdoc-required,acl-config-sync \
  --max-comments=6 \
  --post-summary-only

9. KI-Review im Vergleich zu klassischen Linting-Tools

KI-Code-Review ersetzt keine der bewährten statischen Analyse-Tools, sondern ergänzt sie um eine andere Prüfebene. Die folgende Übersicht zeigt, wofür welches Werkzeug den größeren Nutzen bringt, und macht deutlich, warum die sinnvolle Antwort fast immer eine Kombination aus mehreren Ebenen ist, nicht ein Ersatz der einen durch die andere.

In der Praxis funktioniert die Kombination am besten, wenn jedes Werkzeug nur das prüft, wofür es strukturell geeignet ist: PHPStan und PHPCS für deterministische, regelbasierte Prüfungen, die keine Kosten pro Lauf verursachen und keine Interpretationsspielräume lassen, und der KI-Reviewer für die kontextabhängigen Fragen, bei denen starre Regeln versagen. Wer versucht, mit der KI auch das zu prüfen, was ein Linter bereits zuverlässig abdeckt, verschwendet API-Budget und erzeugt zusätzliches Kommentar-Rauschen ohne Mehrwert.

10. Zusammenfassung

KI-Code-Review in der CI-Pipeline löst ein konkretes Problem: Offensichtliche Probleme, Konsistenzverstöße und vergessene Config-Updates werden erkannt, bevor sie einen menschlichen Reviewer erreichen, und zwar innerhalb von Minuten statt Stunden oder Tagen. Der KI-Schritt läuft parallel zu PHPStan und PHPCS, nicht als deren Ersatz, und blockiert im Regelfall nicht den Merge, sondern liefert priorisierte Hinweise. Architekturentscheidungen, Sicherheitsbewertungen mit echten Konsequenzen und Performance unter Produktionslast bleiben fest in menschlicher Verantwortung.

Der entscheidende Erfolgsfaktor ist Zurückhaltung statt Vollständigkeit: Ein Reviewer, der bei jedem Diff zwanzig triviale Hinweise produziert, wird nach kurzer Zeit ignoriert, unabhängig von der Qualität der wenigen wichtigen Hinweise darunter. Ein hartes Kommentar-Limit, ein Konfidenzschwellenwert und der explizite Ausschluss von Themen, die bereits durch Linter abgedeckt sind, halten die Signalqualität hoch. Wer diese Balance trifft, gewinnt einen echten Zeitvorteil im Review-Prozess, ohne die Verantwortung für kritische Entscheidungen an ein Modell abzugeben.

11. FAQ: KI-Code-Review in der CI-Pipeline