Was macht Arbeitsbroschüre?
Nach Abschluss einer Arbeit möchte der Benutzer zweierlei:
- Die normale Zusammenfassung im Chat, genau wie du sie ohnehin schreiben würdest (was geändert wurde, wo es steht, was nicht erledigt ist). Diese Fähigkeit ersetzt oder verkürzt diese Zusammenfassung nicht.
- Eine Broschüre: eine eigenständige HTML-Seite, die dieselbe Arbeit visuell darstellt, sodass der Benutzer sie neben dem Chat öffnen und die Änderung anhand von Diagrammen, Screenshots und kommentiertem Code statt Absätzen nachvollziehen kann.
Die Broschüre muss code-akurat sein. Jede Behauptung, Zahl, jeder Dateipfad und Screenshot stammt aus dem tatsächlichen Diff, den ausgeführten Befehlen und der betrachteten App. Erfinde niemals einen Test, der nicht ausgeführt wurde, oder ein Ergebnis, das du nicht gesehen hast.
Schritte
1. Zuerst die Chat-Zusammenfassung schreiben
Schließe die Arbeit wie gewohnt ab, inklusive deiner normalen Textzusammenfassung und wrap_up (falls die App eine hat). Erstelle danach die Broschüre. Wenn der Benutzer nur die Broschüre für eine frühere Arbeit angefordert hat, springe direkt zu Schritt 2.
Nachdem ein PR eröffnet wurde (der PostToolUse-Hook des Plugins oder einer in deinen Einstellungen fügt nach gh pr create eine Erinnerung hinzu), erstelle die Broschüre für diesen PR mit gather.sh --pr <N> im selben Durchlauf und füge den Broschüren-Link in deine abschließende Nachricht ein. Bearbeite den PR-Textkörper nicht, um ihn hinzuzufügen, es sei denn, der Benutzer bittet darum. Überspringe die Broschüre nur, wenn der PR eine triviale Einzeiler-Änderung ist (Tippfehler, Versionsnummer).
2. Fakten sammeln
Führe das Hilfsskript vom Repository-Stamm aus aus (es gibt Commits, eine pro-Datei-Diffstatistik gruppiert nach Ordner, uncommittete Änderungen und PR-Informationen aus):
bash <skill-dir>/scripts/gather.sh # dieser Branch vs. main + uncommittet
bash <skill-dir>/scripts/gather.sh A..B # beliebiger Git-Bereich (z. B. bereits gemergte Arbeit)
bash <skill-dir>/scripts/gather.sh --pr 51 # ein GitHub-PR
Lies dann die relevanten Teile des Diffs (git diff <bereich> -- <pfad>), nicht das Ganze. Sammle außerdem aus diesem Gespräch:
- Warum: das Problem oder die Anfrage in den eigenen Worten des Benutzers.
- Entscheidungen: Optionen, die du abgewogen hast, und warum du dich für diese entschieden hast.
- Verifikation: ausgeführte Befehle und ihre tatsächliche Ausgabe, aufgenommene Screenshots, was du im Browser oder Simulator geprüft hast und was du nicht verifizieren konntest.
- Offene Punkte: Folgemaßnahmen, Risiken, alles Unerledigte.
- Benötigt den Benutzer: alles, was nur er entscheiden, mit eigenen Augen prüfen oder genehmigen kann.
3. Die echte App erfassen (wenn die Änderung sichtbar ist)
Wenn die Änderung in einer Benutzeroberfläche sichtbar ist, sollte die Broschüre die tatsächliche Anwendung zeigen, nicht eine Beschreibung davon.
- Nachher: Mache einen Screenshot der laufenden App auf den geänderten Bildschirmen mit den Vorschau-Tools (
preview_startmit dem launch.json-Server des Projekts, navigiere,computer {action: "screenshot"}) oder dem iOS-Simulatorscreenshot. Erfasse sowohl Desktop- als auch Telefonbreiten, wenn sich das Layout geändert hat. - Vorher: Wenn der Unterschied der Punkt ist, checke die Basis-Revision in einen temporären Worktree im Scratchpad aus (
git worktree add <scratchpad>/before <base>), betreibe sie auf einem anderen Port, mache einen Screenshot derselben Ansicht, entferne dann den Worktree (git worktree remove). Überspringe dies, wenn die Änderung rein additiv ist oder ein „Vorher“ nichts bringt. - Speichere Screenshots als Dateien im Scratchpad, verkleinere sie (
sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) und bette sie alsdata:-URIs ein. Halte die gesamte Seite unter ~8 MB. - Für Video-/Animationsänderungen bette einige Standbilder ein (
ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) oder einen Frame-Streifen sowie die gemessenen Zahlen. - Nicht-visuelle Änderungen (Skripte, Daten, Backend) erhalten stattdessen Diagramme und echte Ausgaben.
4. Die Geschichte planen, dann visuelle Elemente auswählen
Ordne die Seite so an, wie der Benutzer sie erklärt haben möchte: zuerst das Ergebnis, dann wie es funktioniert, dann die Details. Wähle visuelle Elemente basierend auf dem, was sich geändert hat. Bevorzuge ein Bild, wo immer es schneller erklärt als Text; halte Prosa kurz (Bildunterschriften und ein bis drei Sätze pro Absatz).
| Was sich geändert hat | Zu verwendendes visuelles Element |
|---|---|
| Logik, eine Pipeline, eine Entscheidungsregel | Mermaid flowchart des neuen Ablaufs; markiere die neuen/geänderten Knoten mit classDef changed |
| Anfragen zwischen Teilen (UI → API → Speicher) | Mermaid sequenceDiagram |
| Struktur (Module, Dateien, Datenform) | Dateizuordnung mit +/−-Balken; Mermaid graph zur Verbindung der Teile; Tabelle der Felder vorher/nachher |
| Benutzeroberfläche | Vorher/Nachher-Screenshot-Paar; annotiere mit nummerierten Markierungen über dem Bild |
| Zahlen (Zeiten, Größen, Zählungen, Leistung) | Ein inline-SVG-Balkendiagramm maßstabsgetreu, vorher vs. nachher |
| Zustand oder Lebenszyklus | Mermaid stateDiagram-v2 |
| Eine Arbeitssequenz (Migration, mehrstufige Änderung) | Nummerierte Walkthrough-Schritte (nur wenn die Reihenfolge real ist) |
| Schlüsselcode | Kurze Diff-Auszüge (5–25 Zeilen) mit markierten wichtigen Zeilen, innerhalb von <details>, damit sie nicht dominieren |
Strebe mindestens drei verschiedene visuelle Elemente für eine funktionsgroße Änderung an und mindestens eines für alles Kleinere. Diagramme müssen den realen Mechanismus beschreiben (echte Funktionsnamen, Dateinamen, Werte), keine generischen Kästen.
5. Die Seite aus der Vorlage erstellen
Kopiere <skill-dir>/template.html und fülle sie aus. Sie enthält bereits den Skizzenbuch-Look (einheitliches helles Design mit kariertem Hintergrund, handschriftlichen Überschriften, bleistiftskizzierten Karten, handgezeichneten Diagrammen), das Layout und jede oben aufgeführte Komponente. Füge keinen Dunkelmodus hinzu und ändere das Aussehen nicht, es sei denn, der Benutzer bittet darum. Regeln:
- Behalte den
<style>-Block und das Mermaid-Lader-Skript; ersetze die Beispielinhalte. Lösche Abschnitte, die nicht zutreffen, anstatt sie dünn zu lassen (z. B. kein „Vorher → Nachher“ für reines Refactoring). <title>: der Name der Funktion, zwei bis vier Wörter (z. B. „Checkout-Wiederholungslogik“), nicht „Arbeitszusammenfassung: …“.- Hero: ein Satz zum Ergebnis, die Meta-Zeile (Branch, PR-Link, Datum) und die Statistik-Leiste (Dateien, Zeilen +/−, Commits, bestandene Prüfungen). Berechne Zahlen aus gather.sh, schätze nicht.
- Benötigt deine Eingabe (Haftnotiz unter dem Hero): nur echte Anfragen, die auf den Benutzer warten, eine Zeile pro Stück, mit Hinweis, wo nachzusehen ist. Maximal drei. Lösche die gesamte Notiz, wenn es keine gibt; fülle sie niemals auf.
- Warum so (Entscheidungstabelle): zwei bis vier Optionen, die wirklich in der Sitzung abgewogen wurden, eine als „Gewählt“ markiert, jeweils ein Einzeiler zu den Kompromissen. Erfinde keine Alternativen zum Füllen; wenn keine echte Entscheidung getroffen wurde, lösche den Abschnitt.
- Halte die Seite schlank: diese beiden plus die zutreffenden Abschnitte. Füge keine Abschnitte über die Vorlage hinaus hinzu.
- Dateizuordnung: eine Zeile pro aussagekräftiger Datei (gruppiere generierte/binäre Dateien in eine Zeile), +/−-Balkenbreiten als Prozentsatz der Gesamtgröße der größten Datei, plus eine Zeile in einfachem Deutsch, warum sie geändert wurde.
- Diff-Auszüge: maskiere
<,>,&. Markiere Zeilen mitclass="add",class="del"oderclass="hl"(wichtige unveränderte Zeile). - Mermaid kommt in
<pre class="mermaid">, beginnend direkt nach dem Tag mit dem Konfigurationsblock aus der Vorlage (---/config:/look: handDrawn/theme: neutral/---), damit es sowohl als lokale Datei als auch auf claude.ai handgezeichnet rendert. Behalte die ZeileclassDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2pxaus der Vorlage bei. Maskiere</>in Labels als</>und verwendeclass <ids> changedfür das, was diese Arbeit hinzugefügt oder geändert hat. Halte jedes Diagramm auf etwa 5–9 Knoten, damit es auf einen Bildschirm passt: fasse aufeinanderfolgende Schritte in einem Knoten mit einer<br/>-Detailzeile zusammen und teile einen längeren Ablauf in zwei Diagramme auf. Verwendeflowchart LRfür kurze Ketten,TDfür verzweigte. - Verifikation: Liste jede Prüfung mit einem Bestanden / Fehlgeschlagen / Nicht geprüft-Chip und ihrem Nachweis (Ausgabeauszug oder Screenshot). „Nicht geprüfte“ Punkte sind erforderlich, wenn sie existieren.
- Schreibe klar: kurze Sätze, die Begriffe des Benutzers, keine Füllwörter.
Speichere sie als <repository-stamm>/.claude/work-briefs/<JJJJ-MM-TT>-<slug>.html. Halte diesen Ordner in jedem Repository aus Git heraus, ohne dessen .gitignore zu berühren, indem du ihn einmalig zur lokalen Ausschlussdatei hinzufügst:
mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")
6. Einmal prüfen, dann ausliefern
- Öffne die Seite einmal im Browser-Bereich (
preview_startmiturl: file://<pfad>oder dem statischen Server des Projekts) und mache einen Screenshot, um zu bestätigen, dass die Diagramme gerendert werden und nichts überläuft. Korrigiere, was dieser eine Blick zeigt; keine Schleife. - Zeige sie im Seitenbereich an:
SendUserFilemitdisplay: "render". - Veröffentliche sie als privates Artefakt (
Artifactveröffentlichen mit dem Dateipfad,icon: "document"und einer ein-Satz-Beschreibung), damit sie überlebt, nachdem ein Worktree bereinigt wurde. Dies ist die dauerhafte Kopie; Artefakte starten privat. Wenn kein Artefakt-Tool verfügbar ist (z. B. in einer reinen Terminal-Sitzung), überspringe dies und gib den lokalen Pfad an. - Füge im Chat nach deiner normalen Zusammenfassung eine Zeile mit dem Broschüren-Link und dem lokalen Dateipfad hinzu.
Aktualisierung: Wenn der Benutzer Änderungen wünscht, bearbeite dieselbe Datei und veröffentliche sie erneut unter demselben Pfad, damit der Link gleich bleibt.
Wie eine gute Broschüre aussieht
- Jemand, der nicht an der Sitzung teilgenommen hat, versteht in unter zwei Minuten Bildlauf, was sich geändert hat und warum.
- Der erste Bildschirm beantwortet „Was ist jetzt anders?“ ohne Scrollen.
- Jedes Diagramm, Diagramm und jeder Screenshot stammt von dieser Änderung.
- Der ehrliche Status ist sichtbar: was verifiziert wurde, was nicht, was noch aussteht.