CommunitySchreiben & Editierengithub.com

PR-Erklärer

Erkläre einen Pull-Request, eine Bug-Fix oder eine lokale Änderung einem Teamkollegen – als eigenständige HTML-Seite (Standard) oder als Markdown-Übergabe (--md). Deckt ein Feature ab (Warum, Architektur, Ablauf, wichtiger Code, Verifikation) oder einen Bug-Fix (Symptom, Ursache, Lösung, Nachweis). Verwende es, wenn du gebeten wirst, „diesen PR/Fix/Änderung zu erklären“, „einen Walkthrough zu schreiben“, „eine Übergabe zu verfassen“, „einen Review-Leitfaden zu erstellen“ oder bevor du Arbeit übergibst. Flags: --concise für eine Zwei-Minuten-Version, --local für nicht committete oder nicht gepushte Arbeit, --md für HANDOVER.md-artiges Markdown.

Was ist PR-Erklärer?

Der PR-Erklärer ist ein KI-Agenten-Skill, der entwickelt wurde, um komplexe Code-Änderungen für Junior-Entwickler in einem Team verständlich zu machen. Er nimmt einen Pull-Request (PR), einen Bug-Fix oder lokale Änderungen und generiert ein einziges, in sich geschlossenes Dokument (standardmäßig HTML, optional als Markdown), das die Änderung von Grund auf erklärt: was das Problem war, wie das System funktioniert, was die Änderung bewirkt und wie sie verifiziert wurde. Der Skill unterstützt die Plattformen gh CLI und git und läuft in Terminal-Umgebungen wie Claude Code. Er analysiert den Diff, das umgebende Code und Konversationen, erstellt eine Gliederung je nach Art der Änderung (Feature oder Bug-Fix) und generiert einen finalen Bericht mit Code-Schnipseln, optionalen Diagrammen (Mermaid) und Verifikationsdetails. Benutzer können mit Flags wie --concise (Kurzfassung), --local (lokale Änderungen) oder --md (Markdown-Ausgabe) steuern. Der Skill stellt sicher, dass der Bericht technisch genau, auf Junior-Niveau lesbar und als Endfassung formuliert ist. Er vermeidet nicht-technische Analogien, definiert Grundlagen nicht und kennzeichnet unsichere Behauptungen explizit. Nach der Generierung prüft der Skill das Dokument auf Richtigkeit und berichtet über den Dateipfad, den Modus, die verwendeten Visualisierungen und die Verifikationsläufe.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more Schreiben & Editieren skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht PR-Erklärer?

Erstelle ein Dokument, das einem Teamkollegen eine Änderung erklärt: Was falsch war oder fehlte, wie das System darum herum funktioniert, was die Änderung bewirkt und wie wir wissen, dass es funktioniert.

Argumente

  • Ziel: eine PR-Nummer oder URL oder nichts.
    • Mit einer PR und verfügbarer gh-CLI: Details mit gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files und den Diff mit gh pr diff <url> abrufen. Umgebenden Code am Head-Commit der PR lesen (git show <headRefOid>:<path>), nicht lokales HEAD.
    • Ohne PR oder ohne gh: lokale Änderung erklären. git diff <base>...HEAD für Commits und git diff plus git status für nicht committete Arbeit verwenden, wobei <base> der Standard-Branch oder der erste Commit ist.
  • --local: auch bei vorhandener PR den lokalen Checkout verwenden (nicht gepushte Arbeit). Auf der Seite vermerken, dass sie lokale Änderungen widerspiegelt.
  • --concise: eine kurze Version, die in etwa zwei Minuten lesbar ist. Höchstens eine Grafik, höchstens 3 Schnipsel, kein Inhaltsverzeichnis, 1–3 Sätze pro Abschnitt.
  • --md: Markdown statt HTML ausgeben (Standard-Datei HANDOVER.md im Repository-Root, es sei denn, der Benutzer gibt einen Namen an). Für Übergaben und wenn kein Browser zur Hand ist.

Zielgruppe und Ton

  • Der Leser ist ein Junior-Entwickler im Team. Kurze Sätze, einfache Verben, eine Idee pro Absatz verwenden.
  • Grundlagen nicht definieren (REST, SQL, JWT, React-Hooks) und keine nicht-technischen Analogien verwenden. Technisch bleiben, mit echten Modul-, Funktions-, Routen- und Feldnamen sowie echten Zahlen.
  • Die Formulierung einfach halten, nicht den Inhalt. Ungewöhnliche Bibliotheksaufrufe oder Muster beim ersten Auftreten erklären.
  • Als Endfassung schreiben. Den aktuellen Zustand direkt beschreiben. Kein Changelog oder „früher dachten wir“-Formulierung.
  • Ehrlich bezüglich der Sicherheit sein. Unbewiesene Behauptungen mit „wahrscheinlich, noch nicht bestätigt“ kennzeichnen.

Umfang: die Änderung erklären, nicht den Diff

  • Die Dateien auswählen, die die Geschichte erzählen, und darin nur die relevanten Zeilen.
  • 1–3 Schnipsel pro Datei verwenden, jeder unter ~25 Zeilen, mit ... für ausgelassene Teile. Jeden mit Dateipfad und 2–4 Sätzen versehen, was er tut und warum.
  • Bei einem Fix den Code zeigen, der den Bug verursacht hat, sowie den Diff des Fixes.
  • Code nach Runtime-Ablauf ordnen, nicht nach Diff-Reihenfolge.
  • Plumbing, Umbenennungen und Formatierung überspringen. In einem Satz erwähnen, wenn ein Reviewer sie im Diff sehen wird.

1. Die Änderung verstehen

  • Den Diff und den umgebenden Code lesen. Den Modus festlegen:
    • Feature: neues Verhalten oder große Umstrukturierung.
    • Bug-Fix: ein Symptom, eine Ursache und eine Lösung.
  • Den letzten Verifikationslauf finden: Testbefehl und -anzahlen, und idealerweise den Nachweis, dass ein neuer Regressionstest ohne den Fix fehlschlägt und mit ihm besteht. Wenn dieser Nachweis nicht existiert und es günstig ist, ihn erstellen: git stash push -- <src files>, den Test ausführen, dann git stash pop. Auch nach einem manuellen oder End-to-End-Check suchen (CLI-Ausgabe, eine Anfrage, ein Screenshot). Nur den letzten Lauf von jedem zeigen.
  • Erkenntnisse aus der Konversation nutzen (Ursachenanalyse, QA-Bericht, Ticket), wo vorhanden.

2. Gerüst

Jedes Dokument beginnt mit einer Augenbrauenzeile (repo · PR #n · ticket oder repo · lokale Änderungen), einem Titel in einfacher Sprache und einer Einleitung von 1–2 Sätzen.

Bug-Fix

  1. Was schiefgelaufen ist: das Symptom, wo es gesehen wurde, was ausgeschlossen wurde.
  2. Ursache: die genaue Stelle, an der die Daten oder der Ablauf brechen (datei:zeile), mit einer Grafik, falls hilfreich.
  3. Der Code, der es verursacht hat: ein oder zwei Schnipsel.
  4. Der Fix: ein Diff-Schnipsel und warum er funktioniert. Nebeneffekte nennen, die er ebenfalls behebt.
  5. Wie wir es wissen: ein Regressionstest, der vorher fehlschlägt und nachher besteht, Gesamtsuite-Anzahlen, ein manueller Check.
  6. Erkenntnisse: 2–4 Lektionen, die ein Junior anderswo wiederverwenden kann.

Feature

  1. Warum: das Problem oder Ziel, mit Belegen.
  2. Wo es sitzt: Architektur- oder Modulkontext (Diagramm), plus was absichtlich unverändert ist.
  3. Wie es abläuft: Schritte oder ein Ablaufdiagramm, verknüpft mit den Code-Karten.
  4. Code-Walkthrough: eine Karte pro wichtiger Datei, in Ablaufreihenfolge.
  5. Verhalten, das man kennen sollte: Randfälle, Zustände, Fehlermodi (eine Tabelle, wenn mehr als 3).
  6. Verifikation: nur den letzten Lauf.
  7. Erkenntnis für Reviewer: das mentale Modell in 2–3 Zeilen und wo im Diff am genauesten hingeschaut werden sollte.

Übergabe-Ergänzungen (immer mit --md einfügen; in HTML optional):

  • Wie ausführen / testen: genaue Befehle.
  • Getroffene Annahmen: Entscheidungen, wo die Spezifikation still war, und warum.
  • Offene Fragen für das Business: geordnet nach Auswirkung.
  • Risiken und Rollback: was in Produktion schiefgehen könnte und wie zurückgesetzt wird.
  • Nächste Schritte: was du mit mehr Zeit tun würdest.

Kurzfassung: nur Was schiefgelaufen ist / Was und warum, Ursache / Wie es funktioniert, Der Fix / Wichtiger Code und Wie wir es wissen.

3. Grafiken: nur, wenn sie etwas erklären, was der Text nicht kann

InhaltVerwendung
Modul- oder Dienstarchitektur, wer wen aufruft, AnfragesequenzMermaid flowchart / sequenceDiagram (≤ ~12 Knoten)
Ein Zweig, der sich vorher und nachher anders verhältVorher/Nachher-Tabelle oder ein kleines statisches SVG
Daten, die durch Stufen gehen, von einem Filter verworfene WerteEine Tabelle mit Beispiel-Eingaben → Ausgaben, vorher vs. nachher
Zustände, Befehle, Risiken, VerträgeTabellen

In Markdown umfasste ```mermaid-Blöcke verwenden (GitHub rendert sie). Animationen nur hinzufügen, wenn der Benutzer darum bittet.

4. Erstellung

  • HTML: von references/page-template.html ausgehen (in sich geschlossen, helles und dunkles Design, Mermaid und highlight.js von einem CDN). Speichern unter .pr-review/<name>.html, benannt nach dem Ticket oder der PR, oder local-<kurzbeschreibung>. Aus Git ausschließen: wenn git check-ignore -q .pr-review/ fehlschlägt, .pr-review/ an .git/info/exclude anhängen. .gitignore nur auf Anfrage bearbeiten.
    • Code-Schnipsel: <pre><code class="language-<sprache>">…</code></pre>, HTML-escaped. Für einen Fix-Diff language-diff mit -/+-Zeilen verwenden.
    • Mermaid: <pre class="mermaid">…</pre>. Niemals Farben fest codieren.
  • Markdown (--md): einfaches GitHub-Flavored Markdown, gleiches Gerüst, kein HTML.

5. Einmal prüfen

  • HTML: wenn ein Browser-Werkzeug verfügbar ist, die Seite einmal in Desktop-Breite und einmal bei ~400px öffnen. Prüfen, ob Mermaid rendert und Code hervorgehoben ist, in einem Durchgang beheben, nicht wiederholen. Sonst sagen, dass es nicht in der Vorschau war, und den Befehl zum Öffnen angeben (open auf macOS, start auf Windows, xdg-open auf Linux).
  • Jedes datei:zeile, jede Zahl und jeden Befehl auf der Seite erneut mit dem Code abgleichen. Fakten müssen exakt sein.

6. Rückmeldung

Antworten mit:

  • dem Dateipfad
  • dem Modus und den abgedeckten Abschnitten
  • den verwendeten Grafiken und was jede erklärt
  • welchem Verifikationslauf das Dokument zeigt
  • allem, was als „noch nicht bestätigt“ markiert ist

Niemals einen PR-Text bearbeiten, einen Kommentar posten oder etwas pushen, ohne vorher zu fragen.

Verwandte Skills