123 lines
6.5 KiB
Markdown
123 lines
6.5 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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
|