Walid-Ahmed/flashcard-deck

Lernkarten-Deck

Verwandle ein Thema in ein Deck aus Frage-und-Antwort-Karten, die zuerst das allgemeine Konzept vermitteln, sauber drucken und zu YouTube-Videos werden können. Die Karten werden in einer Python-Datei (deck.py) mit kleinen Hilfsfunktionen geschrieben, und gebündelte Skripte rendern alles daraus – eine Korrektur an einer Karte ist also eine Bearbeitung und ein Neubuild.

Die Arbeit erfolgt in vier Phasen. Frage vor jeder Phase, die Zeit kostet oder etwas veröffentlicht, denn ein Deck ist nur nützlich, wenn es abdeckt, was der Benutzer braucht, und Videos brauchen Minuten zum Enkodieren.

1. Interview: frage, was gebaut werden soll.
2. Plan: schlage Themen und Kartenfragen vor; hole ein Ja ein.
3. Karten: schreibe deck.py, rendere, schaue dir jede Karte an, korrigiere, was nicht passt.
4. Extras (nur wenn gewünscht): Videos, Thumbnails, Veröffentlichung.

1. Interview

Beginne mit Fragen, nicht mit Bauen. Verwende das AskUserQuestion-Werkzeug, damit der Benutzer Antworten anklicken kann. Stelle alles in einem Aufruf (es können bis zu 4 Fragen sein) und überspringe jede Frage, die die Nachricht des Benutzers oder das offene Projekt bereits beantwortet. Biete zuerst eine empfohlene Option an, markiert mit „(Empfohlen)".

Frage nach Folgendem. Das Werkzeug kann bis zu 4 Fragen stellen. Wenn die Quelle das Material des Benutzers ist und eine fünfte Frage nötig wird, stelle die letzte in einem zweiten Aufruf.

• Quelle: Was die Karten abdecken. Optionen wie: vorhandenes Material (Dateien oder Ordner: PDFs, Folien, Word- oder Markdown-Notizen, ein Kurs, ein Repo oder vorhandene Lernkarten), dieses Repo, ein Thema aus eigenem Wissen oder Notizen, die der Benutzer einfügt. Wenn die Anfrage die Quelle bereits nennt, überspringe dies.
• Wie genau folgen (nur wenn die Quelle ihr Material ist): nur das, was das Material sagt (Empfohlen), das Material plus fehlende Grundlagen, markiert als hinzugefügt, oder das Material als Ausgangspunkt.
• Zielgruppe und Tiefe: Anfänger (eine Idee pro Karte, einfache Worte), Fortgeschrittene (Konzepte plus kurzes Codebeispiel) oder Experten (Kompromisse, Randfälle).
• Maximale Kartenanzahl: bis zu 10 (ein schnelles Set), bis zu 20 (Empfohlen), bis zu 40 (ein vollständiger Kurs) oder kein Limit (so viele wie das Material braucht). Der Benutzer kann jede andere Zahl eingeben. Notiere sie als deck(..., max_cards=N): Der Build stoppt, wenn das Deck darüber hinauswächst, sodass ein späteres Aufteilen von Karten das Limit nicht leise überschreiten kann. Mehr Karten bedeuten mehr Themen, nicht längere Karten.
• Ausgaben: nur Kartenbilder und PDFs (Empfohlen), plus Videos, plus Videos und Thumbnails. Videos kommen in jedem Fall erst nach Genehmigung der Karten.

Frage dann, falls noch unbekannt, als Klartext (kein Werkzeug nötig): den Deck-Titel, der auf jeder Karte erscheint (z. B. „FastAPI" oder „Kubernetes"), wo die Ausgabe gespeichert werden soll (schlage einen flashcards/-Ordner im aktuellen Projekt oder einen neuen Ordner vor) und ob Codebeispiele das Quellprojekt nennen dürfen oder allgemein bleiben sollen. Frage bei eigenem Material des Benutzers auch, ob jede Karte zeigen soll, woher sie stammt (z. B. „Kap. 3, S. 42").

2. Plan

Lies zuerst die Quelle. Wenn es Material ist, das der Benutzer bereits hat, lies jetzt references/existing-material.md: es behandelt das Lesen von PDFs, Folien, Word-Dateien, Ordnern und vorhandenen Lernkarten, das vollständige Erfassen des Materials, sodass nichts stillschweigend verloren geht, die Treue zum Material und die Verweisung jeder Karte auf ihre Seite. Bei einem Thema aus eigenem Wissen entscheide, was ein Lernender auf der gewählten Stufe braucht. Schlage dann das Deck als kurze Liste vor: Themen in Lernreihenfolge und darunter pro Karte eine Zeile mit ihrer Frage. Gruppiere nach Konzept (HTTP-Grundlagen, Validierung, Auth), nicht nach Datei. Strebe 3 bis 9 Karten pro Thema an. Ein kleines Deck (unter etwa 12 Karten) ist in Ordnung als 2 oder 3 Themen mit 2 bis 4 Karten.

Halte den Plan innerhalb der maximalen Kartenanzahl und lasse Platz für ein oder zwei Aufteilungen. Wenn das Material mehr Karten benötigt, als das Maximum erlaubt, decke zuerst die Kernideen ab, liste dann die ausgelassenen Themen oder Abschnitte auf und biete an, das Limit zu erhöhen.

Zeige den Plan und bitte um ein Ja, Änderungen oder Kürzungen, bevor du Karten schreibst. 40 Karten zu den falschen Themen zu schreiben, verschwendet die meiste Zeit, daher ist diese Prüfung eine Runde wert.

3. Karten

Schreibe deck.py, zuerst das erste Thema

Kopiere references/deck_template.py neben das Ausgabeverzeichnis. Schreibe die Karten des ersten Themas, rendere nur dieses Thema (--topic 1), zeige dem Benutzer zwei oder drei davon und frage, ob Stil und Tiefe passen. Dann schreibe den Rest. Auf Karte 3 herauszufinden, dass der Benutzer kürzere Karten wollte, ist billig; auf Karte 40 herauszufinden, ist es nicht. Lies references/components.md, bevor du die erste Karte schreibst: es zeigt jeden Baustein (Leitsatz, Boxen, Schritte, Tabellen, Codebeispiele, Hinweise, Diagramme) mit dem zu verwendenden HTML.

Wie man eine gute Karte schreibt – und warum:

• Konzept zuerst. Die Frage und der Eröffnungssatz (der lead) formulieren die allgemeine Idee in Worten, die überall gelten. Projektspezifischer Code kommt in eine example(...)-Box mit der Beschriftung „Beispiel: ...", sodass der Leser die Regel lernt und dann einen Fall sieht. Wenn das Beispielprojekt von der üblichen Praxis abweicht, sage das im Kommentar des Beispiels.
• Eine Idee pro Karte. Eine Frage, die zwei getrennte Ideen verbindet („Was ist X, und wie deployt man es?") braucht zwei Karten. Ein Kontrast („Wie unterscheidet sich X von Y?") oder ein Paar, das nur zusammen Sinn ergibt, ist eine Idee.
• Lead, dann Struktur, dann Beispiel. Ein ein- oder zweisätzige Antwort, dann zwei oder drei Boxen, Schritte oder eine kleine Tabelle, die es aufschlüsseln, dann ein optionaler Hinweis und ein Codebeispiel. Der Leser sollte die Antwort aus dem Lead allein erhalten.
• Der Footer ist die Merkzeile, unter 15 Wörtern. Der Tag ist ein oder zwei Wörter, die die Idee benennen.
• Klare, exakte Formulierung. Kurze Sätze. Nenne echte Statuscodes, Funktionsnamen und Befehle; deute sie nicht nur an.
• Diagramme nur dort, wo sie etwas hinzufügen: ein Ablauf, eine Entscheidung mit Fehlerpfaden oder die Teile einer URL oder Nachricht. Nicht auf Karten, deren Tabelle die Struktur bereits zeigt.
• Querverweise sagen, wo man nachschauen kann: „Karte 4 in App-Struktur zeigt die Serverseite."

Rendern und prüfen

python3 <skill-verzeichnis>/scripts/build_deck.py deck.py --out AUSGABE_VERZEICHNIS             # alle Karten, PDFs, README
python3 <skill-verzeichnis>/scripts/build_deck.py deck.py --out AUSGABE_VERZEICHNIS --topic 1   # ein Thema, schnelle Prüfung

<skill-verzeichnis> ist der Ordner, in dem diese SKILL.md liegt. Verwende python3 oder python, wenn das Python 3 ist. Das Skript benötigt Python mit playwright und Pillow (pip install playwright pillow) sowie Google Chrome oder playwright install chromium. Es rendert jede Karte als 2400 x 1698 px A4-Querformat-PNG, prüft, ob der Inhalt jeder Karte passt (Höhe und Breite), und benennt jede Karte, die nicht passt. Dann schreibt es ein PDF pro Thema, print/all-cards.pdf und README.md.

• Wiederholter Inhalt: Die Passgenauigkeitsprüfung misst Größe, nicht Sinn. Suche nach einer Box, die einen Schritt oder den Lead wiederholt, und streiche sie.
• Über dem Maximum: Der Build stoppt, wenn das Deck mehr Karten als max_cards hat. Verschmelze oder entferne die unwichtigsten Karten oder bitte den Benutzer, das Limit zu erhöhen. Erhöhe es nicht eigenmächtig.
• Eine Karte passt nicht: Kürze den Text, entferne eine Box oder teile sie in zwei Karten auf (z. B. „9a" und „9b" oder zwei Fragen). Verkleinere niemals die Schrift, um sie hineinzuzwängen; die Karten müssen beim Drucken lesbar bleiben.
• Sieh dir nach dem Rendern jede Karte an, indem du die PNGs öffnest. Die Passgenauigkeitsprüfung erfasst Überlauf, aber keine verwirrende Karte, ein irreführendes Diagramm oder einen Tippfehler. Korrigiere und rendere neu; --topic N rendert ein Thema schnell neu.
• Freiraum ist normal. Der Build meldet freien Platz in CSS-Px auf der 1200 x 849-Karte (das PNG ist doppelt so groß). Eine einfache Karte lässt oft 150 bis 350 px leer, und das ist in Ordnung zum Lesen und Drucken. Polstere keine Karte, um sie zu füllen. Wenn eine Karte über etwa 400 px freilässt und sich dünn anfühlt, verdient sie vielleicht ein Diagramm oder ein Beispiel, oder sie sollte in eine benachbarte Karte eingefügt werden.

4. Extras: Videos, Thumbnails, Veröffentlichung

Nur wenn der Benutzer sie möchte, und nachdem er die Karten genehmigt hat. Frage nach dem Videostil und gib eine ungefähre Enkodierungsdauer an (ca. 15 Sekunden Enkodierung pro Karte auf einem Laptop).

python3 <skill-verzeichnis>/scripts/build_videos.py deck.py --cards AUSGABE_VERZEICHNIS --out VIDEO_VERZEICHNIS [--mode both|questions|cards]
python3 <skill-verzeichnis>/scripts/build_thumbnails.py deck.py --cards AUSGABE_VERZEICHNIS --out VIDEO_VERZEICHNIS/thumbnails [--mode both|questions|cards]

• --mode both (Standard): jede Frage mit versteckter Antwort und einer Zeitleiste (6 s), dann die vollständige Karte (12 s).
• --mode questions: ein Quiz, jede Frage 10 s lang, keine Antworten.
• --mode cards: eine Wiederholung, jede vollständige Karte 15 s lang.
• Jeder Modus erzeugt ein Video pro Thema und eines mit allen Karten, benannt mit dem Modus (-questions, -cards), sodass sich Stile nie überschreiben. Übergib denselben --mode an build_thumbnails.py, damit die Namen übereinstimmen.
• Jedes Video hat einen Intro- und einen Titelbildschirm pro Thema sowie eine .txt-Beschreibung, deren Kapitel YouTube in anklickbare Abschnitte verwandelt. Kapitel sind mindestens 10 Sekunden lang, was YouTube verlangt.
• Videos benötigen ffmpeg. Halte VIDEO_VERZEICHNIS außerhalb jedes Git-Repos, da Videos groß sind.
• Thumbnails sind 1280 x 720 JPEGs, benannt passend zu jedem Video. topic(..., hook="A · B · C") setzt die kleine Zeile unter der Überschrift jedes Themas.
• Biete nach dem Build YouTube-freundliche Titel und Beschreibungen an: einen Titel unter 70 Zeichen mit dem Thema und dem Hook, eine Beschreibung mit der Eröffnungszeile, einem Aufzählungspunkt pro Thema, eventuellen Links und den Kapiteln aus der .txt.

Frage vor dem Pushen, Veröffentlichen oder Hochladen von irgendetwas; das erreicht andere Personen. Wenn die Codebeispiele des Decks aus einem Kurs oder Repo einer anderen Person stammen, erwähne das, bevor du es öffentlich machst, und biete eine Quellenangabe an (deck(..., credit="...") fügt eine in die README ein).

Ändern eines Decks später

Bearbeite deck.py und führe build_deck.py erneut aus; es baut alle Karten, die PDFs und die README neu und entfernt Bilder gelöschter Karten. Baue Videos nur neu, wenn der Benutzer sie aktualisiert haben möchte, und --descriptions-only schreibt nur die Videobeschreibungen neu.

Dateien in diesem Skill

• scripts/build_deck.py: Karten, Passgenauigkeitsprüfung, PDFs, README.
• scripts/build_videos.py, scripts/build_thumbnails.py: die Extras.
• scripts/flashcards/: die Helfer, die deck.py importiert (__init__.py), den Renderer (engine.py) und das Karten-Stylesheet (card.css: druckfreundlich, weiß mit farbigen Umrissen, festes A4-Querformat).
• references/components.md: jeder Kartenbaustein mit einem Beispiel. Vor dem Schreiben von Karten lesen.
• references/deck_template.py: ein kleines funktionierendes Deck zum Kopieren.
• references/existing-material.md: Erstellen eines Decks aus eigenen Notizen, PDFs, Folien, Repo oder Lernkarten des Benutzers. Lesen, wenn das die Quelle ist.