Communitygithub.com

Arbeitsbroschüre

Führt den Benutzer visuell durch abgeschlossene Arbeiten mittels einer HTML-Broschüre mit Flussdiagrammen, Vorher/Nachher-Screenshots der echten App, Entscheidungen, Dateizuordnungen, Diff-Auszügen und Überprüfungsnachweisen – zusätzlich zur normalen Textzusammenfassung im Chat.

Was ist Arbeitsbroschüre?

Diese Fähigkeit erstellt eine eigenständige HTML-Broschüre, die eine abgeschlossene Arbeit visuell zusammenfasst, zusätzlich zur normalen Textzusammenfassung im Chat. Sie ist für jedes Repository geeignet und wird immer dann eingesetzt, wenn ein Pull Request eröffnet wurde, eine Funktion/Fehlerbehebung abgeschlossen ist oder der Benutzer explizit nach einer „Broschüre“ oder „visuellen Zusammenfassung“ fragt. Die Fähigkeit sammelt Fakten mittels eines Helfer-Skripts (`gather.sh`), erstellt Entscheidungstabellen, Dateizuordnungen, Diff-Auszüge und – bei sichtbaren Änderungen – Vorher/Nachher-Screenshots der tatsächlichen Anwendung. Die Broschüre wird aus einer Vorlage generiert, die einen handschriftlichen Skizzenbuch-Look verwendet, und enthält Mermaid-Diagramme, SVG-Balkendiagramme und eingebettete Screenshots als Data-URIs. Die Ausgabe wird im `.claude/work-briefs/`-Verzeichnis gespeichert, lokal von Git ausgeschlossen und optional als privates Artefakt veröffentlicht. Die Fähigkeit stellt sicher, dass jeder Anspruch, jede Zahl und jeder Dateipfad auf dem tatsächlichen Diff und den ausgeführten Befehlen basiert.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht Arbeitsbroschüre?

Nach Abschluss einer Arbeit möchte der Benutzer zweierlei:

  1. 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.
  2. 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_start mit dem launch.json-Server des Projekts, navigiere, computer {action: "screenshot"}) oder dem iOS-Simulator screenshot. 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 als data:-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 hatZu verwendendes visuelles Element
Logik, eine Pipeline, eine EntscheidungsregelMermaid 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ächeVorher/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 LebenszyklusMermaid stateDiagram-v2
Eine Arbeitssequenz (Migration, mehrstufige Änderung)Nummerierte Walkthrough-Schritte (nur wenn die Reihenfolge real ist)
SchlüsselcodeKurze 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 mit class="add", class="del" oder class="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 Zeile classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px aus der Vorlage bei. Maskiere </> in Labels als &lt;/&gt; und verwende class <ids> changed fü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. Verwende flowchart LR für kurze Ketten, TD fü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

  1. Öffne die Seite einmal im Browser-Bereich (preview_start mit url: 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.
  2. Zeige sie im Seitenbereich an: SendUserFile mit display: "render".
  3. Veröffentliche sie als privates Artefakt (Artifact verö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.
  4. 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.

Verwandte Skills