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 *.tmp
*.bak *.bak
.idea .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 ## Project Overview
This project builds presentation decks for Marp, supporting multiple courses: 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 ## Development Workflow
### Build Commands ### Build Commands
Unified per-course pattern: `make <target>-<course>`. Group targets without suffix run for all courses. Single dev server serves all courses.
```bash ```bash
# Development # Dev (all courses, single port)
make dev # Start single dev server on port 3000 make dev # Live server (HMR), port 1312
npm run dev # Alternative command for development server
# Build # Per-course build/deploy (replace <c> with: 223015b, 223015c, dhbw)
make build # Build all courses (HTML + PDF) make build-<c> # Build HTML + PDF
make build-b # Build 223015b only make html-<c> # HTML only
make build-c # Build 223015c only make pdf-<c> # PDF only
make html # HTML only builds make klausur-<c> # Extract klausur slides (HdM only)
make pdf # PDF only builds make deploy-<c> # Build + deploy single course (ASK FIRST!)
# Klausur Folien # All courses
make klausur # Extract klausurfolien for all courses make build # Build everything
make klausur-b # Extract klausurfolien for 223015b make html / pdf # HTML / PDF only
make klausur-c # Extract klausurfolien for 223015c make klausur # Extract klausur (HdM courses only)
make deploy # Deploy everything (ASK FIRST!)
# Deployment
make deploy # Deploy all courses (requires explicit permission)
make deploy-b # Deploy 223015b only
make deploy-c # Deploy 223015c only
# Utilities # Utilities
make qr URL=... # Generate QR code make qr URL=... # Generate QR code
make optimize-images COURSE=223015b # Resize images make qr-slides COURSE=<c> # QR for course URL
make clean # Remove generated files 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 ### Testing
No specific test framework is used. To validate changes:
No formal test framework. To validate changes:
1. Start dev server: `make dev` 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 3. Verify slides render correctly
4. Run `make build` to ensure no build errors 4. Run `make build` to ensure no build errors
5. Check generated files in `build/` directory 5. Check generated files in `build/` directory
@@ -50,7 +61,18 @@ No specific test framework is used. To validate changes:
## Code Style Guidelines ## Code Style Guidelines
### File Structure ### 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/` - Assets in `slides/<course>/assets/`
- Always reference images as `./assets/filename.png` - Always reference images as `./assets/filename.png`
- Scripts in `scripts/` - Scripts in `scripts/`
@@ -58,20 +80,22 @@ No specific test framework is used. To validate changes:
- Generated output in `build/` (gitignored) - Generated output in `build/` (gitignored)
### Naming Conventions ### 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` - Images: `snake_case.jpg` or `kebab-case.jpg`
- Klausur files: `klausurfolien.md` (auto-generated) - Klausur files: `klausurfolien.md` / `klausurfragen.md` (auto-generated, HdM only)
- Function names in scripts: `snake_case` - Function/variable names in scripts: `snake_case`
- Variable names in scripts: `snake_case`
### Markdown Style ### Markdown Style
- Use ATX-style headers (`# ## ###`) - Use ATX-style headers (`# ## ###`)
- YAML frontmatter for slide metadata at top of each file - YAML frontmatter for slide metadata at top of each file
- Never include a final `---` (creates empty slide) - 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` - Use relative paths for assets: `./assets/image.png`
### Script Style ### Script Style
- Use `#!/usr/bin/env bash` shebang - Use `#!/usr/bin/env bash` shebang
- Use `set -e` for error handling - Use `set -e` for error handling
- Use `2>/dev/null || true` for optional operations - 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. - Use colors for terminal output: `\033[0;32m` etc.
### Git Workflow ### Git Workflow
- Commit messages: ALWAYS lowercase - Commit messages: ALWAYS lowercase
- NEVER add co-authoring lines or generated footers - NEVER add co-authoring lines or generated footers
- Follow semantic naming: "add-...", "fix-...", "update-..." - Follow semantic naming: "add-...", "fix-...", "update-..."
@@ -87,111 +112,113 @@ No specific test framework is used. To validate changes:
## Agent Restrictions ## Agent Restrictions
### Security ### 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 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 ### File Protection
Slide files in `slides/*/*.md` are main content files: Slide files in `slides/*/*.md` are main content files:
- **ALLOWED**: Adding slides, adjusting content, fixing typos, enhancing sections - **ALLOWED**: Adding slides, adjusting content, fixing typos, enhancing sections
- **FORBIDDEN** (without permission): Deleting slides, removing sections, bulk deletions - **FORBIDDEN** (without permission): Deleting slides, removing sections, bulk deletions
- Before ANY deletion: ALWAYS ask user for confirmation - Before ANY deletion: ALWAYS ask user for confirmation
### Klausur Handling ### Klausur Handling (HdM only)
- Klausur files (`klausurfolien.md`) are auto-generated
- NEVER edit klausurfolien.md files directly - Klausur files (`klausurfolien.md`, `klausurfragen.md`) are auto-generated
- To update klausurfolien: edit source slides with `<!-- _class: klausur -->` markers - NEVER edit klausur files directly
- Run `make klausur` to regenerate - 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 ## Development Patterns
### Adding New Slides ### 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 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` 4. Test with `make dev`
### Modifying Existing Slides ### Modifying Existing Slides
1. Edit the appropriate markdown file in `slides/<course>/` 1. Edit the appropriate markdown file in `slides/<course>/`
2. Maintain consistent styling with course theme 2. Maintain consistent styling with course theme
3. Preserve image paths as `./assets/...` 3. Preserve image paths as `./assets/...`
4. Test changes with dev server 4. Test changes with dev server
### Working with Assets ### Working with Assets
1. Place images in `slides/<course>/assets/` 1. Place images in `slides/<course>/assets/`
2. Use descriptive names: `diagram-network.jpg`, `example-code.png` 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` 4. Reference as `./assets/filename.ext`
### Course-Specific Configuration ### Course-Specific Configuration
Each course has specific settings in Makefile:
- Course name and title Each course has these per-course settings in `Makefile`:
- Kapitel list (slide files) - `<c>_NAME` – Display name
- Deploy path - `<c>_KAPITEL` – Ordered list of slide file stems (without `.md`)
- Theme colors (in generate-index.sh) - `<c>_DEPLOY` – Remote deploy path
- `<c>_KLAUSUR` – `1` to enable klausur extraction, empty to disable
## Common Tasks ## Common Tasks
### Debugging Build Issues ### 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/` 3. Check file permissions: `ls -la slides/`
4. Validate markdown syntax with dev server 4. Validate markdown via dev server
### Updating Course Structure ### Updating Course Structure
1. Update `_KAPITEL` variables in Makefile
1. Update `<c>_KAPITEL` in `Makefile`
2. Ensure slide files follow naming convention 2. Ensure slide files follow naming convention
3. Update course-specific themes if needed 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 ### Working with Themes
- Custom theme in `themes/custom-theme.css` - 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 - Use consistent color schemes per course
- Test theme changes across all slides - Test theme changes across all slides
## Deployment Process ## Deployment Process
Deployment to production server requires explicit permission: Deployment to production server requires explicit permission:
1. Build process: `make build` (HTML + PDF) 1. Build: `make build` (HTML + PDF) or per-course `make build-<c>`
2. Index generation: automatically handled 2. Index generation: handled by `scripts/generate-index.sh` (per course) and `scripts/generate-root-index.sh` (root)
3. Deploy to remote server via SCP 3. Deploy: `scp` to `tengo@tuttle.uberspace.de` via `make deploy-<c>` or `make deploy`
4. Root index deployment 4. Root index deployed by `make deploy-index` (or as part of `make deploy`)
**IMPORTANT**: Never run deployment commands without explicit user permission. **IMPORTANT**: Never run deployment commands without explicit user permission.
## Tools and Dependencies ## Tools and Dependencies
### Core Dependencies ### Core
- Marp CLI for slide rendering - Marp CLI for slide rendering (via `npx @marp-team/marp-cli`)
- Bash scripts for automation - Bash scripts for automation (`scripts/`)
- Make for build orchestration - Make for build orchestration
- Git for version control - Git for version control
### Optional Tools ### Optional
- qrencode for QR generation (via nix) - `qrencode` for QR generation (via nix-shell)
- ImageMagick for image optimization - ImageMagick for image optimization (via nix-shell)
- 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)
## Troubleshooting ## Troubleshooting
### Common Issues ### Common Issues
- **Port conflicts**: Use `make dev-kill` to clean up processes - **Port conflicts**: kill the dev-server process holding port 1312
- **Build failures**: Check file permissions and Marp CLI installation - **Build failures**: check file permissions and Marp CLI availability via `npx`
- **Asset loading**: Verify relative paths and file existence - **Asset loading**: verify relative paths and file existence in `slides/<c>/assets/`
- **Deploy issues**: Check SSH keys and remote permissions - **Deploy issues**: check SSH keys for `tengo@tuttle.uberspace.de` and remote permissions
### Getting Help ### Getting Help
1. Check this AGENTS.md file first 1. Check this `AGENTS.md` first
2. Review Makefile targets and scripts 2. Review `Makefile` targets and `scripts/`
3. Test changes incrementally 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 ## Courses
- **223015b** - Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur) - **223015b** - Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur) — Fokus: **Dateien und Inhalte**
- **223015c** - Internettechnologien (HdM, 3 Kapitel + Klausur) - **223015c** - Internettechnologien (HdM, 3 Kapitel + Klausur) — Fokus: **Internet und Web**
- **dhbw** - Technik I – Grundlagen IT (DHBW, 8 Kapitel) - **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 Restrictions
- Agent NEVER runs commands outside this folder - 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 ## Courses
| Code | Title | Origin | | Code | Title | Origin | Fokus |
|------|-------|--------| |------|-------|--------|-------|
| 223015b | Dateiformate, Schnittstellen, Speichermedien | HdM | | 223015b | Dateiformate, Schnittstellen, Speichermedien | HdM | **Dateien und Inhalte** |
| 223015c | Internettechnologien | HdM | | 223015c | Internettechnologien | HdM | **Internet und Web** |
| dhbw | Technik I – Grundlagen IT | DHBW | | 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 ## Project Structure