public/uni
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

didaktisches fundament: CLAUDE.md + README.md + AGENTS.md mit drei meta-lernzielen (gelernte hilflosigkeit ablegen, berührungspunkte schaffen, gefühl für technik), constructive alignment (biggs), advance organizer (ausubel), mayer 12-prinzipien, informatikdidaktik-referenz (magenheim/romeike/hartmann), validierungs-checkliste pro folie, anti-pattern-liste (bullet-vorlesen, motivations-cringe, theorie-first, folien-patchen). AGENTS.md von HdM-only auf uni-slides (3 kurse, unified make-pattern, port 1312, deploy tengo@tuttle, korrekte pfade) aktualisiert. .gitignore um assets-original/ ergänzt (image-backups bleiben lokal)

Browse Source
This commit is contained in:
libretech
2026-05-13 22:53:29 +02:00
parent 82407679b5
commit 35f3d2c492
4 changed files with 164 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+4
View File
@@ -34,3 +34,7 @@ hdm-internettechnik-slides/
*.tmp
*.bak
.idea
# Image-Backups (Original-Quellen vor optimize-images)
slides/*/assets-original/
slides/*/assets/*-original/
AGENTS.md
+108 -81
View File
@@ -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 <target>-<course>`. 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 <c> with: 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!)
# 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=<c> # QR for course URL
make optimize-images COURSE=<c> # Resize images
make clean # Remove generated files
make install # npm install
```
**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
```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/<course>/` 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/<course>/` following `NN-topic.md` (HdM) or `NN_topic.md` (DHBW)
- Assets in `slides/<course>/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 `<!-- _class: klausur -->` for exam-relevant slides
- Use `<!-- _class: klausur -->` 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 `<!-- _class: klausur -->` 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 `<!-- _class: klausur -->` markers
- Run `make klausur` (or `make klausur-<c>`) 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 `<course>_KAPITEL` in `Makefile`
4. Test with `make dev`
### Modifying Existing Slides
1. Edit the appropriate markdown file in `slides/<course>/`
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/<course>/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=<c>`
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`:
- `<c>_NAME` – Display name
- `<c>_KAPITEL` – Ordered list of slide file stems (without `.md`)
- `<c>_DEPLOY` – Remote deploy path
- `<c>_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-<c>`
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 `<c>_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-<c>`
### 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-<c>`
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-<c>` 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/<c>/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
4. Maintain backup of working configurations
CLAUDE.md
+37 -2
View File
@@ -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
README.md
+15 -5
View File
@@ -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