wlsdnen/explainer-page

Erklärseite erstellen

Wann verwenden

• Beim Erstellen einer neuen Erklärseite (einfaches HTML oder Ordner).
• Bei grundlegenden Änderungen an Struktur, Abbildungen oder Erklärungen einer bestehenden Erklärseite.

Wenn im Seitenordner oder Projekt eine CLAUDE.md vorhanden ist, haben deren Regeln Vorrang vor diesem Skill.

Ausgabesprache

Die Standardausgabesprache ist Koreanisch (Hapsyo-Stil, lang="ko"). Fordert der Benutzer eine andere Sprache an oder legt die CLAUDE.md des Projekts eine fest, wird in dieser Sprache geschrieben, und das lang-Attribut, der Schriftstapel sowie die Stilregeln (siehe references/writing.md) werden entsprechend angepasst. Die übrigen Regeln gelten sprachunabhängig.

Ergebnis

• Eine eigenständige, einzelne index.html ohne Build-Schritt (Inline-CSS/JS). Videoclips oder Bilder werden im selben Ordner abgelegt.
• Externe Bibliotheken werden per CDN mit fester Version eingebunden oder, falls Offline-Nutzung erforderlich, als Dateien in den Ordner kopiert (Vendoring) und mit relativen Pfaden geladen. Der Benutzer wird gefragt, welche Variante bevorzugt wird, oder die Entscheidung wird in der CLAUDE.md des Seitenordners festgehalten.

Arbeitsschritte

1. Material sammeln und Fakten prüfen

• Paper, Videos, Code-Repositories, technische Blogs/Webseiten direkt öffnen und lesen. Behauptungen und Zahlen in der Seite anhand der Originalquellen (Tabellen-/Abbildungsnummern, Vorlesungszeitstempel, Codepositionen, Blogabschnitte) überprüfen. Wenn ein Blog ein Paper zitiert, nach Möglichkeit im Paper selbst nachprüfen.
• Eine Liste der erforderlichen Vorkenntnisse erstellen, die zum Verständnis des Texts nötig sind. Diese dient als Grundlage für das Interview im nächsten Schritt.

2. Zielgruppeninterview (vor der Gliederung zwingend erforderlich)

• Mit AskUserQuestion (Mehrfachauswahl) für jedes Vorkonzept fragen: „Bekannt / Unsicher / Unbekannt“. Falls AskUserQuestion nicht verfügbar ist, die Frage als Text stellen.
• Je nach Antwort tiefer nachfragen, bis das für das Textverständnis erforderliche Niveau feststeht.
• Das Ergebnis im Abschnitt ## Zielgruppenniveau der CLAUDE.md des Seitenordners pro Konzept dokumentieren. Bei späteren Änderungen dieses Protokoll lesen und das Niveau beibehalten. Beim Veröffentlichen der Seite wird die CLAUDE.md nicht hochgeladen.
• Umsetzung im Text:
  • Unbekannt: Im Text ausführlich erklären.
  • Unsicher: In einem kurzen Wiederholungsfeld (<details>) unterbringen.
  • Bekannt: Erklärung weglassen.

3. Gliederung

• Zuerst den Seitenfluss und die Abschnittsüberschriften (als Thesensätze) festlegen. Pro Abschnitt entscheiden, welche Abbildung (Animation, statisches Bild, Schieberegler) und welcher Clip die These veranschaulichen.
• Bei Themen mit Daten, Modellen und Evaluation den Fluss von den Daten bis zu den Evaluationsmetriken in die Abschnittsstruktur einbeziehen.
• Details: references/writing.md, references/visuals.md.

4. Erstellung

• Einzelne index.html mit Inline-CSS/JS. Berechnungslogik in ein skript ohne DOM-Zugriff auslagern.
• Wenn Videoquellen vorhanden sind, für jeden Erklärungsabschnitt einen Clip einfügen.
• Details: references/writing.md, references/visuals.md, references/style.md.

5. Verifikation

• Mit scripts/check_page.py bei 375, 768 und 1280 px Breite auf horizontalen Überlauf, Konsolenfehler und die Größe des ersten [data-widget]-Touch-Ziels prüfen.
• Auch alle Bedienelemente, Animationen und die Berechnungslogik (check.mjs) überprüfen.
• Befehl: references/verify.md.

Kernregeln

• Fakten: Nur Behauptungen und Zahlen aus dem Paper verwenden, die in der Originalquelle bestätigt wurden. Jede Zahl mit einem Tag (Paper/Blog/Vorlesung/Berechnung/Beispiel) versehen.
• Aufbau: Titel + Einzeiler-Zusammenfassung → Abschnitte → Fallstricke/Missverständnisse → Quellen. h2 als Thesensatz.
• Im Abschnitt: 1–2 Sätze, worum es geht → Abbildung → kurze Erklärung, warum das so ist. Herleitungen und Ausnahmen in <details>.
• Formeln: Nicht die gesamte Herleitung, sondern die Rolle jedes Terms und das Kernkonzept.
• Abbildungen: Nur solche, mit denen der Leser die These selbst überprüfen kann. Standard ist eine automatisch abspielende Animation (Wiedergabe/Pause & Zurücksetzen).
• Stil: Hapsyo-Stil (Standardsprache), maximal 3 Sätze pro Absatz, höchstens eine Metapher pro Abschnitt.
• Design: Für jede Seite neu an das Thema anpassen (kein Kopieren bestehender Seiten). Feste Anforderungen: Nur Hellmodus (color-scheme: light), Farben über CSS-Variablen zentral verwalten.

Fertigstellungs-Checkliste

• Im Seitenordner gibt es eine CLAUDE.md mit dem Abschnitt ## Zielgruppenniveau.
• Alle als „Unbekannt“ markierten Konzepte werden im Text erklärt.
• Alle als „Unsicher“ markierten Konzepte haben ein <details>-Wiederholungsfeld.
• Alle h2 sind Thesensätze.
• Alle Zahlen sind getaggt; die Tags Paper und Blog wurden an der Originalquelle überprüft.
• Bei jeder Formel wird die Rolle jedes Terms erklärt.
• Bei Daten, Modellen und Evaluation ist der Fluss von Datenbereinigung → Ein-/Ausgabeformat → interne Modellverarbeitung → Ausgabe → Verlustfunktion/Training → Evaluationsmetriken mit Abbildungen dargestellt.
• Es gibt keine dekorativen Abbildungen; im Standardzustand der Bedienelemente ist das Phänomen sofort sichtbar; unter jeder Abbildung steht ein einzeiliger Hinweis.
• Bei Videoquellen gibt es Abschnittsclips und Untertitel in der Ausgabesprache (z.B. .ko.vtt).
• Ganz unten gibt es eine Quellenliste (Links zu Paper, Video, Code-Repository, Blog/Webseite).
• lang-Attribut, Viewport, <title>, color-scheme: light, Farben werden über CSS-Variablen verwaltet.
• Layout und Farben passen zum Charakter des Themas; das Design wurde nicht von einer bestehenden Seite kopiert.
• check_page.py ist bestanden; alle Bedienelemente und Animationen funktionieren.
• Bei vorhandener Berechnungslogik ist node check.mjs bestanden.