pr-diagram: Einen Pull Request diagrammieren
Ziel: Ein Diagramm, das einem Reviewer in 10 Sekunden zeigt, was die Änderung bewirkt und wie der Ablauf ist. Es ist keine Karte des gesamten Codebestands.
Guardrails (absolut)
- Code niemals ändern. Keine Dateien im Repository bearbeiten, erstellen oder löschen, und nicht committen, pushen oder Branches wechseln. Die
.mmd-Datei kommt in ein temporäres oder Scratchpad-Verzeichnis, niemals in das Repository. - Niemals genehmigen, Änderungen anfordern oder mergen. Führe nicht
gh pr review,gh pr mergeodergh pr closeaus und poste keine PR-Kommentare. Der einzige Schreibvorgang, den diese Skill jemals ausführt, istgh pr edit --body-filefür die Beschreibung. - Ein Schritt der Zustimmung: Zeige die vollständige neue Beschreibung und frage in derselben Nachricht, ob sie gepostet werden soll. Frage nicht „Soll ich posten?“ und zeige die Beschreibung erst danach. Das ergibt zwei Runden der Zustimmung. Zeige den gesamten Body, nicht nur den hinzugefügten Abschnitt, und beende die Nachricht mit der Frage. „Sieht gut aus“, „Poste es“ oder „Ja“ auf diese Nachricht gilt als Zustimmung. Stille, eine Frage oder eine gewünschte Anpassung nicht. Nach einer Anpassung den gesamten Body und die Frage erneut zusammen zeigen.
- Alles, was du hinzufügst, mit dieser exakten Zeile am Ende des hinzugefügten Blocks signieren:
- Generiert von Claude Code
Argumente
/pr-diagramverwendet den PR für den aktuellen Branch, oder den lokalen Branch-Diff, falls kein PR existiert./pr-diagram 123oder eine PR-URL zielt auf diesen PR (funktioniert für andere Repos über URL).type=td|lr|sequence|state|ererzwingt einen Diagrammtyp.
Schritt 1: Den Diff sammeln
Mit einem PR (alle schreibgeschützt):
gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>
Kein PR: Finde die Basis (gh repo view --json defaultBranchRef -q .defaultBranchRef.name), dann
git diff --stat $(git merge-base origin/<base> HEAD) und git diff $(git merge-base origin/<base> HEAD).
Große Diffs (>1500 geänderte Zeilen oder >30 Dateien): Lies zuerst --stat und den PR-Body, dann nur die Dateien, die die Logik tragen. Überspringe Lockfiles, generierten Code, Snapshots und reine Umbenennungen.
Schritt 2: Den Ablauf identifizieren
Ein Diff zeigt Zeilen, nicht Beziehungen. Lies die aktuelle Version jeder betroffenen Datei (nur lesen) und ermittle:
- Den Ablauf: Was löst ihn aus (Anfrage, Job, Ereignis, Benutzeraktion), was läuft in welcher Reihenfolge und wo endet er (Antwort, DB-Schreibvorgang, Nachricht, externer Aufruf).
- Den Status jedes Schritts: neu (durch diesen PR hinzugefügt), geändert (vorhanden, modifiziert) oder unverändert (Kontext, den der Reviewer braucht, um die Änderung einzuordnen).
- Die Zusammenfassung in einem Satz, die ein Reviewer braucht („Fügt einen Wiederholungsschritt vor dem Zahlungsaufruf hinzu“).
Verwende PR-Titel und -Body als Absicht, aber vertraue dem Code, wenn sie widersprechen. Jeder Knoten und jede Kante muss auf Code zurückgehen, den du gelesen hast. Erfinde niemals einen Schritt, um das Bild sauberer zu machen. Wenn etwas unsicher ist, lasse es weg und sage das.
Entfernter Code: Wenn ein entfernter Schritt für Reviewer wichtig ist, zeige ihn als grauen Knoten mit der Beschriftung „(entfernt)“ und einer gepunkteten Kante. Sonst lasse ihn weg.
Schritt 3: Den Diagrammtyp wählen
Die Ausgabe ist immer Mermaid in einer .mmd-Datei. Wähle den Typ, der zum Ablauf passt:
| Die Änderung ist hauptsächlich... | Diagramm |
|---|---|
| ein Schritt-für-Schritt-Prozess oder eine Entscheidungslogik | flowchart TD (von oben nach unten) |
| Komponenten oder Dienste, die miteinander verbunden sind, oder eine Pipeline | flowchart LR (von links nach rechts) |
| eine Anfrage oder Nachricht, die zwischen 3+ Teilnehmern über die Zeit läuft | sequenceDiagram |
| ein Status- oder Lebenszykluswechsel (ausstehend → genehmigt → …) | stateDiagram-v2 |
| Tabellen, Spalten oder Beziehungen (Migrationen) | erDiagram |
Verwende ein Diagramm. Verwende zwei nur, wenn der PR eindeutig sowohl die Struktur als auch den Laufzeitablauf ändert. Wenn der PR zu klein für ein Bild ist (1–2 Dateien, kein neuer Ablauf), sage das und höre auf.
Schritt 4: Das Diagramm erstellen
Beschriftungen: einfaches Englisch, kurz.
- Schreibe, was ein Schritt tut, keine Code-Identifikatoren:
Prüfe, ob Karte nicht abgelaufen ist, nichtCardValidator.validateExpiry(). Wenn der Name hilft, verwende eine Kurzform:PaymentReconciliationServicewird zuZahlungsabgleicher. - Kürze URLs auf den Pfad:
api.example.com/v2/orders/{id}/refundswird zuPOST /orders/:id/refunds. - Rechteck-Knoten
A["..."]: maximal 35 Zeichen pro Zeile. - Stadion
A(["..."])und abgerundeteA("...")Knoten: maximal 25 Zeichen pro Zeile.** - Wenn ein Knoten mehr Details benötigt, teile ihn mit
<br/>in Zeilen auf (jede Zeile innerhalb ihres Limits). Verwende maximal 3 Zeilen. - Formbedeutung: Rechteck = Schritt oder Komponente, Stadion = Start oder Ende (Auslöser, Antwort),
abgerundet = externes System, Raute
A{"..."}= Entscheidung (maximal 25 Zeichen), ZylinderA[("...")]= Datenspeicher. - Maximal 15 Knoten. Verwende
subgraph, um nach Dienst oder Bereich zu gruppieren, wenn es mehr als etwa 8 gibt. - Beschrifte Kanten kurz in einfachem Englisch (
sendet,bei Fehler,speichert), maximal 20 Zeichen. - Sequenzdiagramme: Teilnehmer- und Aktornamen maximal 25 Zeichen. Nachrichten,
loop,alt, undopt-Beschriftungen sowieNote-Text maximal 35 Zeichen pro Zeile (mit<br/>teilen, maximal 3 Zeilen). Verwende kein;oder#im Nachrichtentext, da diese die Analyse unterbrechen.
Farben (lesbar sowohl im hellen als auch im dunklen GitHub-Modus). Verwende helle Füllungen mit dunklem Text und einem starken Rand:
classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged
Jeder Knoten erhält genau eine Klasse. In stateDiagram-v2 verwende classDef plus class ZustandsName new.
Sequenzdiagramme: Klassen gelten nicht. Ein rect setzt nur den Hintergrund, und die Textfarbe stammt vom GitHub-Theme (hellgrau im Dunkelmodus). Eine deckende helle Füllung macht den Text im Dunkelmodus unlesbar, also verwende immer durchscheinende Tönungen:
- neu:
rect rgba(46,160,67,0.18) - geändert:
rect rgba(210,153,34,0.22) - unverändert: kein
rect
Verwende niemals deckende rect rgb(...). Füge Note over für die wichtigste Änderung hinzu.
Nur-neue PRs (nichts geändert oder unverändert): Behalte die grüne Tönung bei und sage zusätzlich in der Zusammenfassung „Alles in diesem Diagramm ist neuer Code“, da es nichts gibt, womit es kontrastiert werden könnte.
Syntaxfallen (sie unterbrechen die GitHub-Darstellung). Überprüfe jede:
- Knoten-IDs müssen einfache alphanumerische Zeichen sein (
ChkCard). Beschriftungen müssen immer in Anführungszeichen stehen:ChkCard["Check card"]. - Verwende
#quot;für ein wörtliches"innerhalb einer Beschriftung.<br/>ist das einzige erlaubte HTML in Beschriftungen. - Verwende niemals
end(Kleinbuchstaben) als ID. Setze immer Leerzeichen um Pfeile (A --> B), daA---oBals Kreis-Kante geparst wird. subgraph Id["Label"]…end. Jeder Subgraph benötigt sein eigenesend.- Sequenz-Teilnehmer:
participant API as Orders API(die ID hat keine Leerzeichen). erDiagram-Attributtypen müssen einzelne Wörter sein (varchar, nichtvarchar(255)).- Keine
%%{init}%%-Theme-Blöcke. DieclassDef-Farben kümmern sich um beide Modi.
Speichere das Diagramm als pr-<N>-diagram.mmd (oder branch-<Name>-diagram.mmd) in einem temporären oder Scratchpad-Verzeichnis. Gib den vollständigen Pfad an.
Schritt 5: Selbstprüfung vor der Präsentation
- Zähle die Zeichen in jeder Beschriftungszeile gegen ihr Limit (35 für Rechtecke, 25 für Stadion, abgerundete und Rauten-Knoten, 20 für Kantenbeschriftungen; in Sequenzdiagrammen 25 für Teilnehmer und 35 für Nachrichten, Blöcke und Notizen). Korrigiere alle, die darüber liegen.
- Stelle sicher, dass keine Beschriftung einen rohen Code-Identifikator enthält (camelCase,
Foo.bar(), snake_case), wo einfaches Englisch funktioniert. - Überprüfe die Farbe jedes Knotens: Ist er wirklich neu, geändert oder unverändert im Diff?
- Optionaler Rendering-Check:
npx -y @mermaid-js/mermaid-cli -i <datei>.mmd -o <datei>.svg. Der erste Lauf lädt Chromium herunter (~150 MB), also frage vor der Ausführung.
Schritt 6: Präsentieren
Verwende dieses Format im Chat:
**<Ein-Satz-Zusammenfassung dessen, was der PR tut>**
<2–3 Sätze: Der Ablauf in Worten, wo die Änderung darin sitzt, was ausgelassen oder unsicher ist>
```mermaid
...
```
**Legende:** grün = neuer Code · gelb = geänderter Code · grau (oder keine Tönung) = unveränderter Kontext
Gespeichert: <vollständiger Pfad zur .mmd>
Schritt 7: Die vollständige Beschreibung zeigen und um Posten bitten (gleiche Nachricht wie Schritt 6)
Tue dies vor dem Antworten, sodass das Diagramm, die vollständige neue Beschreibung und die Frage zusammen rausgehen:
-
Hole den aktuellen Body in eine temporäre Datei:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
Erstelle den neuen Body in
<tmp>/body-new.md. Setze den Block zwischen Markierungen, damit Wiederholungen ihn ersetzen statt anhäufen:<!-- pr-diagram:start --> ## Änderungsdiagramm <Zusammenfassungssatz> ```mermaid ...Legende: grün = neu · gelb = geändert · grau (oder keine Tönung) = unverändert (Verwende Wörter, keine Farb-Emojis. Emojis werden auf jedem Betriebssystem anders dargestellt, z.B. ⬜ erscheint auf Windows als Lavendel.)
- Generiert von Claude Code
Wenn die Markierungen bereits existieren, ersetze nur den Text zwischen ihnen. Andernfalls hänge den Block nach einer Leerzeile an. Jedes andere Byte des ursprünglichen Bodys bleibt unverändert. -
Überprüfe, dass der neue Body mit dem vollständigen Original-Body beginnt. Er muss Byte für Byte erhalten bleiben.
-
Beende die Nachricht mit dem vollständigen neuen Body in einem umschlossenen Block, der PR-URL und der Frage: "Poste dies an ?" Dann warte und halte an (Guardrail 3).
Schritt 8: Posten (nur nach einem Ja auf die Nachricht von Schritt 7)
gh pr edit <N> --body-file <tmp>/body-new.md. Verwende niemals--bodymit Inline-Text, da Shell-Quoting Backticks und$verstümmelt.- Überprüfe mit
gh pr view <N> --json body -q .body, dass es mitbody-new.mdübereinstimmt, und gib dann die PR-URL. Ignoriere nachgestellte Leerzeichen beim Vergleich, da-qeinen Zeilenumbruch hinzufügt. Vergleiche zum Beispiel.rstrip()von beiden in Python.
Noch kein PR (nur lokaler Branch)? Biete den Block zum Einfügen an, wenn der Benutzer den PR eröffnet. Erstelle den PR nicht.
Don'ts
- Diagrammiere nicht jede Datei. Ein Diagramm von allem zeigt nichts.
- Setze keine Geheimnisse, internen Hostnamen, vollständigen URLs mit Tokens oder Abfragezeichenfolgen oder Kundendaten in Beschriftungen.