SkelegonDK/code-explainer-video

Code-Erklärvideo

Vertonte, animierte Walkthroughs von Code für Entwickler. Der Zuschauer ist ein Entwickler: Zeigen Sie echten Code, nennen Sie echte Dateien und Funktionen, erklären Sie warum und wie, vereinfachen Sie nie mit Analogien für Nicht-Entwickler.

Stack: Remotions Code-Hike-Vorlage (syntax-hervorgehobener Code, der zwischen Schritten morpht), Mermaid für Architekturdiagramme, ElevenLabs für Sprachausgabe (der ElevenLabs-Connector oder die API mit einem Schlüssel) und fest eingebrannte Untertitel. Laden Sie die Fähigkeit remotion-best-practices, wenn Sie den Remotion-Code in template/ ändern.

Dateien neben dieser SKILL.md („das Fähigkeitsverzeichnis“):

• template/: die Remotion-Quelldateien, die in jedes Videoprojekt kopiert werden.
• references/voice.md: wird in Schritt 8 gelesen, vor der Generierung der Sprachausgabe.
• references/long-form.md: zuerst lesen, wenn das Video 15-30 Minuten dauert; es unterteilt die Arbeit in Kapitel, die jeweils die Schritte 2-9 durchlaufen.

1. Aufnahme: drei Fragen (in dieser Reihenfolge) vor jeder Arbeit

Stellen Sie eine Frage nach der anderen (AskUserQuestion wenn verfügbar). Überspringen oder kombinieren Sie sie nicht.

1. Was muss verstanden werden? Ermitteln Sie das Ziel (eine Zeile, ein Block, eine Funktion, Datei, ein Ablauf oder die gesamte Architektur) und den Grund (Fehlerbehebung, Hinzufügen einer Funktion, Überprüfung eines PR, Einarbeitung). Wenn die Antwort vage ist („das Auth-Zeug“), lesen Sie zuerst den Code und bieten Sie dann 2-4 konkrete Blickwinkel zur Auswahl an, z. B. „wie eine Anfrage Ende-zu-Ende authentifiziert wird“ vs. „wie Sitzungen gespeichert und ablaufen“.
2. Wie lange sollte es dauern? Bieten Sie an: ~30 s (eine Zeile oder ein Block), 1-2 min (eine Funktion oder ein Modul), ~5 min (ein Subsystem oder Ablauf), 15-30 min (Einarbeitung in die Codebasis, als Kapitel von parallelen Agenten erstellt). Wenn der Benutzer es nicht weiß, empfehlen Sie eine Dauer basierend auf dem, was Sie in Schritt 1 gefunden haben.
3. Ist mein Verständnis richtig? Nachdem Sie den Code gelesen haben, senden Sie zurück:
   • die eine Frage, die das Video beantwortet, in einem Satz;
   • die Länge und die Anzahl der Beats;
   • die Gliederung: eine Zeile pro Beat (was auf dem Bildschirm zu sehen ist + die Aussage, die es trifft);
   • alles, was Sie absichtlich weglassen. Bauen Sie erst nach einem „Ja“. Bei einem „Nein“ überarbeiten und erneut bestätigen. Dieser Schritt existiert, weil Sprachausgabe ElevenLabs-Credits kostet und Rendering Minuten dauert.

Wenn unbeaufsichtigt ausgeführt (niemand zum Antworten), wählen Sie die vernünftigste Lesart, geben Sie sie am Anfang Ihrer Antwort an und fahren Sie fort.

2. Recherchieren Sie den Code, bevor Sie ein Wort schreiben

• Lesen Sie den tatsächlichen Code. Verfolgen Sie Aufrufe zu ihren Definitionen; leiten Sie Verhalten nicht aus Namen ab. Bei einer großen Codebasis verteilen Sie die Arbeit mit einem schreibgeschützten Subagenten pro Bereich, wenn Ihr Agent Subagenten unterstützt, und behalten Sie nur deren Schlussfolgerungen.
• Jede Behauptung in der Narration muss auf eine Datei und Zeile verweisen, die Sie gelesen haben. Führen Sie eine notes.md mit Behauptung → Pfad:Zeile, während Sie recherchieren; Sie verwenden sie, wenn Sie in Schritt 7 gefundene Probleme beheben.
• Notieren Sie, worüber ein Entwickler stolpern würde: versteckte Seiteneffekte, Reihenfolgenannahmen, Fehlerpfade, Konfiguration, die das Verhalten ändert, irreführende Benennungen.

3. Planen Sie Beats entsprechend dem Zeitbudget

Ein Beat ist eine visuelle Einheit plus 1-3 Sätze Narration. Die Narration läuft mit etwa 150 Wörtern pro Minute (2,5 Wörter/s); jeder Beat erhält eine Nachlaufpause von 0,6 s.

Budget	Beats	Wörter
30 s	3-4	~70
1-2 min	6-12	150-280
5 min	20-30	~700
15-30 min	Kapitel von 3-5 min, siehe references/long-form.md

Beat-Regeln:

• Beginnen Sie mit der zu beantwortenden Frage und schließen Sie mit einer einzeiligen Zusammenfassung. Kein Einleitungs-Brimborium, kein „in diesem Video“.
• Zuerst Architektur, dann heranzoomen: Diagramm, dann der Einstiegspunkt-Code, dann die interessante Zeile.
• Erklären Sie Zweck, nicht Zeilen. Jeder Code-Beat sagt, wozu der Code dient und wie er mit dem vorherigen Beat zusammenhängt, und zeigt dann auf die ein oder zwei Zeilen, die wichtig sind. Gehen Sie nie einen Block Zeile für Zeile durch.
• Code-Beats: höchstens 16 Zeilen (der untere Bildschirmrand ist für Untertitel reserviert) und 80 Zeichen pro Zeile. Schneiden Sie irrelevante Zeilen heraus und ersetzen Sie sie durch einen // ...-Kommentar. Aufeinanderfolgende Beats, die dasselbe Snippet mit einer anderen Hervorhebung zeigen, animieren flüssig, also verwenden Sie Snippets wieder und verschieben Sie die Hervorhebung.
• Heben Sie hervor, worüber die Narration spricht, mit einem Code-Hike-Kommentar direkt darüber: // !mark (nächste Zeile) oder // !mark(1:4) (nächste vier Zeilen). Verwenden Sie die Kommentarsyntax der Sprache (# !mark in Python).
• Diagramm-Beats: Mermaid flowchart mit höchstens 8 Knoten. Verwenden Sie TD für Ketten länger als vier Knoten. Halten Sie Knoten über aufeinanderfolgende Diagramm-Beats hinweg identisch und verschieben Sie nur die Zeile class X hot, damit das Layout nicht springt.
• Die Narration ist für das Hören geschrieben: kurze Sätze, sagen Sie Bezeichner so, wie Entwickler sie sagen („die handle-request-Funktion“), lesen Sie keinen Code Symbol für Symbol vor, sprechen Sie keine Zeilennummern aus.

4. Projekteinrichtung (einmal pro Video)

Setzen Sie SKILL_DIR auf das Fähigkeitsverzeichnis, dann:

npx create-video@latest --yes --code-hike explainer && cd explainer
npx remotion add @remotion/media && npm rm twoslash-cdn && rm public/code*
rm src/calculate-metadata/process-snippet.ts src/annotations/Callout.tsx src/annotations/Error.tsx src/ProgressBar.tsx src/ReloadOnCodeChange.tsx
cp -R "$SKILL_DIR/template/." .
command -v mmdc || npm i -g @mermaid-js/mermaid-cli

Twoslash wird bewusst entfernt: es markiert jeden ungelösten Import in einem Code-Auszug als roten Fehler. Die kopierten Dateien ersetzen die Komposition der Vorlage durch eine, die von beats/ gesteuert wird:

• scripts/build.mjs wandelt beats/ in public/beats/ um (Audio, gerenderte Diagramme, manifest.json) und misst die Audiolänge jedes Beats.
• src/Main.tsx spielt die Beats nacheinander ab: Titel, Code oder Diagramm, Audio, Untertitel.
• src/annotations/Mark.tsx implementiert die !mark-Hervorhebung. src/Captions.tsx timet Untertitel-Blöcke über das Audio jedes Beats.

5. Schreiben Sie die Beats

Ein Paar Dateien pro Beat in beats/, nummeriert, damit sie sortiert werden (01, 02, … 10):

• NN.txt: optionale erste Zeile # <Bildschirmtitel> (verwenden Sie pfad/zu/datei.ts:42-60 für Code-Beats, eine kurze Überschrift für Diagramme), dann die Narration.
• Eine visuelle Darstellung: NN.<Erweiterung> mit dem Code-Auszug (die Erweiterung bestimmt die Hervorhebungssprache: .ts, .py, .go, …) oder NN.mmd mit einem Mermaid-Diagramm. Heben Sie einen Diagrammknoten hervor mit classDef hot fill:#facc15,color:#000,stroke:#facc15 und class KnotenId hot.

Beispiel:

beats/04.txt
# src/auth/session.ts:31-44
Sitzungen werden träge erneuert. Die Ablaufprüfung wird nur durchgeführt, wenn eine Anfrage eintrifft, daher wird eine untätige Sitzung hier nie bereinigt.

beats/04.ts
export async function getSession(id: string) {
  const s = await store.get(id);
  // !mar(1:3)
  if (s && s.expiresAt < Date.now()) {
    return renew(s);
  }
  return s;
}

6. Entwurfsdurchlauf (keine Credits)

1. node scripts/build.mjs ohne beats/*.mp3 und ohne Schlüssel erzeugt Platzhalter-Audio mit der geschätzten Länge und gibt die Gesamtlänge aus. Wenn es mehr als 15 % über oder unter dem Budget liegt, kürzen oder ergänzen Sie jetzt Beats.
2. Rendern Sie Standbilder der Momente mit den meisten Inhalten auf dem Bildschirm und des Moments, in dem jede Hervorhebung landet (etwa 1,5 s nach einem Beat): npx remotion still Main out/check.png --frame=<n> --scale=0.5. Betrachten Sie sie. Beheben Sie überlaufende Zeilen, unlesbare Diagramme und Hervorhebungen in der falschen Zeile.

7. Unabhängige Faktenprüfung (vor der Generierung von Narration)

Der Autor eines Skripts ist die schlechteste Person, es zu überprüfen. Lassen Sie einen Prüfer, der es nicht geschrieben hat, jede Behauptung gegen den Code prüfen. Führen Sie dies auch durch, wenn Sie unbeaufsichtigt arbeiten.

• Wenn Ihr Agent Subagenten unterstützt, starten Sie einen neuen. Geben Sie ihm den Repository-Pfad, jedes beats/NN.txt und dessen visuelle Darstellung sowie diese Kurzbeschreibung, aber nicht notes.md oder Ihre Gliederung, damit er seine eigene Lesart des Codes bildet:

  Prüfen Sie dieses Erklärskript gegen den Code. Listen Sie jede faktische Behauptung in der Narration und in den Bildschirmtiteln auf. Finden Sie für jede den Code, der sie bestätigt oder widerlegt, und verfolgen Sie Aufrufe zu ihren Definitionen. Geben Sie eine Zeile pro Behauptung zurück: Beat | Behauptung | richtig / falsch / nicht überprüfbar | Pfad:Zeile | warum. Melden Sie auch Code-Auszüge, die von der Quelle abweichen (außer // ...-Kürzungen und !mark-Kommentare), Titel, deren Pfad:Zeile-Bereich falsch ist, alles Wichtige an diesem Code, das das Skript irreführend darstellt, und Code-Beats, deren Narration zeilenweise durchgeht, ohne zu sagen, wozu der Code dient.

• Andernfalls führen Sie selbst einen zweiten Durchlauf durch: Öffnen Sie für jede Behauptung den zitierten Code erneut und überprüfen Sie ihn dort, nicht anhand von notes.md.

Beheben Sie jede falsche Behauptung, entfernen oder entschärfen Sie jede nicht überprüfbare und schreiben Sie gekennzeichnete zeilenweise Beats um, um ihren Zweck zu verdeutlichen. Führen Sie den Entwurfsbuild erneut aus und senden Sie nur die geänderten Beats zur erneuten Überprüfung zurück.

8. Stimme und Rendern

1. Lesen Sie references/voice.md und generieren Sie eine Narration pro Beat mit der ersten verfügbaren Option: dem ElevenLabs-Connector, einem ElevenLabs-API-Schlüssel, einem anderen Text-to-Speech-Anbieter oder keinem (stummes Video mit Untertiteln). Verwenden Sie eine Stimme für das gesamte Video.
2. Führen Sie erneut node scripts/build.mjs aus. Es verwendet beats/NN.mp3, wenn vorhanden, sodass das Ändern eines Beats das Ersetzen nur dieser Datei bedeutet.
3. Rendern Sie einmal: npx remotion render Main out/explainer.mp4. Überprüfen Sie, ob Video- und Audiolängen übereinstimmen (ffprobe -v error -show_entries stream=codec_type,duration -of csv=p=0 out/explainer.mp4) und, sofern das Video nicht stumm sein soll, ob das Audio vorhanden ist (ffmpeg -i out/explainer.mp4 -af volumedetect -vn -f null - 2>&1 | grep mean_volume; Platzhalter-Audio liest etwa -91 dB).

9. Vor der Übergabe

• Sehen Sie sich den ersten und den letzten Beat sowie einen in der Mitte an, oder hören Sie sie zumindest an. Wenn ein Bezeichner falsch ausgesprochen wird, buchstabieren Sie ihn phonetisch in NN.txt um und vertonen Sie nur diesen Beat neu. Untertitel zeigen den Erzähltext, daher erscheint eine phonetische Umschreibung auch dort; halten Sie Umschreibungen lesbar.
• Jede Narration, die sich nach Schritt 7 geändert hat, durchläuft diesen Schritt erneut.
• Liefern Sie die mp4 mit einer einzeiligen Zusammenfassung der Frage, die sie beantwortet. Laden Sie sie niemals ohne ausdrückliche Erlaubnis hoch oder veröffentlichen Sie sie irgendwo.