Repo-Walkthrough-Video

Was macht Repo-Walkthrough-Video?

Das Ziel ist ein Video, das ein Teammitglied ansehen kann, um ein Repository zu verstehen: wofür es ist, wie seine Teile zusammenpassen, und jede Funktion, die wirklich ausgeführt wird, einschließlich dessen, was heute kaputt ist. Zwei Aufgaben sind hier vermischt, und sie sollten in dieser Reihenfolge ausgeführt werden:

1. Das Repo wirklich testen. Jeder im Video gezeigte Befehl wurde tatsächlich ausgeführt und seine Ausgabe gelesen.
2. Als Geschichte aufnehmen. Die Kapitel folgen der Struktur des Systems, und jedes wird erzählt.

Ein Video, das nur erfolgreiche Befehle zeigt, täuscht das Team. Die Fehler, die du beim Testen findest, sind oft der wertvollste Teil des Videos, also gib ihnen ein eigenes Schlusskapitel.

Ausgabelayout

Arbeite in einem Ordner außerhalb des Repos. Der Benutzer wählt ihn; wenn nicht, verwende ein Geschwisterverzeichnis wie <eltern-von-repo>/video/, da ein Stammpfad wie /video unter macOS oft schreibgeschützt ist.

video/
├── <name>-walkthrough.mp4    # Vollvideo: Kapitel + mov_text-Untertitelspur
├── <name>-walkthrough.srt    # Gleiche Erzählung, auch als Transkript verwendbar
├── chapters/NN-slug.mp4      # Eine Datei pro Kapitel
├── README.md                 # Kapitelverzeichnis mit Startzeiten, wie man neu aufzeichnet
├── src/                      # engine.py, make_readme.py, script.py (+ Helfer)
├── work/                     # Wegwerf-Klon(s) des Repos: Hier läuft jeder Befehl
└── build/                    # Zwischendateien (pro-Segment Stimme, Frames, Clips)

Führe die Demo-Befehle nie auf der Arbeitskopie des Benutzers aus. Klone es in work/ (git clone <repo> work/<name>), damit das Video absichtlich Dinge kaputt machen kann (fehlerhafte Manifeste, eingeschleuste Fehler) und mit git checkout . && git clean -fd zurücksetzen kann. Wenn der Checkout des Benutzers nicht festgeschriebene Änderungen enthält, erwähne sie und lasse sie in Ruhe.

Schritt 1: Überprüfe die Werkzeuge und teile dem Benutzer mit, was fehlt

which vhs ffmpeg ffprobe jq; python3 -c "import PIL; print(PIL.__version__)"; say -v '?' | head -3

Wenn etwas fehlt, sage dem Benutzer, was zu installieren ist und warum, bevor du es installierst (brew install vhs ffmpeg jq). Für Pillow fass das System-Python nicht an. Starte die Engine stattdessen durch uv: uv run --no-project --with pillow python engine.py .... Verpacke es in eine Shell-Funktion (py() { uv run --no-project --with pillow python "$@"; }), da eine Variable, die den Befehl enthält, nicht als ein Wort expandiert wird. Das Gleiche gilt für alles, was das Repo braucht, wie Docker, ein Simulator-Stack oder Anmeldedaten. Frage den Benutzer danach und erfinde niemals ein Geheimnis. Eine Premium-Stimme (Systemeinstellungen → Bedienungshilfen → Gesprochene Inhalte, z. B. „Anna (Premium)") klingt viel besser als die Standardstimme Samantha. Biete sie an, aber blockiere nicht darauf; VOICE=... engine.py --force vertont später neu.

Schritt 2: Verstehe und teste das Repo, bevor du ein Wort der Erzählung schreibst

Lies die README, die Dokumentation oder ADRs, die CLI-Einstiegspunkte (--help jedes Unterbefehls), die Test-Marker, die Makefile und die CI-Konfiguration. Erstelle ein Inventar jeder Funktion, die ein Benutzer ausführen kann: jeder CLI-Unterbefehl, jede Testsammlung, jede Integration, jeder Fehlermodus, gegen den der Code schützt.

Dann führe alles in work/ aus und schreibe auf:

• die genauen Befehle, die jede Funktion gut zeigen, mit kurzer Ausgabe (pfeife durch jq, head, tail, cut -c1-160)
• was fehlschlägt und ob es ein echter Fehler oder nur deine Umgebung ist (falscher Standardpfad, fehlende Umgebungsvariable). Behebe Umgebungsprobleme im Klon oder mit Umgebungsvariablen und mache diese Behebung im Video sichtbar, da das Team auch darauf stoßen wird.
• wie man jede Sicherheitsregel absichtlich bricht (eine Fixture, ein sed auf einer Kopie), damit das Video das Auslösen der Regel zeigen kann

Diese Notizen werden das Kapitel mit den Ergebnissen. Halte sie als Liste nummerierter, konkreter Punkte.

Schritt 3: Plane die Kapitel

Folge der eigenen Pipeline des Systems, nicht der Ordnerliste. Eine Form, die gut funktioniert hat:

#	Kapitel	Inhalt
00	Willkommen	Titelbild, dann eine Folie „Was du sehen wirst"
01	Gesamtbild	Ein-Satz-Zweck, die Pipeline als Boxen und Pfeile, eine Terminal-Szene mit Repo-Layout
02	Einrichtung	Installation, die CLI gruppiert nach Zweck, die schnelle Testsuite
…	ein Kapitel pro Pipeline-Stufe	Echte Befehle, plus eine Szene „Absichtlich kaputt machen" pro Regel
…	Live / Integration	Die echten Backend-Dienste, Ende zu Ende
N-1	Schnittstellen / Übergabe	Worauf andere Teams angewiesen sind
N	Ergebnisse und nächste Schritte	Die nummerierte Liste der Ergebnisse, dann was als nächstes zu tun ist

Ziele auf 1–3 Minuten pro Kapitel und 15–25 Minuten insgesamt. Ein Kapitel ist eine Idee; ein Segment ist ein Bildschirm plus eine Erzählung. Zeige dem Benutzer diese Gliederung (Kapiteltitel und eine Zeile pro Kapitel) vor der Aufnahme.

Schritt 4: Schreibe src/script.py

Kopiere die gebündelten Skripte in den Videoordner:

mkdir -p video/src && cp <skill-dir>/scripts/{engine.py,make_readme.py,agent.jq} video/src/
cp <skill-dir>/scripts/script_template.py video/src/script.py

script.py enthält alle Wörter und alle Befehle. engine.py macht daraus Video. Lese references/script-format.md für das vollständige Segment-Schema, die Folien-Layouts und den Erzählstil. scripts/script_template.py zeigt jeden Segment-Typ mit einem funktionierenden Beispiel; baue den Rest der Kapitel in der gleichen Form (Schritt 3 gibt die Kapitelgliederung).

Die wichtigsten Erzählregeln:

• Schreibe für das Ohr: kurze Sätze, kein Markdown und schreibe Akronyme aus, die die Stimme falsch ausspricht ("M C P", "C L I"), oder füge sie zu SPOKEN in script.py hinzu.
• Sage, worauf der Zuschauer schauen soll („Schau auf die Skills: null"). Die Stimme und das Bild müssen übereinstimmen. Wenn du also die Ausgabe eines Befehls änderst (eine Zahl, einen Geschwindigkeitsfaktor), korrigiere auch den Satz.
• Untertitel (die untere Leiste einer Terminal-Szene) sind eine Zeile, die den Punkt angibt, mit code in Backticks.

Schritt 5: Trockentest, dann aufnehmen

cd video/src                          # `py` = Python mit Pillow (siehe Schritt 1)
py engine.py --dry                    # Führt jeden Terminalbefehl in plain bash aus und gibt die Ausgabe aus, kein Video
py engine.py --dry --only 04          # Ein Kapitel
py engine.py --only 04                # Ein Kapitel aufnehmen (schnelles Feedback zum Aussehen)
py engine.py                          # Alles fehlende oder geänderte, dann das vollständige Video zusammenbauen
py engine.py --only 07 --reuse-terms  # VHS-Clips behalten, nur Stimme und Frames neu machen (Erzählungskorrekturen)
py make_readme.py                     # Schreibt README.md mit dem Kapitelverzeichnis

Mach immer zuerst einen Trockentest. Es dauert Minuten statt einer Stunde und fängt jeden Befehl, der einen Fehler produziert, hängt oder zu viel ausgibt. Nimm zuerst ein Kapitel auf und schau dir die Frames vor dem vollständigen Build an:

ffmpeg -v error -ss 20 -i chapters/04-*.mp4 -frames:v 1 build/check.png   # Dann lies das PNG

Ein vollständiger Build dauert lange (etwa 40 Minuten für 21 Minuten Video). Führe ihn im Hintergrund aus und warte auf seine Fertigstellungsmeldung, anstatt zu pollen. Kapitel werden durch einen Hash ihres Skripts zwischengespeichert, sodass beim erneuten Ausführen nur das neu gebaut wird, was sich geändert hat.

Schritt 6: Verifizieren und übergeben

ffprobe -v error -show_chapters -show_streams -of compact video/<name>-walkthrough.mp4 | head -40

Überprüfe Folgendes:

• die Dauer
• 1920×1080 h264, aac und einen mov_text-Untertitelstream
• eine Kapitelmarkierung pro Kapitel
• Beispiel-Frames aus einigen Kapiteln: kein überlaufender Text in Boxen, Untertitel innerhalb von zwei Zeilen

Dann teile dem Benutzer die genauen Pfade der MP4, des chapters/-Ordners, der SRT und der README mit. Füge hinzu, wie man sie öffnet (open video/<name>-walkthrough.mp4; QuickTime oder VLC zeigen die Kapitel- und Untertitelmenüs) und die Liste der Ergebnisse. Erwähne alle Container oder Dienste, die du laufen gelassen hast, und wie man sie stoppt.

Bereits gelöste Fallstricke (behalte diese beim Bearbeiten der Engine im Hinterkopf)

• Gesperrte Shells: vhs, Docker, uv-Caches und say schlagen oft unter einer Befehlssandbox fehl („Operation not permitted", Docker-Socket-Fehler). Diese Befehle müssen außerhalb davon ausgeführt werden. open ist ebenfalls blockiert, also gib dem Benutzer den Befehl, den er selbst ausführen muss.
• VHS-Frame-Drops: die Standardeinstellung 50 fps verwirft Frames bei langen Szenen. Die Engine verwendet Set Framerate 15.
• VHS Output muss ein bloßer Dateiname sein. Führe vhs mit cwd auf den Ausgabeordner aus.
• VHS-Strings haben keine Escape-Sequenzen. json.dumps-Zitierung zerstört PS1-Escape-Sequenzen. Verwende q() in der Engine, die ein ", ' oder `-Trennzeichen wählt, das der Text nicht enthält.
• Wait hängt, wenn das Muster nicht mit der Eingabeaufforderung übereinstimmt. Die Engine setzt eine PS1, die auf $ endet, und verwendet WaitPattern /[>$]$/. Befehle, die eine letzte Zeile ausgeben, die auf $ oder > endet, können eine Wartezeit vorzeitig beenden, also füge dort eine pause ein.
• Langlaufende Szenen (ein KI-Agent, ein Pipeline-Lauf): setze "speedup": True auf das Segment. Die Engine beschleunigt den Clip auf ungefähr die Länge der Erzählung und stempelt sped up ×N.N in den Header ein. Sage also, dass es beschleunigt ist.
• Textüberlauf auf Folien: wrap() misst Code-Spans in der Monospace-Schriftart. Halte Box-Körper kurz und teile lange Pfade auf zwei Zeilen.
• Warteschleifen: eine pgrep -f <muster>-Schleife matcht sich selbst. Warte stattdessen auf eine PID oder eine Datei.
• Before-Hooks ("before": [...] in einem Kapitel) bereiten den Zustand vor: Setze einen DB-Container zurück, starte eine Pipeline, injiziere einen Fehler. Setze das Rückgängig (Zurücksetzen, Entfernen der Injektion) in dasselbe Kapitel, damit ein Neuaufbau eines Kapitels niemals die Plattform kaputt hinterlässt.
• Geheimnisse, die die Demo benötigt, landen in einer git-ignorierten Datei im Klon (z. B. dev-vault.env). Zeige ihre Werte niemals auf dem Bildschirm und committe sie niemals.

Einen KI-Agenten bei der Arbeit zeigen (optional)

Wenn das Repo einen Agenten baut oder konfiguriert, ist die stärkste Szene der Agent, der einen echten, injizierten Fehler diagnostiziert. Führe ihn kopflos mit Stream-JSON-Ausgabe aus und formatiere den Stream mit dem gebündelten agent.jq (eine Zeile pro Tool-Aufruf, dann die Antwort):

claude -p "<frage>" --output-format stream-json --verbose | jq -rj -f /pfad/zu/video/src/agent.jq

Markiere dieses Segment mit "speedup": True und setze den Fehler danach im selben Kapitel zurück.