uni/CLAUDE.md

CLAUDE.md - Agent Guidelines for Uni Slides (DHBW + HdM)

This project builds presentation decks for Marp, supporting multiple courses.

Courses

• 223015b - Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur) — Fokus: Dateien und Inhalte
• 223015c - Internettechnologien (HdM, 3 Kapitel + Klausur) — Fokus: Internet und Web
• dhbw - Technik I – Grundlagen IT (DHBW, 8 Kapitel)

Didaktisches Fundament (für alle HdM-Kurse)

Diese drei Meta-Lernziele sind der Maßstab für jede inhaltliche Entscheidung — Folien, Reihenfolge, Beispiele, Übungen, Sprache. Jede Folie soll mindestens eines davon bedienen.

1. Gelernte Hilflosigkeit ablegen. Studierende sollen am Ende fühlen, dass Technik kein Mysterium ist, das sie überfordert. Konsequenz: keine Insider-Sprache ohne Erklärung, jeder Begriff wird beim ersten Auftreten geöffnet, abstrakte Konzepte werden über konkrete Beispiele eingeführt (nicht andersrum).
2. Berührungspunkte schaffen. Studierende sollen das Material mit ihrer eigenen Lebenswelt verknüpfen. Konsequenz: jedes Kapitel braucht mindestens einen Anker im Alltag der Studierenden (Smartphone, WhatsApp, Foto, Instagram-Story, eigener Laptop, eigener Browser, eigene Hex-Farbe). Theorie ohne Anker streichen oder umbauen.
3. Erstes fundiertes Wissen und Gefühl für Technik. Nicht Auswendiglernen. Nicht „Klausurwissen". Ein belastbarer mentaler Bauplan, der sich später erweitern lässt. Konsequenz: lieber drei Konzepte in Tiefe als zwölf in Breite. Vereinfachen ist erlaubt, solange das Modell nicht falsch wird.

Didaktische Werkzeuge, die wir anwenden

• Constructive Alignment (Biggs): Lernziele → Aktivitäten → Prüfung → Folien (in dieser Reihenfolge). Keine Folien-Restrukturierung ohne benannte Lernziele.
• Advance Organizer (Ausubel): Jeder Themenblock öffnet mit einem visuellen Schema, das die Struktur des Bogens (nicht ein konkretes Beispiel) zeigt. Ankert Vorwissen, gibt Orientierung.
• Mayer Multimedia (12 Prinzipien): Coherence (Deko-frei), Signaling (visuelle Cues), Redundancy-Vermeidung (Folientext ≠ Vorlesungstext), Spatial Contiguity (Text + Bild zusammen), Pre-Training (Grundbegriffe vor Komplexem), Personalisation.
• Informatikdidaktik (Magenheim / Romeike / Hartmann): Abstrakt-Konkret-Brücke ist nicht optional, sondern Pflicht. Beispiele aus der Lebenswelt zuerst, Formalisierung danach.

Validierungs-Kriterien (vor Commit / Deploy prüfbar)

Jede neue oder geänderte Folie soll folgende Fragen positiv beantworten können:

• Welches der drei Meta-Lernziele bedient diese Folie?
• Welches konkrete Lernziel des Themenblocks (formuliert mit Verb: analysieren, identifizieren, herleiten, begründen, einordnen, anwenden) wird hier vorbereitet, gestützt oder geprüft?
• Gibt es einen Berührungspunkt zur Lebenswelt der Studierenden auf dieser Folie oder im direkten Umfeld?
• Würde ein Student ohne Vorkenntnisse den Begriffsapparat dieser Folie verstehen — oder gibt es ungeöffnete Insider-Sprache?
• Folientext ≠ wortwörtlicher Vorlesungstext (Mayer Redundancy)?
• Wäre die Folie ohne den vorhergehenden Block verständlich? (Sollte NEIN sein — Folien sind nicht Inseln, sondern Schritte.)

Wenn eine dieser Fragen verneint wird: nicht committen, sondern umbauen oder begründen warum die Ausnahme akzeptabel ist.

Anti-Pattern, die wir vermeiden

• Bullet-Vorlesen: Folientext ist nicht das, was der Dozent sagt. Es ist der visuelle Anker für das, was der Dozent sagt.
• Motivations-Cringe: Keine Anbiederung an Studierende durch billige Provokationen („Wer hat schon mal..." als Selbstzweck). Anker müssen substanziell sein.
• Theorie-First: Niemals Definition vor Beispiel, wenn das Beispiel die Definition selbst-erklärend macht.
• Folien-Patchen: Bei kaputtem Bogen keine Brücken-Folien einbauen — sondern die Lernziel-Struktur prüfen und ggf. den ganzen Block neu denken.

Agent Restrictions

• Agent NEVER runs commands outside this folder
• Agent NEVER runs build/deploy commands without explicit user request
• Agent NEVER runs deploy commands (make deploy, scp, etc.) without explicit user permission
• Agent NEVER runs git checkout -- or git restore on files with uncommitted work. To undo specific changes, use targeted Edit operations instead.

Critical File Protection

Slide files in slides/*/*.md are main content files:

• ALLOWED: Adding slides, adjusting content, fixing typos, enhancing sections
• FORBIDDEN (without permission): Deleting slides, removing sections, bulk deletions
• Before ANY deletion: ALWAYS ask user for confirmation

Project Structure

slides/
├── 223015b/            # HdM: Dateiformate
├── 223015c/            # HdM: Internettechnik
└── dhbw/               # DHBW: Technik I
scripts/                # Shared scripts
themes/                 # Custom Marp themes
build/                  # Generated output (gitignored)

Build Commands

Unified per-course pattern: make <target>-<course>. Group targets without suffix run for all courses. Single dev server serves all courses.

# Dev (all courses, single port)
make dev             # Live server (HMR), port 1312

# Per-course build/deploy (replace <c> with course id: 223015b, 223015c, dhbw)
make build-<c>       # Build HTML + PDF
make html-<c>        # HTML only
make pdf-<c>         # PDF only
make klausur-<c>     # Extract klausur slides (HdM only)
make deploy-<c>      # Build + deploy single course (ASK FIRST!)

# All courses
make build           # Build everything
make html / pdf      # HTML / PDF only
make klausur         # Extract klausur (HdM courses only)
make deploy          # Deploy everything (ASK FIRST!)

Adding a new course: add id to COURSES in Makefile + define <id>_NAME, <id>_KAPITEL, <id>_DEPLOY, <id>_KLAUSUR. No new targets needed.

Nix Flake Commands

nix develop                           # Dev shell with all tools (node 22, npm, make)

Code Style Guidelines

File Structure

• Slides in slides/<course>/
• Assets in slides/<course>/assets/
• Always reference images as ./assets/filename.png

Naming Conventions

• Slide files: NN-topic.md (e.g., 01-grundlagen.md)
• Images: snake_case.jpg or kebab-case.jpg

Markdown Style

• Use ATX-style headers (# ## ###)
• Frontmatter for slide metadata
• Never include a final --- (creates empty slide)

Git Workflow

• Commit messages: ALWAYS lowercase
• NEVER add co-authoring lines or generated footers