Vorher und Nachher
Erzeuge ein PNG: eine Tabelle mit einer Zeile pro visueller Änderung, und in jeder Zeile der Name der Änderung, eine einzeilige Notiz, der Screenshot vom Basis-Branch und der Screenshot vom Branch. Ein Leser, der den Code nicht gesehen hat, sollte allein aus dem Bild erkennen können, was anders aussieht und wo.
Das Bild ist nur so gut wie seine Liste der Änderungen. Eine Tabelle, die drei von fünf Änderungen zeigt oder eine Differenz aufgrund unterschiedlicher Daten statt des Codes anzeigt, führt den Leser in die Irre. Der Hauptaufwand besteht darin, jede visuelle Änderung zu finden und jedes Paar so aufzunehmen, dass nur der Code sich unterscheidet.
Wo die Bilder landen. Alles, was dieses Skill produziert, wird im Dokumente-Ordner des Benutzers gespeichert, in ~/Documents/before-after/<Repository>/<Branch>/: die Aufnahmen, das Manifest, eine Kopie von shots.mjs und das finale before-after.png. Die Skripte wählen diesen Ordner selbst und nehmen keinen Ausgabepfad entgegen; ein Benutzer, der ein anderes Wurzelverzeichnis als ~/Documents/before-after möchte, setzt die Umgebungsvariable BEFORE_AFTER_DIR, die ihm gehört, nicht dir. Schreibe die Bilder nirgendwo anders hin und verschiebe oder kopiere sie danach nicht; der Scratchpad dient nur für den Basis-Worktree und zum Erstellen von shots.mjs. Ein späterer Durchlauf für denselben Branch verwendet den Ordner erneut.
Zwei Skripte liegen in scripts/ neben dieser Datei: capture.mjs macht die Aufnahmen, und compose.mjs erstellt und prüft die Tabelle. Jedes dokumentiert sein Eingabeformat in seinem Header. Lies beide Header, bevor du beginnst.
Lokale Notizen. Wenn eine Datei namens LOCAL.md neben dieser Datei liegt, lies sie, bevor du beginnst. Sie enthält die eigenen Standardeinstellungen des Benutzers für die Projekte, an denen er arbeitet (Befehle, Hosts, Konten, Pfade) und ist nicht Teil des veröffentlichten Skills. Wo sie das betreffende Projekt abdeckt, zählt sie als Teil der Projektanweisungen; wo nicht, ignoriere sie.
1. Änderungen sammeln
Wenn kein Basis-Branch angegeben ist, verwende die Basis des Pull-Requests (gh pr view --json baseRefName --jq .baseRefName), andernfalls den Standard-Branch (git symbolic-ref --short refs/remotes/origin/HEAD), andernfalls origin/main. Bevorzuge die Remote-Tracking-Referenz. Uncommittete Arbeiten einschließen:
base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short # auch ungetrackte Dateien lesen
git log --oneline "$base"..HEAD
Lies auch die Pull-Request-Beschreibung und das Issue, falls vorhanden. Sie sagen oft, welche Bildschirme die Änderung betrifft, und enthalten Screenshots, die die Leute zu sehen erwarten.
2. Jede visuelle Änderung auflisten
Verfolge jeden Hunk nach außen zu dem, was ein Benutzer sieht:
- Code, Styles, Tokens, Icons, Kopien, Übersetzungen ansehen. Jedes davon ist ein Kandidat. Suche bei gemeinsam genutztem Code (einer UI-Komponente, einem Formatierungs-Helper, einem CSS-Token) nach seinen Aufrufern und liste jeden Bildschirm auf, der ihn rendert. Eine Änderung an gemeinsam genutztem Code zeigt sich normalerweise an mehr Stellen, als der Branch betraf.
- Datenzustände. Lies für jeden Bildschirm, welche Verzweigungen der geänderte Code nimmt: geladen, ladend, leer, Fehler, fehlender Wert, Null und Negativ, langer Text, ein Element und viele, jeder Modus oder jede Einstellung. Behalte nur die Zustände, deren Darstellung der Diff ändert.
- Interaktionszustände. Hover, Fokus, gedrückt, deaktiviert, ausgewählt; ein offenes Popover, Menü, Blatt oder Dialog; ein Feld, das einen Validierungsfehler anzeigt. Diese erfordern Schritte vor der Aufnahme (Schritt 4).
- Bildschirme, die der Branch hinzufügt oder entfernt. Diese haben nur eine Seite; die Zeile zeigt einen Platzhalter für die andere.
- Umgebungen, die das Projekt unterstützt, wo die Änderung anders aussehen könnte: Dark-Theme, mobile und Desktop-Breiten, eine andere Locale.
Sortiere die Kandidaten in drei Listen:
- Visuell: etwas auf dem Bildschirm unterscheidet sich. Diese werden Zeilen.
- Nicht visuell: die Änderung betrifft nur den Accessibility-Tree, Attribute, Screenreader-Text, Verhalten oder Codestruktur. Diese sind keine Zeilen. Nenne sie im Bericht, damit der Leser weiß, dass sie bedacht und nicht übersehen wurden. Wenn der Benutzer sie trotzdem sehen möchte, kann eine Zeile einen als Bild aufgenommenen Accessibility-Tree-Auszug enthalten, entsprechend gekennzeichnet.
- Unsicher: Markup- oder Klassenänderungen, die unsichtbar sein sollen, aber etwas verschieben oder einfärben könnten (ein neues Wrapper-Element, eine Positionierungsklasse, ein ausgetauschter Helper). Nimm diese auf und lass die Pixel-Prüfung entscheiden.
Eine Änderung an Bewegung (eine Animation, ein Übergang, dessen Timing) kann nicht in einem Standbild gezeigt werden. Setze sie unter „Nicht gezeigt“ in den Bericht und sage, wie man sie sehen kann.
Gruppiere Zeilen sinnvoll: eine Zeile pro eindeutigem Aussehen, nicht pro Aufrufort. Wenn zehn Bildschirme die geänderte Zelle auf dieselbe Weise verwenden, zeige ein oder zwei davon und nenne die restlichen in der Notiz. Ziele auf eine Tabelle, die jemand tatsächlich liest; ab etwa zwölf Zeilen erstelle ein zweites Bild pro Bereich und sage dies.
Wenn sowohl die visuelle als auch die unsichere Liste leer sind, höre hier auf. Sag dem Benutzer, dass der Branch keine visuellen Änderungen hat, liste auf, was betrachtet wurde und warum jedes Element nicht visuell ist, und erstelle kein Bild. Wenn nur unsichere Elemente existieren und jedes Paar sich als identisch herausstellt, ist das Ergebnis dasselbe, und die identischen Paare sind der Beleg: melde sie als geprüft und unverändert.
3. Basis und Branch lokal bauen
Erfasse beide Seiten aus lokalen Builds, niemals von einer Live-Umgebung: Eine Live-Umgebung hinkt dem Arbeitsbaum hinterher und kann uncommittete Arbeiten nicht zeigen.
-
Branch: der aktuelle Arbeitsbaum, erstellt nach der letzten Änderung.
-
Basis: ein separater Worktree am Merge-Base, damit der Arbeitsbaum des Benutzers nie berührt wird. Wechsle niemals Branches oder stashe im Checkout des Benutzers.
git worktree add --detach <scratchpad>/before-after-base "$base"Installiere dort Abhängigkeiten. Das Symlinken des Dependency-Verzeichnisses des Haupt-Checkouts ist nur in Ordnung, wenn der Diff die Lockdatei nicht berührt. Entferne den Worktree, wenn du fertig bist (
git worktree remove).
Verwende die dokumentierten Befehle des Projekts (lies seine README, AGENTS.md, CLAUDE.md, Entwicklungsdokumentation und jedes run-Skill). Beide Seiten müssen mit demselben Staging- oder Test-Backend kommunizieren, niemals mit Produktion. Wenn unklar ist, welcher Befehl auf welches Backend abzielt, lies die Build-Konfiguration, und wenn immer noch Zweifel bestehen, halte inne und frage. Bevor du etwas erfasst, überprüfe den Host einer echten API-Anfrage von jeder Seite.
Bevorzuge den Produktions-Build des Projekts, der statisch ausgeliefert wird (ein build gefolgt von einem preview oder einem beliebigen statischen Server) gegenüber seinem Dev-Server. Ein Dev-Server fügt Hot-Reload-Clients und Overlays hinzu, benötigt möglicherweise einen Watcher-Prozess pro Worktree und kann anders rendern als das, was ausgeliefert wird. Wenn du mit einem Tool baust, das nicht der eigene Build-Befehl des Projekts ist, überprüfe, ob die Seite rendert: Ein Projekt kann sein Bundle nachbearbeiten. Ein Build kann auch ein Ausgabeverzeichnis im Arbeitsbaum des Benutzers leeren oder überschreiben. Das sind generierte Dateien, sag aber im Bericht, was du neu gebaut hast, und lege das zurück, was die Dev-Umgebung erwartet, falls der Build es entfernt hat.
Bevor du einer Aufnahme vertraust, bestätige, dass sich die beiden Builds unterscheiden: lies das Markup des geänderten Elements auf jeder Seite und sieh die Änderung des Diffs darin. Zwei Server, die denselben Code ausliefern, ergeben identische Paare, die nichts beweisen.
Wähle, wie die beiden Builds bereitgestellt werden:
- Beide gleichzeitig auf zwei freien Ports. Das ist am einfachsten, und die beiden Aufnahmen eines Paars werden Sekunden auseinander aufgenommen. Es funktioniert, wenn die Bildschirme kein Login benötigen oder wenn ein Login einen Portwechsel überlebt. Cookies werden zwischen Ports auf demselben Host geteilt, aber Local Storage nicht, und ein Backend akzeptiert möglicherweise nur bestimmte Origins. Überprüfe, ob ein eingeloggter Bildschirm wirklich auf dem zweiten Port lädt, bevor du dich darauf verlässt.
- Nacheinander auf demselben Port. Stelle die Basis auf dem üblichen Port des Projekts bereit, nimm mit
--side=beforeauf, stoppe sie, stelle den Branch auf diesem Port bereit und nimm mit--side=afterauf. Gespeicherter Login-Status und erlaubte Origins gelten dann für beide. Die Aufnahmen liegen Minuten auseinander, daher müssen die Daten gemockt oder als stabil bekannt sein.
Wenn das Projekt ein Komponenten-Katalog (Storybook, eine „Workshop“-App oder ähnlich) hat und die Änderung in einer gemeinsamen Komponente lebt, ist die Erfassung dort günstiger und stabiler als in der vollständigen App und benötigt normalerweise kein Login. Erfasse dennoch nach Möglichkeit mindestens einen echten Bildschirm pro Änderung, damit das Bild sie im Kontext zeigt. Wenn ein echter Bildschirm nicht erreicht werden kann (z. B. kein Test-Login), sag dies unter „Nicht gezeigt“.
4. Jedes Paar unter identischen Bedingungen aufnehmen
Schreibe ein shots.mjs im Scratchpad, im Format des Headers von scripts/capture.mjs, und führe es vom Projektstamm aus, damit Playwright richtig auflöst und der Ausgabeordner den richtigen Repository- und Branch-Namen erhält:
node <dieses Skill>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>
Das Skript führt dieselben Schritte gegen beide URLs aus. Es verwendet das installierte Chrome, einen Device Scale Factor von 2 und reduzierte Bewegung. Es deaktiviert Übergänge, setzt unendliche Animationen (ein Schimmern, ein Spinner) auf ihren ersten Frame und beendet endliche, wartet auf Schriftarten und darauf, dass das Netzwerk zur Ruhe kommt, und friert die Uhr ein, wenn du eine Zeit angibst. Es schreibt shots/<slug>.before.png, shots/<slug>.after.png und das manifest.json für Schritt 5 in den oben beschriebenen Dokumente-Ordner, kopiert shots.mjs dort hinein und gibt den Pfad des Ordners als letzte Zeile aus. --only=<slug> nimmt eine Zeile erneut auf. Eine fehlgeschlagene Aufnahme hinterlässt ein <slug>.<side>.FAILED.png des gesamten Viewports, das zeigt, wie die Seite stattdessen aussah.
Wenn das End-to-End-Setup des Projekts einen gespeicherten Login-Status hat, übergib ihn als storageState (lies die Projektdokumentation, wie er erstellt wird). In Orca funktioniert der eingebettete Browser (das orca-cli-Skill) auch für ein oder zwei Paare, aber ein Skript macht die Paare wiederholbar.
Was du in shots.mjs richtig machen musst:
- Gleiche Daten auf beiden Seiten. Live-Daten driften zwischen zwei Aufnahmen: Preise ticken und Listen sortieren neu. Bevorzuge, die Antworten zu mocken, von denen der Bildschirm im
mockder Aufnahme abhängt: Erfasse eine echte Payload vom Staging und erfülle beide Seiten damit. Zwei Einschränkungen:- Wenn der Branch die Anfrage oder die Antwortform ändert (einen neuen Endpunkt, ein neues Feld, einen geänderten Decoder), kann eine Payload nicht beide Seiten bedienen. Gib jeder Seite die Payload, die ihr Code erwartet, aufgebaut aus denselben zugrunde liegenden Werten, und sag dies im Untertitel.
- Daten, die über einen WebSocket oder Server-Sent Events ankommen, werden von
page.routenicht berührt. Verwendepage.routeWebSocketoder wähle einen Bildschirm oder eine Zeit, in der der Stream ruhig ist, oder verstecke das Live-Element, wenn es nicht das Thema ist.
- Erreiche den Zustand gezielt. Lade-, Fehler- und fehlende-Wert-Zustände treten selten auf Testkonten auf: Erzeuge sie in
mock(verzögere eine Antwort, lasse sie fehlschlagen, setze ein Feld auf null). Leite die Anforderungspfade und Feldnamen aus dem Code ab, nicht durch Raten. Erreiche Interaktionszustände insteps(Hover, Fokus, Klicken zum Öffnen). - Beschneide auf die Änderung mit Kontext. Setze
targetauf das kleinste Element, das die Änderung zeigt und noch als Teil seines Bildschirms erkennbar ist: die Karte, die Tabelle, das Blatt, nicht die ganze Seite. Ziel ist ein Zuschnitt von höchstens etwa 650 CSS-Px Breite: das passt nebeneinander in voller Größe. Ein breiterer Zuschnitt wird gestapelt (vorher über nachher), und einer breiter als etwa 1300 CSS-Px wird verkleinert, sodass sein Text schwerer lesbar wird. Verwende auf beiden Seiten dasselbe Ziel, damit die Zuschnitte übereinstimmen. - Verstecke, was nicht das Thema ist und sich ständig bewegt (ein Ticker, eine Uhr, ein spät geladener Avatar) mit einem Style-Tag in
steps, auf beiden Seiten.
5. Zusammensetzen und prüfen
node <dieses Skill>/scripts/compose.mjs <ordner>/manifest.json [--diff] [--stack]
Das Bild wird neben dem Manifest als before-after.png geschrieben, und sein Pfad ist die letzte Ausgabezeile. --diff fügt ein Bild pro Zeile hinzu, das die geänderten Pixel in Magenta zeigt. Verwende es, wenn die Änderung klein oder subtil ist (Abstand, eine Farbe, ein Glyph); lasse es weg, wenn die Änderung offensichtlich ist. Wenn die beiden Aufnahmen einer Zeile unterschiedliche Größen haben, wird der Vergleich oben links ausgerichtet, sodass alles nach der Verschiebung als geändert zählt; die Zeile sagt dies, und das Diff-Bild ist dann nur ein grober Anhaltspunkt.
Das Skript zeichnet beide Aufnahmen einer Zeile im gleichen Maßstab. Es gibt den Anteil geänderter Pixel pro Zeile und aus, wie jede Zeile angeordnet wurde, und beendet sich mit Code 3, wenn ein Paar identisch ist. Dann:
- Ein identisches Paar bedeutet, dass die Aufnahme die Änderung verfehlt hat (falscher Zustand, falscher Bildschirm, ein Cache, ein Basis-Build, der nicht wirklich die Basis ist) oder die Änderung nicht visuell ist. Finde heraus, welcher Fall vorliegt. Korrigiere die Aufnahme oder nimm die Zeile aus dem Manifest und verschiebe das Element in die nicht-visuelle Liste als „geprüft, kein Pixel unterscheidet sich“. Versende niemals eine Zeile mit einem identischen Paar.
- Sieh dir das Bild an (lies das PNG) und überprüfe jede Zeile: Der Unterschied, den du siehst, ist der, den die Notiz beschreibt, und nichts anderes unterscheidet sich. Ein Unterschied, der nicht durch den Diff erklärt wird (ein anderer Preis, eine fehlende Zeile, verschobenes Layout woanders) ist Daten-Drift oder eine unerwartete Regression. Nimm erneut auf oder melde es dem Benutzer als mögliche Regression. Verstecke es nicht.
- Überprüfe, ob der Text in jeder Aufnahme lesbar ist. Reagiere auf jede „Text möglicherweise nicht lesbar“-Warnung des Skripts: Schneide enger zu und nimm diese Zeile mit
--onlyerneut auf. - Wenn das Bild sehr lang ist, teile es nach Bereich auf: Erstelle einen Unterordner pro Bereich im Ordner des Branches, jeder mit eigenem
manifest.json, dessen Pfade auf../shots/...zeigen, und setze jeden zusammen.
6. Bericht
Gib dem Benutzer:
- Den vollständigen absoluten Pfad zum PNG.
- Die Zeilen, eine pro Zeile.
- Nicht gezeigt: die nicht-visuellen Änderungen, die unsicheren Elemente, die der Pixel-Check als unverändert befunden hat, Bewegungsänderungen, die visuellen, die du nicht erfassen konntest (und warum), und die Aufruforte, die als Duplikate einer gezeigten Zeile weggelassen wurden.
- Alles Unerwartete, das der Pixel-Check oder dein eigener Blick zutage gefördert hat.
- Wie die Paare erstellt wurden (echte Staging-Daten oder welche Antworten gemockt wurden; ein Katalog oder die echte App), damit der Leser weiß, was die Bilder beweisen.
Stoppe die von dir gestarteten Dev-Server und entferne den Basis-Worktree. Die Aufnahmen, die Kopie von shots.mjs und das Manifest bleiben im Ausgabeordner, damit ein späterer Durchlauf mit --only eine einzelne Zeile erneut erfassen kann.