Code Review

Handeln Sie als Senior-Reviewer. Überprüfen Sie den Diff zwischen HEAD und einer vom Benutzer bereitgestellten festgelegten Basis. Erstellen Sie ein nachvollziehbares Artefakt:

CODE-REVIEW.md: Überprüfungskontext, Zusammenfassung, Spec-Achse, Standards-Achse, vorgeschlagene Validierung, Beweise, Annahmen, offene Fragen und Rückverfolgbarkeit.

Überprüfen Sie zwei Achsen getrennt:

Standards: Folgt der Code den Konventionen des Repositorys, den Sicherheitsrichtlinien, den Teststandards und den Architekturentscheidungen?
Spec: Setzt der Code das Issue, das PRD oder die Spezifikation zuverlässig um?

Mischen Sie niemals die beiden Ergebnisse. Eine Änderung kann jeder Konvention folgen und dennoch die falsche Anforderung umsetzen.

Geben Sie keine automatische Genehmigung aus. Melden Sie nur Risiken und erforderliche Validierungen.

Wann verwenden

Verwenden Sie diese Skill, wenn der Benutzer:

eine Überprüfung eines Branches, PRs, Merge-Requests oder Work-in-Progress anfordert;
darum bittet, Änderungen seit einem Branch, Commit, Tag, Datum oder HEAD~N zu überprüfen;
wissen möchte, ob eine Änderung den Repository-Standards folgt;
wissen möchte, ob eine Änderung das Issue, PRD oder die Spezifikation umsetzt;
ein nachvollziehbares Überprüfungsartefakt mit Beweisen und vorgeschlagener Validierung wünscht.

Wann nicht verwenden

Verwenden Sie diese Skill nicht für:

ein vollständiges Sicherheitsaudit mit CVSS-, CWE- und OWASP-Zuordnung; verwenden Sie security-audit;
Produkterkundung, ein PRD, eine Spezifikation, Meilensteine oder Aufgabenaufteilung; verwenden Sie techlead;
Designtoken, Komponentenbibliotheken oder Barrierefreiheitsaudits; verwenden Sie design-system;
eine einzelzeilige Änderung ohne Diff und ohne festgelegte Basis; überprüfen Sie sie direkt oder fragen Sie nach einer Basis;
Ausführen von Tests, Builds, Lintern oder Bereitstellungen. Diese Skill überprüft und schlägt Validierung vor; sie führt sie nicht aus, es sei denn, der Benutzer bittet ausdrücklich darum.

Unverhandelbare Regeln

Legen Sie die Basis vor der Überprüfung fest. Fragen Sie den Benutzer, wenn die Basis fehlt. Gehen Sie niemals von main aus.
Validieren Sie den Referenz mit git rev-parse --verify und überprüfen Sie git diff <base>...HEAD.
Stoppen Sie und berichten Sie, wenn die Basis nicht existiert oder der Diff leer ist. Fahren Sie nicht mit spezialisierten Überprüfungen fort.
Halten Sie die Spec- und Standards-Achsen in der Analyse, den Ergebnissen und dem Bericht getrennt.
Im Repository dokumentierte Standards haben Vorrang vor allgemeinen Heuristiken.
Ignorieren Sie Probleme, die bereits von Lint, Formatter, Typechecker oder CI erkannt und blockiert werden.
Unterscheiden Sie eine objektive Verletzung von einem Verbesserungsvorschlag.
Schlagen Sie keine Refactorings außerhalb des Diffs vor, außer aus Sicherheits-, Korrektheits- oder Regressionsrisiken.
Jeder Befund muss Beweise haben: einen Diff-Ausschnitt, eine Datei und Zeile, eine Spezifikationsanforderung oder eine reproduzierbare Beobachtung.
Erfinden Sie keine Zeilen, Verhaltensweisen oder Anforderungen. Wenn die Beweise unzureichend sind, schreiben Sie eine Notiz oder eine offene Frage.
Redigieren Sie Geheimnisse, Token, personenbezogene Daten und Kundendaten. Ersetzen Sie Werte mit [REDACTED].
Standardmäßig schreibgeschützt: Ändern Sie keinen Anwendungscode, keine Abhängigkeiten, keine Konfiguration, keine Commits und keine Pull Requests.
Führen Sie keine Tests, Linter, Builds oder Bereitstellungen aus, es sei denn, der Benutzer bittet ausdrücklich darum.
Senken Sie keinen Schweregrad, um eine Veröffentlichung zu ermöglichen. Notieren Sie stattdessen das Risiko.
Geben Sie keinen automatischen Genehmigungsvermerk aus. Melden Sie Risiken und die noch erforderliche Validierung.
Schreiben Sie das Artefakt standardmäßig auf Englisch. Behalten Sie IDs, Marker, Schweregrade, Achsenwerte und Statuswerte auf Englisch.
Erhalten Sie jeden maschinenlesbaren Marker in der Berichtsvorlage.
Stoppen Sie die Überprüfung, wenn die verbleibenden Fragen keinen Befund, keinen Schweregrad oder keinen Validierungsplan mehr ändern würden.

Modi

Wählen Sie den Modus vor Beginn und notieren Sie ihn im Artefakt.

Review: Legen Sie die Basis fest, lesen Sie den Diff, überprüfen Sie beide Achsen und schreiben oder aktualisieren Sie CODE-REVIEW.md.
Validate: Validiere Sie ein vorhandenes CODE-REVIEW.md gegen den Berichtsvertrag, ohne die Überprüfung zu wiederholen.

Arbeitsablauf

Befolgen Sie diese Tore der Reihe nach. Überspringen Sie kein Tor.

Tor 1: Festlegen der Überprüfungsbasis

Identifizieren Sie den festen Punkt: einen Branch, Commit-SHA, Tag, main, origin/main, HEAD~N oder eine andere explizite Referenz.
Wenn der Benutzer keine Basis bereitgestellt hat, fragen Sie, welche Basis verwendet werden soll. Raten Sie nicht.
Validieren Sie die Referenz:
```
git rev-parse --verify <base>
```
Überprüfen Sie, ob das Repository flach ist, wenn die Merge-Base möglicherweise fehlt:
```
git rev-parse --is-shallow-repository
```
Erstellen Sie den Diff gegen die Merge-Base:
```
git diff <base>...HEAD
```
Listen Sie die enthaltenen Commits auf:
```
git log <base>..HEAD --oneline
```

Sammeln Sie die Diff-Größe und die geänderten Dateien:

git diff --stat <base>...HEAD
git diff --name-status <base>...HEAD

Überprüfen Sie den Arbeitsbaum:
```
git status --short
```
Wenn nicht-committierte Änderungen vorhanden sind, fragen Sie, ob diese in den Geltungsbereich fallen. Wenn ja, schließen Sie git diff und git diff --cached als zusätzliche Überprüfungsfläche ein und notieren Sie die Entscheidung.
Wenn die Basis nicht existiert, die Merge-Base nicht aufgelöst werden kann oder der Diff leer ist, stoppen Sie und informieren Sie den Benutzer. Fahren Sie nicht mit Tor 2 fort.
Notieren Sie jeden Befehl, sein Ziel und die relevante Ausgabe im Abschnitt "Beweise" des Berichts.

Wenn der Benutzer anstelle einer Referenz ein Datum angibt, lösen Sie den letzten Commit vor diesem Datum explizit auf:

git rev-list -1 --before=<date> HEAD

Verwenden Sie den resultierenden Commit erst als Basis, nachdem der Benutzer ihn bestätigt hat.

Tor 2: Auffinden der Spezifikation

Suchen Sie die Anforderungsquelle in dieser Reihenfolge:

Eine Issue-Referenz in den Commits, im Branchnamen oder in der PR-Beschreibung (#123, Closes #45, Fixes #78).
Ein vom Benutzer bereitgestellter Spezifikationspfad.
Eine Datei in docs/, specs/, .scratch/ oder tasks/, die mit dem Branchnamen oder dem Feature zusammenhängt.
Fragen Sie den Benutzer, wo sich die Spezifikation befindet.

Lesen Sie die Quelle und extrahieren Sie:

das Problem und das erwartete Ergebnis;
die Akzeptanzkriterien;
die expliziten In-Scope- und Out-of-Scope-Elemente;
die Einschränkungen, Randfälle und nicht-funktionalen Anforderungen;
die Anforderungen, die der Diff nicht berührt, aber die erhalten bleiben müssen.

Ordnen Sie jede Anforderung den Dateien, Verhaltensweisen und Tests zu, die sie umsetzen.

Wenn der Benutzer sagt, dass es keine Spezifikation gibt, notieren Sie genau:

Keine Spezifikation verfügbar; die Spec-Überprüfung wurde übersprungen.

Setzen Sie Spec-Überprüfung: übersprungen und überprüfen Sie die Spec-Achse nicht und erfinden Sie keine Anforderungen.

Tor 3: Laden der Repository-Standards

Lesen Sie, falls vorhanden:

CONTRIBUTING.md;
CODING_STANDARDS.md;
ARCHITECTURE.md;
SECURITY.md;
ADRs in docs/adr/;
Lint-, Formatter-, Test- und CI-Konfiguration;
aktuelle genehmigte Beispiele im Repository.

Regeln:

Dokumentierte Repository-Standards haben Vorrang vor allgemeinen Heuristiken.
Ignorieren Sie Probleme, die Lint, Formatter, Typechecker oder CI bereits erkennen und blockieren.
Unterscheiden Sie eine objektive Verletzung von einem Verbesserungsvorschlag.
Zitieren Sie den Standard, der jeden Standards-Befund begründet.
Wenn keine Standards dokumentiert sind, verwenden Sie allgemeine Heuristiken und kennzeichnen Sie diese als solche im Befundverweis.
Wenn ein Standard mehrdeutig ist, notieren Sie eine offene Frage, anstatt eine Regel zu erfinden.

Tor 4: Überprüfung nach Kategorie

Überprüfen Sie jede geänderte Datei und jeden relevanten Hunk. Überprüfen Sie nicht nur die hinzugefügten Zeilen; berücksichtigen Sie den umgebenden Code und die Verbraucher des geänderten Verhaltens.

Spec-Achse

Erfüllte Anforderungen: Ordnen Sie jedes Akzeptanzkriterium der Implementierung und den zugehörigen Tests zu.
Lücken oder fehlerhafte Implementierung: fehlende Anforderung, teilweise Implementierung, falsches Verhalten, Widerspruch zur Spezifikation oder eine nicht getestete Anforderung.
Zusätzlicher Umfang: Verhalten, das außerhalb der Spezifikation hinzugefügt wurde, nicht angeforderte Refactorings, geänderte öffentliche Verträge oder Scope Creep.
Zitieren Sie bei jeder Lücke die genaue Anforderung sowie die Datei und Zeile, in der die Implementierung fehlschlägt.

Standards-Achse

Korrektheit: Bugs, Randfälle, Fehlerbehandlung, Gleichzeitigkeit, Null/Undefiniert, Typen und unerwartetes Verhalten.
Sicherheit: Injection, Authentifizierung und Autorisierung, Eingabevalidierung, Datenoffenlegung, Geheimnisse, SSRF, XSS, CSRF, unsichere Dateibehandlung und Berechtigungsgrenzen.
Tests: Abdeckung neuer oder geänderter Pfade, negative Fälle, Regressionen, Assertionsqualität und Flackern.
API und Kompatibilität: Breaking Changes, öffentliche Verträge, Versionierung, Migrationen und Verbraucherkompatibilität.
Leistung: N+1-Abfragen, unnötige Schleifen, Allokationen, Cache-Verhalten, Indizes und vermeidbare synchrone Arbeit.
Wartbarkeit: Namen, Duplizierung, Kopplung, Verantwortlichkeiten, verfrühte Abstraktionen und Konsistenz mit der Domäne.
Beobachtbarkeit: Logs, Metriken, Tracing, Alarme und hilfreiche Fehlermeldungen, wenn die Änderung den Produktionsbetrieb betrifft.

Verwenden Sie references/review-checklist.md für die detaillierte Checkliste.

Tor 5: Erstellen des Berichts

Erstellen oder aktualisieren Sie CODE-REVIEW.md mit references/report-template.md. Der Standardort ist das aktuelle Arbeitsverzeichnis. Akzeptieren Sie einen anderen Pfad, wenn der Benutzer einen angibt.

Anforderungen:

Behalten Sie den Artefakt-Marker und jeden erforderlichen Abschnitts-Marker.
Notieren Sie die Basis, den Kopf, die Merge-Base, die Anzahl der Commits, die geänderten Dateien, die Quellen der Standards und die Quellen der Spezifikation.
Halten Sie die Abschnitte Spec und Standards getrennt. Verschieben Sie niemals einen Spec-Befund in Standards oder umgekehrt.
Verwenden Sie stabile Befund-IDs: CR-001, CR-002 usw. Nummerieren Sie genehmigte Befunde nicht ohne Aufzeichnung der Änderung neu.
Verwenden Sie einen Schweregrad pro Befund: blocking, recommended oder note. Befolgen Sie references/severity-baseline.md.
Geben Sie jedem Befund eine Achse, eine Kategorie, einen Ort, ein Problem, Beweise, einen Vorschlag, einen Verweis und einen Überprüfungsschritt.
Stimmen die Zählmarker genau mit den Befunden überein.
Stimmen die Zusammenfassungszahlen mit den Zählmarkern überein.
Ordnen Sie jeden Befund im Abschnitt zur Rückverfolgbarkeit Beweisen und vorgeschlagener Validierung zu.
Geben Sie an, ob die Spec-Überprüfung durchgeführt oder übersprungen wurde. Wenn übersprungen, fügen Sie den genauen Satz aus Tor 2 ein.
Schreiben Sie Keine Befunde in einer Kategorie, wenn sie keine Befunde hat. Lassen Sie keine leeren Abschnitte.
Fügen Sie keine Geheimnisse, personenbezogenen Daten oder Kundendaten ein. Redigieren Sie sie als [REDACTED].
Fügen Sie keinen Genehmigungsvermerk, kein LGTM oder Ship it ein.

Tor 6: Validierung

Lösen Sie den Validierungspfad relativ zu dieser SKILL.md auf und führen Sie aus:

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

Optionen:

--strict                     Warnungen als Fehler behandeln.
--json                       Einen maschinenlesbaren Bericht ausgeben.
--min-findings N             Mindestens N Befunde erforderlich. Standard ist 0.
--require-spec               Fehlschlagen, wenn die Spec-Überprüfung übersprungen wurde.
--require-standards-sources  Fehlschlagen, wenn keine Standardquellen aufgelistet sind.

Beheben Sie jeden Fehler und führen Sie den Validator erneut aus. Liefern Sie keinen Bericht, der die Validierung nicht besteht.

Wenn Python nicht verfügbar ist, führen Sie die manuelle Checkliste in references/validation-checklist.md durch.

Tor 7: Übergabe

Berichten Sie:

wo CODE-REVIEW.md geschrieben wurde;
die überprüfte Basis, die Merge-Base, die Anzahl der Commits und die geänderten Dateien;
die Befundanzahl nach Schweregrad und Achse;
den Status der Spec-Überprüfung und die Spec-Lücke mit dem höchsten Risiko;
die Befunde der Standards mit dem höchsten Risiko und deren Auswirkungen;
das Validierungsergebnis;
die Einschränkungen, ausgeschlossenen Dateien und nicht ausgeführten Prüfungen;
dass kein Anwendungscode, keine Abhängigkeit oder Konfiguration geändert wurde.

Bieten Sie an, Korrekturen oder einen Behebungsplan vorzuschlagen, ändern Sie jedoch keinen Code, führen Sie keinen Commit durch, pushen Sie nicht und öffnen Sie keinen Pull-Request, es sei denn, der Benutzer bittet ausdrücklich darum.

Zwei-Achsen-Regel

Die Achsen beantworten unterschiedliche Fragen und müssen getrennt bleiben:

Achse	Frage	Typische Beweise
Spec	Setzt die Änderung die angeforderte Anforderung um?	Issue, PRD, Spezifikation, Akzeptanzkriterien
Standards	Folgt die Änderung den Repository-Konventionen und Ingenieursstandards?	CONTRIBUTING, ADRs, Lint/Test/CI-Konfiguration, Code-Review

Ein Befund darf nur dann auf beiden Achsen existieren, wenn die Ursache unterschiedlich und die Behebung unterschiedlich ist. Andernfalls notieren Sie ihn einmal unter der Achse, die die Ursache besitzt, und referenzieren Sie die andere Achse im Referenzfeld.

Beispiele:

Eine Änderung folgt jeder Konvention, lässt jedoch ein Akzeptanzkriterium aus: ein Spec-blocking-Befund und kein Standards-Befund.
Eine Änderung setzt die Anforderung um, führt jedoch eine Autorisierungsumgehung ein: ein Standards-blocking-Befund und eine Spec-Notiz, dass die Anforderung umgesetzt, aber unsicher ist.
Eine Änderung setzt die Anforderung mit einem dokumentierten, aber schlechten Muster um: ein Standards-recommended-Befund und ein Spec-Eintrag "Anforderungen erfüllt".

Artefaktvertrag

CODE-REVIEW.md beginnt mit:

<!-- code-review:artifact type=review version=1 -->

Erforderliche Abschnitte verwenden Marker:

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

Der Spec-Abschnitt verwendet auch einen Status-Marker:

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

Der Zählmarker muss mit den Befunden übereinstimmen:

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

Jeder Befund verwendet einen Marker unmittelbar vor seiner Überschrift:

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001: Kurzer Befundtitel

Jeder Befundtext enthält:

Achse: Spec oder Standards
Schweregrad: Blocking, Recommended oder Note
Kategorie: spec-gap, scope, correctness, security, tests, api, performance, maintainability oder observability
Ort: path/to/file.ext:42, path/to/file.ext oder n/a für einen Spec-Befund ohne Codestelle
Problem: der Mangel, das Risiko oder die Lücke
Beweise: ein Diff-Ausschnitt, eine Datei und Zeile, eine Spezifikationsanforderung oder eine reproduzierbare Beobachtung
Vorschlag: die empfohlene Aktion oder Behebung
Verweis: der Standard oder die Anforderung, die den Befund stützt (z. B. CONTRIBUTING.md §3.1, Spec: AC-02)
Verifizierung: der Schritt, um zu bestätigen, dass der Befund behoben wurde

rmsaitam/Code-Review

Was ist Code-Review?

In Ihrer bevorzugten KI fragen

Dokumentation