zarazhangrui/codebase-to-course

Was macht codebase-to-course?

Verwandle jede Codebasis in einen atemberaubenden, interaktiven Kurs. Das Ergebnis ist ein Verzeichnis mit einer vorgefertigten styles.css, main.js, HTML-Dateien pro Modul und einer zusammengebauten index.html – öffne sie direkt im Browser, ohne Einrichtung (einzige externe Abhängigkeit: Google Fonts CDN). Der Kurs vermittelt, wie der Code funktioniert, durch scrollbasierte Module, animierte Visualisierungen, eingebettete Quizfragen und verständliche Code-Übersetzungen.

Willkommensnachricht beim ersten Start

Wenn der Skill zum ersten Mal ausgelöst wird und der Benutzer noch keine Codebasis angegeben hat, stelle dich vor und erkläre, was du tust:

Ich kann jede Codebasis in einen interaktiven Kurs verwandeln, der erklärt, wie sie funktioniert – ohne Programmierkenntnisse.

Gib mir einfach ein Projekt:

• Einen lokalen Ordner – z. B. „mache ./mein-projekt zu einem Kurs"
• Einen GitHub-Link – z. B. „erstelle einen Kurs aus https://github.com/user/repo"
• Das aktuelle Projekt – wenn du bereits in einer Codebasis bist, sage einfach „mache dies zu einem Kurs"

Ich lese den Code durch, finde heraus, wie alles zusammenhängt, und erstelle einen schönen Ein-Seiten-HTML-Kurs mit animierten Diagrammen, verständlichen Code-Erklärungen und interaktiven Quizfragen. Das Ganze läuft in deinem Browser – keine Einrichtung nötig.

Wenn der Benutzer einen GitHub-Link angibt, klone das Repository zuerst (git clone <url> /tmp/<repo-name>), bevor du mit der Analyse beginnst. Wenn sie „diese Codebasis" oder Ähnliches sagen, verwende das aktuelle Arbeitsverzeichnis.

Für wen ist das gedacht

Die Zielgruppe ist ein "Vibe-Coder" – jemand, der Software erstellt, indem er KI-Programmierwerkzeuge in natürlicher Sprache anleitet, ohne traditionelle Informatikausbildung. Sie haben dieses Projekt vielleicht selbst erstellt (ohne den Code anzusehen) oder ein interessantes Open-Source-Projekt auf GitHub gefunden und möchten verstehen, wie es aufgebaut ist. In beiden Fällen verstehen sie noch nicht, was unter der Haube passiert.

Gehe von null technischem Hintergrundwissen aus. Jedes Informatikkonzept – von Variablen über APIs bis hin zu Datenbanken – muss in einfacher Sprache erklärt werden, als ob der Lernende es noch nie gesehen hätte. Kein Fachjargon ohne Definition. Kein „wie du wahrscheinlich weißt". Der Ton sollte wie ein kluger Freund sein, der etwas erklärt, nicht wie ein Professor, der doziert.

Ihre Ziele sind praktisch, nicht akademisch:

• Genug technisches Wissen haben, um KI-Programmierwerkzeuge effektiv zu steuern – bessere Architektur- und Tech-Stack-Entscheidungen treffen
• Erkennen, wenn KI falsch liegt – Halluzinationen aufspüren, schlechte Muster erkennen, wissen, wenn etwas komisch riecht
• Eingreifen, wenn KI stecken bleibt – aus Fehlerschleifen ausbrechen, Probleme debuggen, sich selbst entblocken
• Fortschrittlichere Software mit Produktionsqualität und Zuverlässigkeit erstellen
• Technisch versiert genug sein, um Entscheidungen selbstbewusst mit Ingenieuren zu besprechen
• Das Vokabular der Software erlernen – die präzisen technischen Begriffe lernen, um Anforderungen klar und eindeutig an KI-Programmieragenten zu beschreiben (z. B. wissen, dass man „Namespace-Paket" statt „geteilter Ordner-Ding" sagen muss)

Sie versuchen NICHT, Softwareentwickler zu werden. Sie möchten Programmieren als Superkraft, die das verstärkt, worin sie bereits gut sind. Sie müssen keinen Code von Grund auf neu schreiben – sie müssen ihn lesen, verstehen und lenken.

Warum dieser Ansatz funktioniert

Dieser Skill kehrt die traditionelle Informatikausbildung um. Das alte Modell ist: Konzepte jahrelang auswendig lernen → irgendwann etwas bauen → endlich den Sinn sehen (die meisten geben vor Schritt 3 auf). Dieses Modell ist: baue zuerst etwas → erlebe, wie es funktioniert → verstehe nun, wie es funktioniert.

Der Lernende hat bereits Kontext, den traditionelle Studenten nicht haben – sie haben die App benutzt, sie wissen, was sie tut, sie haben vielleicht sogar ihre Funktionen in natürlicher Sprache beschrieben. Der Kurs trifft sie dort, wo sie sind: „Du kennst diesen Button, auf den du klickst? Hier ist, was unter der Haube passiert, wenn du ihn klickst."

Jedes Modul beantwortet „Warum sollte mich das interessieren?" bevor es „Wie funktioniert das?" erklärt. Die Antwort auf „Warum sollte mich das interessieren?" ist immer praktisch: weil dieses Wissen dir hilft, KI besser zu steuern, schneller zu debuggen oder intelligentere Architekturentscheidungen zu treffen.

Das verzeichnisbasierte Ausgabeformat ist absichtlich gewählt: Die Trennung von CSS/JS vom Inhalt bedeutet, dass KI niemals Boilerplate neu generiert, jedes Modul unabhängig geschrieben wird (kleine Ausgabegröße und hohe Qualität) und die zusammengebaute index.html offline ohne Einrichtung funktioniert.

---

Der Prozess

Phase 1: Codebasis-Analyse

Bevor du den Kurs-HTML-Code schreibst, verstehe die Codebasis gründlich. Lies alle wichtigen Dateien, verfolge die Datenflüsse, identifiziere die "Hauptakteure" (Hauptkomponenten/Module) und kartiere, wie sie kommunizieren. Gründlichkeit zahlt sich hier aus – je mehr du verstehst, desto besser der Kurs.

Was extrahiert werden soll:

• Die Haupt-„Akteure" (Komponenten, Dienste, Module) und ihre Verantwortlichkeiten
• Die primäre Benutzerreise (was passiert, wenn jemand die App von Anfang bis Ende nutzt)
• Wichtige APIs, Datenflüsse und Kommunikationsmuster
• Kluge technische Muster (Caching, Lazy Loading, Fehlerbehandlung usw.)
• Echte Fehler oder Fallstricke (wenn im Git-Verlauf oder in Kommentaren sichtbar)
• Der Tech-Stack und warum jede Komponente gewählt wurde

Finde selbst heraus, was die App tut, indem du die README, die Haupteinstiegspunkte und den UI-Code liest. Frage den Benutzer nicht, das Produkt zu erklären – er könnte es ebenfalls nicht kennen. Der Kurs sollte damit beginnen, zu erklären, was die App in einfacher Sprache tut (eine kurze „Hier ist, was dieses Ding tut und warum es interessant ist"), bevor er eintaucht, wie es funktioniert. Das erste Modul sollte mit einer konkreten Benutzeraktion beginnen – „Stell dir vor, du fügst eine YouTube-URL ein und klickst auf Analysieren – hier ist, was unter der Haube passiert."

Phase 2: Curriculumsdesign

Strukturiere den Kurs als 4-6 Module. Die meisten Kurse benötigen 4-6. Gehe nur auf 7-8, wenn die Codebasis wirklich so viele unterschiedliche Konzepte hat, die es wert sind, gelehrt zu werden. Weniger, bessere Module sind besser als mehr, dünnere.

Der Bogen beginnt immer mit dem, was der Lernende bereits kennt (das benutzerseitige Verhalten) und bewegt sich zu dem, was er nicht kennt (der Code darunter). Stell es dir wie Hineinzoomen vor: beginne breit mit der Erfahrung, dann schäle nach und nach Schichten ab.

Modulposition	Zweck	Warum es für einen Vibe-Coder wichtig ist
1	„Hier ist, was diese App tut – und was passiert, wenn du sie benutzt"	Beginne mit dem Produkt (was es tut, warum es interessant ist), dann verfolge eine Kernbenutzeraktion bis in den Code. Verankere alles in etwas Konkretem.
2	Lerne die Akteure kennen	Wisse, welche Komponenten es gibt, um KI sagen zu können „setze diese Logik in X, nicht Y"
3	Wie die Teile miteinander reden	Verstehe den Datenfluss, um „es wird nicht angezeigt"-Probleme debuggen zu können
4	Die Außenwelt (APIs, Datenbanken)	Wisse, was extern ist, um Kosten, Ratenlimits und Fehlermodi bewerten zu können
5	Die cleveren Tricks	Lerne Muster (Caching, Chunking, Fehlerbehandlung), um sie von KI anfordern zu können
6	Wenn etwas kaputt geht	Baue Debugging-Intuition auf, um KI-Fehlerschleifen zu entkommen
7	Das große Ganze	Siehe die vollständige Architektur, um bessere Entscheidungen darüber zu treffen, was als Nächstes gebaut wird

Dies ist ein Menü, keine Checkliste. Wähle die Module, die der Codebasis dienen – ein einfaches CLI-Tool benötigt 4, nicht 7. Passe den Bogen an die Komplexität der Codebasis an.

Das Schlüsselprinzip: Jedes Modul sollte mit einer praktischen Fähigkeit verbunden sein – KI steuern, Debuggen, Entscheidungen treffen. Wenn ein Modul dem Lernenden nicht hilft, etwas BESSER zu tun, streiche es oder formuliere es um, bis es das tut.

Jedes Modul sollte enthalten:

• 3-6 Bildschirme (Unterabschnitte, die innerhalb des Moduls fließen)
• Mindestens eine Code-mit-Deutsch-Übersetzung
• Mindestens ein interaktives Element (Quiz, Visualisierung oder Animation)
• Ein oder zwei „Aha!"-Callout-Boxen mit universellen CS-Einblicken
• Eine Metapher, die das technische Konzept im Alltag verankert – aber verwende NIEMALS dieselbe Metapher über Module hinweg und greife NIEMALS auf die „Restaurant"-Metapher zurück (sie ist überstrapaziert). Wähle Metaphern, die organisch zum spezifischen Konzept passen. Die besten Metaphern fühlen sich unvermeidlich für das Konzept an, nicht gezwungen.

Verpflichtende interaktive Elemente (jeder Kurs muss ALLE enthalten):

• Gruppenchat-Animation – mindestens eine im gesamten Kurs. Dies sind iMessage/WhatsApp-ähnliche Unterhaltungen zwischen Komponenten. Sie sind eines der ansprechendsten Elemente und müssen immer erscheinen, selbst wenn du ein Modulkonzept kreativ als Gespräch zwischen Akteuren rahmen musst.
• Nachrichtenfluss / Datenfluss-Animation – mindestens eine im gesamten Kurs. Die schrittweise Paketanimation zwischen Akteuren. Wenn die Codebasis irgendeine Art von Anfrage/Antwort, Datenpipeline oder mehrstufigem Prozess hat, animiere sie. Jede Codebasis hat irgendwo einen Datenfluss – finde ihn.
• Code ↔ Deutsch-Übersetzungsblöcke – mindestens eine pro Modul (bereits oben erforderlich, aber zur Wiederholung: dies ist nicht verhandelbar).
• Quizfragen – mindestens eine pro Modul (Multiple-Choice, Szenario, Drag-and-Drop oder Fehler finden – jeder Quiztyp zählt).
• Glossar-Tooltips – bei jedem technischen Begriff, bei der ersten Verwendung pro Modul.

Diese fünf Elementtypen sind das Rückgrat jedes Kurses. Andere interaktive Elemente (Architekturdiagramme, Ebenen-Umschalter, Musterkarten usw.) sind optional und sollten hinzugefügt werden, wenn sie passen. Aber die fünf oben genannten müssen IMMER vorhanden sein – keine Ausnahmen.

Präsentiere das Curriculum NICHT zur Genehmigung – baue es einfach. Der Benutzer möchte einen Kurs, kein Planungsdokument. Entwerfe das Curriculum intern und gehe dann direkt zum Bauen über. Wenn sie Änderungen wünschen, werden sie es dir sagen, nachdem sie das Ergebnis gesehen haben.

Nach dem Entwurf des Curriculums entscheide, welchen Build-Pfad du verwendest:

• Einfache Codebasis (einzelner CLI, kleine Web-App, Bibliothek, ein klarer Einstiegspunkt, 5 oder weniger Module) → gehe direkt zu Phase 3 Sequentiell.
• Komplexe Codebasis (Full-Stack-App, mehrere Dienste, inhaltsreiche Website, Monorepo oder 6+ Module) → gehe zuerst zu Phase 2.5, dann zu Phase 3 Parallel.

Phase 2.5: Modul-Briefings (nur für komplexe Codebasen)

Für komplexe Codebasen schreibe ein Briefing für jedes Modul, bevor du HTML schreibst. Dies ist der kritische Schritt, der paralleles Schreiben ermöglicht – jedes Briefing gibt einem Agenten alles, was er braucht, ohne die Codebasis erneut lesen zu müssen.

Lies references/module-brief-template.md für die Vorlagenstruktur. Lies references/content-philosophy.md für die Inhaltsregeln, die das Schreiben von Briefings leiten sollen.

Schreibe für jedes Modul ein Briefing nach course-name/briefs/0N-slug.md, das Folgendes enthält:

• Lehrbogen (Metapher, Einführungshaken, Schlüsseleinblick)
• Vorab extrahierte Code-Snippets (aus der Codebasis kopiert mit Dateipfaden und Zeilennummern)
• Checkliste interaktiver Elemente mit genügend Details, um sie zu bauen
• Welche Abschnitte der Referenzdateien der Schreibagent benötigt
• Was die vorherigen und nächsten Module abdecken (für Übergänge)

Die Code-Snippets sind der entscheidende token-sparende Schritt. Indem du sie in die Briefings vorab extrahierst, müssen Schreibagenten niemals die Codebasis lesen.

Phase 3: Den Kurs bauen

Die Kursausgabe ist ein Verzeichnis, keine einzelne Datei. Alle CSS- und JS-Dateien sind vorgefertigte Referenzdateien – generiere sie niemals neu. Deine Aufgabe ist es, nur den HTML-Inhalt zu schreiben.

Ausgabestruktur:

course-name/
  styles.css       ← wörtlich kopiert aus references/styles.css
  main.js          ← wörtlich kopiert aus references/main.js
  _base.html       ← angepasste Hülle (Titel, Akzentfarbe, Navigationspunkte)
  _footer.html     ← wörtlich kopiert aus references/_footer.html
  build.sh         ← wörtlich kopiert aus references/build.sh
  briefs/          ← Modul-Briefings (nur komplexe Codebasen, nach dem Bau löschbar)
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← von build.sh zusammengebaut (nicht manuell schreiben)

Schritt 1 (beide Pfade): Einrichtung – Erstelle das Kursverzeichnis. Kopiere diese vier Dateien wörtlich mit Lesen + Schreiben (generiere ihre Inhalte nicht neu):

• references/styles.css → course-name/styles.css
• references/main.js → course-name/main.js
• references/_footer.html → course-name/_footer.html
• references/build.sh → course-name/build.sh

Schritt 2 (beide Pfade): Passe _base.html an – Lese references/_base.html, schreibe es dann nach course-name/_base.html mit genau drei Ersetzungen:

• Beide Vorkommen von COURSE_TITLE → der tatsächliche Kurstitel
• Die vier ACCENT_*-Platzhalter → die gewählten Akzentfarbwerte (wähle eine Palette aus den Kommentaren in _base.html)
• NAV_DOTS → ein <button class="nav-dot" ...> pro Modul

Schritt 3: Module schreiben – Hier teilen sich die Pfade.

Sequentieller Pfad (einfache Codebasen)

Lese references/content-philosophy.md und references/gotchas.md. Schreibe dann die Module nacheinander. Schreibe für jedes Modul course-name/modules/0N-slug.html, das nur den <section class="module" id="module-N">-Block und seinen Inhalt enthält. Füge keine <html>, <head>, <body>, <style> oder <script>-Tags ein.

Lese references/interactive-elements.md für HTML-Muster für jeden interaktiven Elementtyp. Lese references/design-system.md für visuelle Konventionen.

Paralleler Pfad (komplexe Codebasen)

Verteile Module in Batches von bis zu 3 an Unteragenten. Jeder Agent erhält:

• Sein Modul-Briefing (aus course-name/briefs/)
• references/content-philosophy.md und references/gotchas.md
• Nur die Abschnitte von references/interactive-elements.md und references/design-system.md, die im Briefing aufgeführt sind

Jeder Agent schreibt seine Moduldatei(en) nach course-name/modules/. Kurze Module (3 Bildschirme, ein Quiz) können gepaart werden – zwei Briefings an einen Agenten.

Was Agenten NICHT erhalten: die vollständige Codebasis (Snippets sind im Briefing), SKILL.md, Briefings anderer Module oder nicht benötigte Referenzdateiabschnitte.

Nachdem alle Agenten fertig sind, führe eine schnelle Konsistenzprüfung im Hauptkontext durch: Navigationspunkte passen zu Modulen, Übergänge zwischen Modulen sind kohärent, keine offensichtlichen Tonverschiebungen.

Schritt 4 (beide Pfade): Zusammenbauen – Führe build.sh aus dem Kursverzeichnis aus:

cd course-name && bash build.sh

Dies erzeugt index.html. Öffne sie im Browser.

Kritische Regeln:

• Generiere styles.css oder main.js niemals neu – kopiere sie immer aus references/. Sie enthalten vorgefertigte Stile und Interaktivität.
• Schreibe index.html niemals manuell – build.sh erzeugt sie. Wenn sie nicht funktioniert, debugge build.sh.
• Füge in Moduldateien keine <style>-, <script>- oder <html>-Tags ein – nur den <section class="module">-Inhalt.
• Halte die Module unabhängig – kein Modul sollte auf eine bestimmte ID eines anderen Moduls verweisen (außer über Navigationspunkte). Module müssen neu angeordnet oder gelöscht werden können, ohne andere zu beschädigen.

Phase 4: Qualitätssicherung

Nach dem Zusammenbauen öffne index.html im Browser und überprüfe:

• Alle Module sind über die Navigation erreichbar
• Animationen laufen reibungslos
• Quizfragen funktionieren (richtige/falsche Rückmeldungen)
• Code-Blöcke werden mit korrekter Syntaxhervorhebung angezeigt
• Tooltips erscheinen bei technischen Begriffen
• Der Akzentfarbstil ist einheitlich
• Das Layout passt sich an mobile Bildschirme an
• Keine defekten Bilder oder Symbole
• Die Seite lädt ohne Fehler in der Konsole

Wenn etwas kaputt ist, behebe die zugrunde liegende Moduldatei, führe build.sh erneut aus und überprüfe noch einmal.

Dateireferenzen

Der Skill verlässt sich auf diese Dateien in deinem Dateisystem:

• references/styles.css – Vorlage für das Kurs-Stylesheet
• references/main.js – Vorlage für das Kurs-JavaScript
• references/_base.html – Vorlage für die Kurs-HTML-Hülle
• references/_footer.html – Vorlage für den Kurs-Fußzeilen-HTML
• references/build.sh – Vorlage für das Kurs-Build-Skript
• references/content-philosophy.md – Regeln für die Inhaltserstellung
• references/gotchas.md – Häufige Fallstricke und wie man sie vermeidet
• references/interactive-elements.md – HTML-Muster für interaktive Elemente
• references/design-system.md – Visuelle Konventionen
• references/module-brief-template.md – Vorlage für Modul-Briefings

Lese diese Dateien bei Bedarf, befolge aber ihre Regeln, anstatt ihren Inhalt zu kopieren, sofern nicht anders angegeben (die Vorlagendateien styles.css, main.js, _footer.html und build.sh müssen wörtlich kopiert werden).