rzhang569/study-guide

Studienführer

Du erstellst eine eigenständige HTML-Seite pro Prüfung, die aus einem Kursordner mit einfachen Dateien von scripts/build.py erstellt wird. Die Seite besteht aus drei Teilen:

• Notizen, ein Abschnitt pro Vorlesung. Jede Behauptung verweist auf eine Folienseite. Jedes Thema wird mit verständlichen Boxen, durchgerechneten Beispielen, Abbildungen und roten "Fallen"-Boxen ergänzt. Eine Übungsbox am Ende jedes Abschnitts ermöglicht es dem Studierenden, sich direkt nach dem Lesen selbst zu testen.
• Ein Übungszentrum mit vier Reitern:
  • eine Übungsdatenbank mit sofortiger Rückmeldung und einer Erklärung für jede Option;
  • Schritt-für-Schritt-Kurzantworten mit Teilpunkten;
  • zeitgesteuerte Probeklausuren aus einem eigenen Pool in den Proportionen der echten Prüfung;
  • ein Fehlernotizbuch, das sich selbst befüllt.
• Ein Fortschrittsbericht, den die Seite für dich speichert. Du liest ihn später und schreibst neue Übungen, die genau das abdecken, was der Studierende tatsächlich falsch gemacht hat.

Die Engine (assets/engine.js) und die Stile (assets/page.css) sind fertig und getestet, deine Aufgabe sind die Inhalte und die Fragen. Der größte Teil dessen, was eine Seite nützlich macht, befindet sich in den Referenzdateien; lies sie, wenn du diesen Schritt erreichst.

Wenn du kurz davor bist...	Lies
die Vorlesungsabschnitte zu schreiben	references/content-standard.md
Fragen zu schreiben oder zu überprüfen oder die Probeklausur zu kalibrieren	references/question-bank.md
einen Feldnamen, das Fortschrittsformat oder die DB-Dokumentation zu überprüfen	references/data-format.md

examples/demo/ ist ein vollständiger kleiner Kurs (fiktiver PROB 101, drei Vorlesungen). Wenn du unsicher bist, wie etwas aussehen soll, kopiere das Muster aus seinen Quellen: sections/*.html, practice.json, mock.json und short.json.

Lies nicht assets/engine.js, assets/page.css oder eine erstellte review.html. build.py bindet sie ein, sie enthalten Zehntausende von Tokens, und nichts darin benötigt deine Bearbeitung.

In den folgenden Befehlen ist <skill-dir> der Ordner, der diese SKILL.md enthält. Wenn python3 nicht gefunden wird (häufig unter Windows), verwende python oder py -3.

1. Finde heraus, was die Prüfung ist

Ermittle diese Fakten, bevor du etwas schreibst. Suche sie nach Möglichkeit selbst, und frage den Studierenden nur nach dem, was du nicht finden kannst:

• Prüfung: Datum und Uhrzeit, Dauer in Minuten, welche Vorlesungen im Rahmen liegen, das Format und erlaubte Hilfsmittel. Format bedeutet Fragetypen, wie viele von jedem und deren Punkte. Hilfsmittel bedeuten Notizblätter, einen Taschenrechner oder nichts.
• Quellen: Folien (PDFs oder Links), Lektüre, die Kurswebsite und alle offiziellen Übungsfragen, Quiz-Ergebnisse oder Beispielprüfungen.
• Studierender: Die Sprache, in der die Seite sein soll (lang: zh oder en für die Oberfläche; schreibe den Inhalt in ihrer Sprache) und wie stark ihr Hintergrundwissen ist. Ein Studierender, der sagt „Ich bin verloren", benötigt auf fast jedem Thema verständliche Boxen.

Wenn du browsen kannst, recherchiere den Kurs selbst: die Stundenplanseite, den Syllabus und veröffentlichte Quiz-Ergebnisse. Achte auf Muster, die es wert sind, dem Studierenden mitgeteilt zu werden, wie „Die Checkpoint-Fragen im Unterricht kommen direkt nach einer bestimmten Folie" oder „Der offizielle Fragenkatalog sagt, er verwendet dasselbe Format wie die Prüfung". Füge die Logistik in den Heldenbereich der Seite ein.

Überprüfe die KI-Richtlinie des Kurses im Syllabus. Einige Kurse verbieten KI-generiertes Studienmaterial oder KI-Hilfe bei benoteten Arbeiten. Wenn die Richtlinie dies verbietet, informiere den Studierenden vor dem Erstellen. Gib niemals Antworten auf benotete Hausaufgaben auf die Seite.

2. Kalibriere die Probeklausur ohne Spoiler

Studierende möchten die offizielle Beispielprüfung oft für einen einzigen zeitgesteuerten Durchlauf aufheben. Lies dann nicht ihre Fragen; vermesse sie stattdessen:

python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf

Das Skript gibt niemals Frage-, Options- oder Szenariotexte aus. Es gibt aus:

• die Anzahl der Seiten und Fragen sowie die Optionen pro Frage;
• Punktwerte, die Zeitbegrenzung und die Deckblattanweisungen (Taschenrechner, Notizen);
• Teilüberschriften und Fragenbereiche, die ein Szenario teilen („Fragen 11–14 …");
• die Nummern der Fragen, die auf früheres Material verweisen.

Verwende die Ausgabe, um die Mock-Abschnitte (Typen und Anzahlen) und die Zeitbegrenzung festzulegen. Eine Frage, die auf etwas zurückverweist, wie eine Kurzantwort, die ein früheres Szenario wiederverwendet, gehört zu diesem Szenario, wenn du die Struktur der Prüfung beschreibst.

Wenn das Skript dir etwas nicht sagen kann, melde es als unbekannt und bitte den Studierenden, auf das Deckblatt zu schauen. Schreibe keine eigene Sonde, die Wörter oder Zahlen aus den Fragen ausgibt. Selbst ein verirrtes „insgesamt" oder „%" gibt einen Hinweis auf das Thema einer Frage, und die Zahlen in einer Gleichung verraten die Frage.

Frage, bevor du eine Beispielprüfung oder einen Lösungsschlüssel öffnest. Selbst wenn der Studierende das Lesen erlaubt, verwende es nur zur Kalibrierung (Struktur, Schwierigkeit, Stil). Kopiere niemals seine Fragen oder Szenarien in die Seite.

3. Richte den Kursordner ein

python3 <skill-dir>/scripts/build.py --init <course-dir>

Dies kopiert den Demo-Kurs. Bearbeite dann course.json:

• title, lang und lectures. Vorlesungsbezeichnungen sind genau das, was Fragen und Gruppen verwenden, z.B. "L1" oder "L5–L6".
• storageKey: eindeutig pro Kurs und Prüfung, z.B. "bio201-mt1". Der Fortschritt wird darunter gespeichert, also ändere ihn nie, sobald der Studierende begonnen hat.
• mock.sections: ein Eintrag pro Fragetyp, in Prüfungsreihenfolge, mit Anzahlen, die dem echten Papier entsprechen.
• mock.minutes: zu wählende Zeitbegrenzungen. Nimm die echte auf; wenn die Probeklausur lange Fragen auslässt, biete auch eine proportional kürzere an.

Lösche die Demo-Abschnitte und -Fragen, während du sie ersetzt. Siehe references/data-format.md für jedes Feld.

4. Schreibe die Abschnitte

Schreibe eine Datei pro Vorlesung in sections/ (10-l1.html, 20-l2.html, …), plus 00-hero.html für Logistik und eine abschließende Fallenliste. Jede Vorlesung ist ein <section class="part" id="...">. Ihre Übungsbox erscheint automatisch, wenn eine Übungsgruppe mit "sec" auf diese id zeigt.

references/content-standard.md enthält das vollständige Rezept und das HTML für jede Komponente. Kurz gesagt: Zitiere jede Behauptung, beginne schwierige Vorlesungen mit einem Glossar und Analogien, gib jedem Thema eine einzeilige Einleitung, ein konkretes Beispiel vor jeder Formel, eine verständliche Box, eine Abbildung, wo ein Bild hilft, und eine Fallenbox für das, was Wahr/Falsch-Fragen verdrehen.

5. Schreibe die Fragen

Es gibt drei Datenbanken. references/question-bank.md enthält die Regeln und die Prüfcheckliste.

• practice.json: 8–15 Fragen pro Vorlesung. Mische Einzelauswahl, Wahr/Falsch, Mehrfachauswahl und Lückentexte, plus gelegentlich eine Karteikarte. Jede Option hat ihre eigene Erklärung.
• mock.json: eigene Fragen, niemals Kopien von Übungsaufgaben. Ziele auf etwa das Doppelte dessen, was ein Papier von jedem Typ zieht, damit sich wiederholte Papiere unterscheiden. Passe den Stil der echten Prüfung an.
• short.json (optional): Schritt-für-Schritt-Versionen der Kurzantworttypen der Prüfung. Jeder Schritt ist ein toleranter Lückentext, eine Auswahl oder ein Selbstcheck gegen die Musterantwort.

6. Erstellen und überprüfen

python3 <skill-dir>/scripts/build.py <course-dir>

Fehler stoppen den Build. Warnungen kommen von den Fragebank-Prüfungen; behebe sie, es sei denn, du hast einen Grund, es nicht zu tun. Sie kennzeichnen Muster wie:

• die richtige Antwort ist bei zu vielen Fragen die längste Option;
• ein Buchstabe wird zu oft als gezeigte Antwort angezeigt;
• jede Mehrfachauswahl hat die gleiche Anzahl von Antworten;
• eine Mock-Frage ist eine Übungsfrage mit neuen Zahlen.

Füge --strict hinzu, um Warnungen den Build mit Exit-Code 2 beenden zu lassen (die Seite wird trotzdem geschrieben), damit du weiter korrigieren kannst, bis er sauber ist. Öffne dann <course-dir>/review.html in einem Browser und überprüfe:

• die Konsole zeigt keine Fehler und Formeln werden gerendert;
• das Beantworten einer Übungsfrage, eines Kurzantwort-Schrittes und einer vollständigen Mock-Klausur funktioniert;
• bei 375 px Breite scrollt nichts auf der Seite seitwärts (Abbildungen und Tabellen scrollen innerhalb ihrer eigenen Boxen);
• kein Text in einer Abbildung überlappt eine Linie, eine Pfeilspitze oder anderen Text (mache einen Screenshot).

7. Liefern

• Lokal (beliebiger Agent): Gib den Dateipfad an. Der Fortschritt wird im localStorage dieses Browsers gespeichert. Die Schaltfläche Fortschritt exportieren im Übungszentrum gibt dem Studierenden JSON zum Zurückkopieren an dich.
• claude.ai artifact (nur Claude; experimentell, noch nicht Ende-zu-Ende getestet): Veröffentliche das erstellte HTML und gewähre die db-Fähigkeit. Wenn window.claude.use("db") verfügbar ist, spiegelt die Engine den Fortschritt in die Dokumente progress/practice und progress/mock und behält eine Zusammenfassung in progress/report. Bevor du dich darauf verlässt, beantworte eine Frage auf der veröffentlichten Seite und lies progress/report zurück. Wenn das Dokument fehlt, sage dem Studierenden, er solle stattdessen Fortschritt exportieren verwenden.

Sage dem Studierenden in zwei oder drei Zeilen, wie er die Seite verwenden soll: Lesen Sie einen Abschnitt, machen Sie die zugehörige Übungsbox, Probeklausuren gegen Ende und das Fehlernotizbuch am Tag davor.

8. Schließe den Kreislauf

Wenn der Studierende zurückkommt, lies seinen Fortschritt, bevor du etwas änderst. Verwende das exportierte JSON, das er einfügt oder sendet (sein report-Feld), oder das DB-Dokument progress/report, falls die Artefakt-Synchronisation funktioniert. Der Bericht listet auf:

• Genauigkeit beim ersten Versuch pro Vorlesung;
• jede verpasste Übungsfrage mit der gegebenen und der richtigen Antwort;
• Kurzantwort-Schritte, die er verpasst hat;
• Mock-Klausur-Verlauf, plus die falschen und markierten Fragen des letzten Papiers.

Dann:

1. Benenne die Schwachstellen in einigen Zeilen. Zähle Vorlesungen unter etwa 80 % Treffergenauigkeit beim ersten Versuch, wiederholte Fehlvorstellungen und Kurzantwort-Schritte, die immer wieder scheitern. Zähle auch Fragen, die als unsicher markiert, aber richtig beantwortet wurden; auch das ist wackliges Wissen.
2. Schreibe neue Übungen für jede Schwachstelle. Frage dasselbe Konzept mit anderen Worten, Zahlen oder Szenarien ab; wiederhole niemals die Frage, die er verpasst hat. Füge sie mit neuen IDs zu practice.json und, wenn der Mock-Pool dort dünn ist, zu mock.json hinzu.
3. Korrigiere die Erklärung, nicht nur die Fragen. Wenn sich eine Fehlvorstellung wiederholt, erklärt der Abschnitt sie wahrscheinlich schlecht. Füge eine verständliche Box, ein durchgerechnetes Beispiel oder eine Abbildung hinzu, die genau auf diese Verwechslung abzielt.
4. Baue neu, dann sage dem Studierenden, was sich geändert hat und wo.

Halte gespeicherte Fortschritte beim Bearbeiten gültig

Datensätze sind durch storageKey, Fragen-id und ursprünglichen Optionsindex eindeutig. Also:

• behalte den storageKey und vorhandene IDs bei;
• ordne keine Optionen in beantworteten Fragen neu an, füge keine ein und lösche keine (füge stattdessen eine neue Frage an);
• verwende keine alte ID für eine andere Frage wieder;
• wenn sich die Bedeutung oder Antwort einer Frage ändert, gib ihr eine neue ID und entferne die alte. Datensätze für entfernte IDs werden ignoriert, nicht falsch interpretiert.

Die Engine mischt die Reihenfolge, in der Optionen angezeigt werden, mit einem Seed aus der ID, sodass die gespeicherten Indizes korrekt bleiben. Um zu ändern, als welcher Buchstabe eine Antwort angezeigt wird, setze "show" (siehe references/data-format.md) anstatt Optionen neu anzuordnen. Das Korrigieren von Tippfehlern oder Formulierungen in Stämmen und Erklärungen ist immer sicher, ebenso wie das Bearbeiten von Abschnitts-HTML.

Was Studierende sich gewünscht haben

Diese Lektionen stammen aus dem Erstellen von Überprüfungsseiten, die für echte Prüfungen verwendet wurden:

• Abstrakte Erklärungen kamen nicht an. Studierende wollten zuerst konkrete Zahlen („Wirf eine Münze 10 Mal …"), dann die Formel, wobei Ableitungen ausgeklappt und als nicht prüfungsrelevant gekennzeichnet wurden.
• Das Lernen mehrerer Vorlesungen vor dem Üben war ermüdend. Deshalb endet jeder Abschnitt mit einer eigenen Übungsbox.
• Format-Pingeligkeit war frustrierend, z.B. als falsch bewertet für 1/2 statt 0.5. Die Engine vergleicht numerische Antworten nach Wert; liste Textvarianten in accept auf.
• Studierende lernen Antwortmuster schnell. Die richtige Antwort war normalerweise die längste Option, jede Mehrfachauswahl hatte 3 Antworten, und die richtige Antwort war immer B. Der Build prüft die ersten beiden; die Engine mischt die Anzeigereihenfolge.
• Eine Probeklausur, die Übungsfragen wiederverwendete, maß das Gedächtnis, nicht das Verständnis. Deshalb ist der Mock-Pool getrennt.
• Studierende wollten Optionstext zum Kopieren auswählen können, und einen Timer, der sich automatisch abschaltet, wenn die Zeit abläuft.