From 35f3d2c492801dfabb9f54d55db9a1a0c25a5266 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Wed, 13 May 2026 22:53:29 +0200 Subject: [PATCH] =?UTF-8?q?didaktisches=20fundament:=20CLAUDE.md=20+=20REA?= =?UTF-8?q?DME.md=20+=20AGENTS.md=20mit=20drei=20meta-lernzielen=20(gelern?= =?UTF-8?q?te=20hilflosigkeit=20ablegen,=20ber=C3=BChrungspunkte=20schaffe?= =?UTF-8?q?n,=20gef=C3=BChl=20f=C3=BCr=20technik),=20constructive=20alignm?= =?UTF-8?q?ent=20(biggs),=20advance=20organizer=20(ausubel),=20mayer=2012-?= =?UTF-8?q?prinzipien,=20informatikdidaktik-referenz=20(magenheim/romeike/?= =?UTF-8?q?hartmann),=20validierungs-checkliste=20pro=20folie,=20anti-patt?= =?UTF-8?q?ern-liste=20(bullet-vorlesen,=20motivations-cringe,=20theorie-f?= =?UTF-8?q?irst,=20folien-patchen).=20AGENTS.md=20von=20HdM-only=20auf=20u?= =?UTF-8?q?ni-slides=20(3=20kurse,=20unified=20make-pattern,=20port=201312?= =?UTF-8?q?,=20deploy=20tengo@tuttle,=20korrekte=20pfade)=20aktualisiert.?= =?UTF-8?q?=20.gitignore=20um=20assets-original/=20erg=C3=A4nzt=20(image-b?= =?UTF-8?q?ackups=20bleiben=20lokal)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 4 ++ AGENTS.md | 189 ++++++++++++++++++++++++++++++----------------------- CLAUDE.md | 39 ++++++++++- README.md | 20 ++++-- 4 files changed, 164 insertions(+), 88 deletions(-) diff --git a/.gitignore b/.gitignore index a8d908a..d8fb0fb 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,7 @@ hdm-internettechnik-slides/ *.tmp *.bak .idea + +# Image-Backups (Original-Quellen vor optimize-images) +slides/*/assets-original/ +slides/*/assets/*-original/ diff --git a/AGENTS.md b/AGENTS.md index 529d5a2..c5ba85c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,48 +1,59 @@ -# AGENTS.md - Agent Guidelines for HdM Slides +# AGENTS.md - Agent Guidelines for Uni Slides (HdM + DHBW) -This file contains comprehensive guidelines for agentic coding agents working on the HdM Slides project. +This file contains comprehensive guidelines for agentic coding agents working on the Uni Slides project. For the short version, see `CLAUDE.md`. ## Project Overview This project builds presentation decks for Marp, supporting multiple courses: -- **223015b** - Dateiformate, Schnittstellen, Speichermedien (6 Kapitel) -- **223015c** - Internettechnologien (3 Kapitel) + +- **223015b** – Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur) +- **223015c** – Internettechnologien (HdM, 3 Kapitel + Klausur) +- **dhbw** – Technik I – Grundlagen IT (DHBW, 8 Kapitel) ## Development Workflow ### Build Commands + +Unified per-course pattern: `make -`. Group targets without suffix run for all courses. Single dev server serves all courses. + ```bash -# Development -make dev # Start single dev server on port 3000 -npm run dev # Alternative command for development server +# Dev (all courses, single port) +make dev # Live server (HMR), port 1312 -# Build -make build # Build all courses (HTML + PDF) -make build-b # Build 223015b only -make build-c # Build 223015c only -make html # HTML only builds -make pdf # PDF only builds +# Per-course build/deploy (replace with: 223015b, 223015c, dhbw) +make build- # Build HTML + PDF +make html- # HTML only +make pdf- # PDF only +make klausur- # Extract klausur slides (HdM only) +make deploy- # Build + deploy single course (ASK FIRST!) -# Klausur Folien -make klausur # Extract klausurfolien for all courses -make klausur-b # Extract klausurfolien for 223015b -make klausur-c # Extract klausurfolien for 223015c - -# Deployment -make deploy # Deploy all courses (requires explicit permission) -make deploy-b # Deploy 223015b only -make deploy-c # Deploy 223015c only +# 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!) # Utilities -make qr URL=... # Generate QR code -make optimize-images COURSE=223015b # Resize images -make clean # Remove generated files +make qr URL=... # Generate QR code +make qr-slides COURSE= # QR for course URL +make optimize-images COURSE= # Resize images +make clean # Remove generated files +make install # npm install +``` + +**Adding a new course:** add id to `COURSES` in `Makefile` + define `_NAME`, `_KAPITEL`, `_DEPLOY`, `_KLAUSUR`. No new targets needed. + +### Nix Flake + +```bash +nix develop # Dev shell with all tools (node 22, npm, make) ``` ### Testing -No specific test framework is used. To validate changes: + +No formal test framework. To validate changes: 1. Start dev server: `make dev` -2. Open http://localhost:3000/223015b/ or /223015c/ +2. Open http://localhost:1312/223015b/, /223015c/, or /dhbw/ 3. Verify slides render correctly 4. Run `make build` to ensure no build errors 5. Check generated files in `build/` directory @@ -50,7 +61,18 @@ No specific test framework is used. To validate changes: ## Code Style Guidelines ### File Structure -- Slides in `slides//` following naming pattern `NN-topic.md` + +``` +slides/ +├── 223015b/ # HdM: Dateiformate +├── 223015c/ # HdM: Internettechnik +└── dhbw/ # DHBW: Technik I +scripts/ # Shared scripts +themes/ # Custom Marp themes +build/ # Generated output (gitignored) +``` + +- Slides in `slides//` following `NN-topic.md` (HdM) or `NN_topic.md` (DHBW) - Assets in `slides//assets/` - Always reference images as `./assets/filename.png` - Scripts in `scripts/` @@ -58,20 +80,22 @@ No specific test framework is used. To validate changes: - Generated output in `build/` (gitignored) ### Naming Conventions -- Slide files: `NN-topic.md` (e.g., `01-grundlagen.md`, `02-bilder.md`) + +- Slide files: `NN-topic.md` (HdM, e.g. `01-grundlagen.md`) or `NN_topic.md` (DHBW, e.g. `01_web_eng.md`) - Images: `snake_case.jpg` or `kebab-case.jpg` -- Klausur files: `klausurfolien.md` (auto-generated) -- Function names in scripts: `snake_case` -- Variable names in scripts: `snake_case` +- Klausur files: `klausurfolien.md` / `klausurfragen.md` (auto-generated, HdM only) +- Function/variable names in scripts: `snake_case` ### Markdown Style + - Use ATX-style headers (`# ## ###`) - YAML frontmatter for slide metadata at top of each file - Never include a final `---` (creates empty slide) -- Use `` for exam-relevant slides +- Use `` for exam-relevant slides (HdM) - Use relative paths for assets: `./assets/image.png` ### Script Style + - Use `#!/usr/bin/env bash` shebang - Use `set -e` for error handling - Use `2>/dev/null || true` for optional operations @@ -79,6 +103,7 @@ No specific test framework is used. To validate changes: - Use colors for terminal output: `\033[0;32m` etc. ### Git Workflow + - Commit messages: ALWAYS lowercase - NEVER add co-authoring lines or generated footers - Follow semantic naming: "add-...", "fix-...", "update-..." @@ -87,111 +112,113 @@ No specific test framework is used. To validate changes: ## Agent Restrictions ### Security -- NEVER run commands outside `/home/mwc/Coding/hdm` folder + +- NEVER run commands outside `/home/libretech/Repos/uni` - NEVER run build/deploy commands without explicit user request -- NEVER run deploy commands (make deploy, scp, etc.) without explicit permission +- NEVER run deploy commands (`make deploy`, `scp`, etc.) without explicit permission +- NEVER run `git checkout --` or `git restore` on files with uncommitted work. To undo specific changes, use targeted Edit operations instead. ### 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 -### Klausur Handling -- Klausur files (`klausurfolien.md`) are auto-generated -- NEVER edit klausurfolien.md files directly -- To update klausurfolien: edit source slides with `` markers -- Run `make klausur` to regenerate +### Klausur Handling (HdM only) + +- Klausur files (`klausurfolien.md`, `klausurfragen.md`) are auto-generated +- NEVER edit klausur files directly +- To update klausur: edit source slides with `` markers +- Run `make klausur` (or `make klausur-`) to regenerate +- DHBW course has no klausur extraction (`dhbw_KLAUSUR =` is empty) ## Development Patterns ### Adding New Slides -1. Create new file following `NN-topic.md` pattern + +1. Create new file following naming convention (`NN-topic.md` for HdM, `NN_topic.md` for DHBW) 2. Copy frontmatter from existing slides in the same course -3. Update Makefile `_KAPITEL` variable if needed +3. Add stem to `_KAPITEL` in `Makefile` 4. Test with `make dev` ### Modifying Existing Slides + 1. Edit the appropriate markdown file in `slides//` 2. Maintain consistent styling with course theme 3. Preserve image paths as `./assets/...` 4. Test changes with dev server ### Working with Assets + 1. Place images in `slides//assets/` 2. Use descriptive names: `diagram-network.jpg`, `example-code.png` -3. Optimize with `make optimize-images COURSE=223015b` +3. Optimize with `make optimize-images COURSE=` 4. Reference as `./assets/filename.ext` ### Course-Specific Configuration -Each course has specific settings in Makefile: -- Course name and title -- Kapitel list (slide files) -- Deploy path -- Theme colors (in generate-index.sh) + +Each course has these per-course settings in `Makefile`: +- `_NAME` – Display name +- `_KAPITEL` – Ordered list of slide file stems (without `.md`) +- `_DEPLOY` – Remote deploy path +- `_KLAUSUR` – `1` to enable klausur extraction, empty to disable ## Common Tasks ### Debugging Build Issues -1. Check Makefile syntax: `make -n build` -2. Verify Marp CLI installation: `npx @marp-team/marp-cli --version` + +1. Check Makefile syntax: `make -n build-` +2. Verify Marp CLI: `npx @marp-team/marp-cli --version` 3. Check file permissions: `ls -la slides/` -4. Validate markdown syntax with dev server +4. Validate markdown via dev server ### Updating Course Structure -1. Update `_KAPITEL` variables in Makefile + +1. Update `_KAPITEL` in `Makefile` 2. Ensure slide files follow naming convention 3. Update course-specific themes if needed -4. Test both dev and build processes +4. Test both `make dev` and `make build-` ### Working with Themes + - Custom theme in `themes/custom-theme.css` -- Course themes defined in individual slide frontmatter +- Course themes referenced in individual slide frontmatter - Use consistent color schemes per course - Test theme changes across all slides ## Deployment Process Deployment to production server requires explicit permission: -1. Build process: `make build` (HTML + PDF) -2. Index generation: automatically handled -3. Deploy to remote server via SCP -4. Root index deployment +1. Build: `make build` (HTML + PDF) or per-course `make build-` +2. Index generation: handled by `scripts/generate-index.sh` (per course) and `scripts/generate-root-index.sh` (root) +3. Deploy: `scp` to `tengo@tuttle.uberspace.de` via `make deploy-` or `make deploy` +4. Root index deployed by `make deploy-index` (or as part of `make deploy`) **IMPORTANT**: Never run deployment commands without explicit user permission. ## Tools and Dependencies -### Core Dependencies -- Marp CLI for slide rendering -- Bash scripts for automation +### Core +- Marp CLI for slide rendering (via `npx @marp-team/marp-cli`) +- Bash scripts for automation (`scripts/`) - Make for build orchestration - Git for version control -### Optional Tools -- qrencode for QR generation (via nix) -- ImageMagick for image optimization -- Python 3 for simple HTTP server (legacy) - -## Testing Strategy - -Since there's no formal test suite: -1. Manual testing with dev server -2. Build process validation -3. Slide rendering checks -4. Asset path verification -5. Cross-browser compatibility checks (important) +### Optional +- `qrencode` for QR generation (via nix-shell) +- ImageMagick for image optimization (via nix-shell) ## Troubleshooting ### Common Issues -- **Port conflicts**: Use `make dev-kill` to clean up processes -- **Build failures**: Check file permissions and Marp CLI installation -- **Asset loading**: Verify relative paths and file existence -- **Deploy issues**: Check SSH keys and remote permissions +- **Port conflicts**: kill the dev-server process holding port 1312 +- **Build failures**: check file permissions and Marp CLI availability via `npx` +- **Asset loading**: verify relative paths and file existence in `slides//assets/` +- **Deploy issues**: check SSH keys for `tengo@tuttle.uberspace.de` and remote permissions ### Getting Help -1. Check this AGENTS.md file first -2. Review Makefile targets and scripts +1. Check this `AGENTS.md` first +2. Review `Makefile` targets and `scripts/` 3. Test changes incrementally -4. Maintain backup of working configurations \ No newline at end of file +4. Maintain backup of working configurations diff --git a/CLAUDE.md b/CLAUDE.md index 417d13b..043668a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,10 +4,45 @@ This project builds presentation decks for Marp, supporting multiple courses. ## Courses -- **223015b** - Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur) -- **223015c** - Internettechnologien (HdM, 3 Kapitel + Klausur) +- **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 diff --git a/README.md b/README.md index 9ecdbc5..585a0bd 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,21 @@ Combined presentation slides for DHBW and HdM Stuttgart courses, built with [Mar ## Courses -| Code | Title | Origin | -|------|-------|--------| -| 223015b | Dateiformate, Schnittstellen, Speichermedien | HdM | -| 223015c | Internettechnologien | HdM | -| dhbw | Technik I – Grundlagen IT | DHBW | +| Code | Title | Origin | Fokus | +|------|-------|--------|-------| +| 223015b | Dateiformate, Schnittstellen, Speichermedien | HdM | **Dateien und Inhalte** | +| 223015c | Internettechnologien | HdM | **Internet und Web** | +| dhbw | Technik I – Grundlagen IT | DHBW | Grundlagen | + +## Didaktisches Fundament (HdM) + +Drei Meta-Lernziele bilden den Maßstab für jede inhaltliche Entscheidung: + +1. **Gelernte Hilflosigkeit ablegen** — Technik ist kein Mysterium. Keine Insider-Sprache ohne Erklärung; abstrakte Konzepte über konkrete Beispiele. +2. **Berührungspunkte schaffen** — Inhalte mit der Lebenswelt der Studierenden verknüpfen. Jedes Kapitel braucht mindestens einen Alltags-Anker. +3. **Erstes fundiertes Wissen und Gefühl für Technik** — kein Auswendiglernen, sondern ein belastbarer mentaler Bauplan. Lieber drei Konzepte in Tiefe als zwölf in Breite. + +Die operative Umsetzung (Werkzeuge, Validierungs-Kriterien, Anti-Pattern) ist in [CLAUDE.md](./CLAUDE.md#didaktisches-fundament-für-alle-hdm-kurse) dokumentiert und gilt für alle Beiträge — menschlich wie agentisch. ## Project Structure