lggarrison/agent-skills

PR-Review

Diese Regeln gelten für jeden Reviewer, ob Mensch oder Agent (Copilot Code Review, Claude und andere). Die Schwester-Fähigkeit github behandelt die Seite des Autors: Kommentare beheben, antworten und um die nächste Überprüfung bitten. Sofern die eigenen Review-Regeln des Repos (AGENTS.md, CONTRIBUTING.md, ein Style Guide) mit dieser Fähigkeit in Konflikt stehen, haben die Regeln des Repos Vorrang.

Das Ziel eines Reviews ist es, einen korrekten PR zusammenzuführen. Es geht nicht darum, etwas zu finden. „Keine Probleme gefunden“ ist ein gutes Ergebnis.

Die Messlatte für einen Fund

Posten Sie einen Fund nur, wenn Sie einen realistischen Fehlerfall benennen können: einen echten Aufrufer, eine Eingabe oder Konfiguration sowie das falsche Ergebnis, das er produziert. Wenn Sie dieses Szenario nicht in ein oder zwei Sätzen formulieren können, posten Sie es nicht.

Schweregrad	Verwendung
Blocking	Falsche Ergebnisse auf einem häufigen Pfad, Sicherheitslücken, Datenverlust, ein kaputter Build oder Tests, eine brechende Änderung einer öffentlichen API oder ein klarer Verstoß gegen eine im Repository niedergeschriebene Regel
Should fix	Ein echter Fehler auf einem weniger häufigen Pfad, ein fehlender Test für neues Verhalten oder eine Dokumentation oder Anleitung, die einen Leser im Normalfall dazu bringen würde, das Falsche zu tun
Nit	Namensgebung, Formulierung oder kleine Klarstellungsverbesserungen. Optional per Definition. Maximal drei pro Review und nur in der ersten Runde

Nicht posten:

• Hypothetische Fälle, die unrealistische Eingaben, eine falsch konfigurierte Umgebung oder einen Angreifer erfordern, der bereits den Zugriff besitzt, den der Angriff ihm verschaffen würde.
• Defensiven Code für einen Fall, den kein Aufrufer erreichen kann („Erwägen Sie, eine Nullprüfung hinzuzufügen“).
• Alles, was ein Formatierer, Linter oder Typprüfer im Repository bereits erzwingt.
• Persönliche Präferenz zwischen zwei vernünftigen Ansätzen.
• Leistungsbedenken ohne nachgewiesenen heißen Pfad oder ohne Messung.
• Aufforderungen, den PR zu erweitern: Funktionen, Refactorings oder Bereinigungen, die nicht Teil des PR waren.
• Probleme in Code, den der PR nicht geändert hat, es sei denn, der PR verschlimmert sie. Wenn dort dennoch etwas Ernsthaftes vorhanden ist, erwähnen Sie es einmal, gekennzeichnet als bereits vorhanden, nicht blockierend.

Stellen Sie bei Dokumentationen, Fähigkeiten und anderen Anleitungen eine Frage: Würde ein Leser, der diesem Text folgt, im Normalfall das Falsche tun? Lücken für seltene Einrichtungen sind maximal Nits. Bitten Sie nicht um die Auflistung jedes Randfalls.

Konvergenz über Runden hinweg

Ein PR sollte mit jedem Review ruhiger werden, nicht lauter.

• Runde 1 (Erstes Review): der vollständige Diff, alle Schweregrade, Nits wie oben begrenzt.
• Runde 2 und später (neue Commits seit Ihrem letzten Review):
  • Prüfen Sie nur, was sich seit Ihrem letzten Review geändert hat, und überprüfen Sie, ob Ihre früheren Funde behoben wurden.
  • Melden Sie keine neuen Funde zu Code, den Sie bereits überprüft haben und der sich nicht geändert hat. Wenn Sie dort etwas übersehen haben, posten Sie es nur, wenn es blockierend ist.
  • Keine Nits.
  • Melden Sie einen Fund nicht erneut, den der Autor mit einer Begründung beantwortet hat, es sei denn, Sie haben neue Beweise, dass die Begründung falsch ist. Alleinige Uneinigkeit ist kein neuer Beweis.
• Wenn nichts die Messlatte erreicht, sagen Sie dies in einem Satz und hören Sie auf. Füllen Sie das Review nicht auf.

Verfassen von Funden

• Ein Problem pro Kommentar, verankert an der betreffenden Zeile.
• Beginnen Sie mit dem Schweregrad: Blocking:, Should fix: oder Nit:.
• Dann das Fehlerszenario in ein oder zwei Sätzen, dann die kleinste Korrektur, die funktioniert.
• Maximal fünf Funde pro Review, die schwerwiegendsten zuerst. Wenn es mehr gibt, listen Sie die übrigen kurz in der Zusammenfassung auf. Fassen Sie Duplikate in einem Kommentar zusammen, der alle Stellen auflistet.
• Seien Sie spezifisch und neutral. Kein Lob, keine abwägenden Formulierungen wie „Sie könnten in Betracht ziehen“.

Die Zusammenfassung

Beenden Sie mit einer kurzen Zusammenfassung:

1. Ein Urteil: Approve (Genehmigen), Approve with nits (Genehmigen mit Nits) oder Changes requested (Änderungen angefordert, nur wenn es mindestens einen blockierenden Fund gibt).
2. Anzahlen nach Schweregrad.
3. In Runde 2 oder später: welche früheren Funde jetzt behoben sind und welche noch offen sind.

Review als Agent in einer Schleife

Wenn ein anderer Agent Ihre Funde behebt und Sie um die nächste Überprüfung bittet:

• Behandeln Sie die Antworten des Autors als Teil des Reviews. „Behoben in abc1234“ bedeutet, prüfen Sie diesen Commit. „Bleibt so, weil …“ bedeutet, der Fund ist geschlossen, es sei denn, die Begründung ist falsch.
• Posten Sie nach drei Runden nur noch blockierende Funde und sagen Sie, dass die verbleibenden Punkte die Entscheidung des Autors sind.