AGENTS.md

1# AGENTS.md
2 
3## Projektübersicht
4 
5Dies ist ein Bildungs-Curriculum-Repository zum Erlernen der Grundlagen der Webentwicklung für Einsteiger. Das Curriculum ist ein umfassender 12-Wochen-Kurs, der von Microsoft Cloud Advocates entwickelt wurde und 24 praxisorientierte Lektionen zu JavaScript, CSS und HTML enthält.
6 
7### Hauptkomponenten
8 
9- **Bildungsinhalte**: 24 strukturierte Lektionen, organisiert in projektbasierten Modulen
10- **Praktische Projekte**: Terrarium, Tipp-Spiel, Browser-Erweiterung, Weltraumspiel, Banking-App, Code-Editor und KI-Chat-Assistent
11- **Interaktive Quizze**: 48 Quizze mit jeweils 3 Fragen (Vor-/Nach-Lektion Bewertungen)
12- **Mehrsprachige Unterstützung**: Automatisierte Übersetzungen für über 50 Sprachen via GitHub Actions
13- **Technologien**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (für KI-Projekte)
14 
15### Architektur
16 
17- Bildungs-Repository mit lektionenbasierter Struktur
18- Jeder Lektionenordner enthält README, Codebeispiele und Lösungen
19- Eigenständige Projekte in separaten Verzeichnissen (quiz-app, verschiedene Lektionenprojekte)
20- Übersetzungssystem unter Verwendung von GitHub Actions (co-op-translator)
21- Dokumentation bereitgestellt über Docsify und als PDF verfügbar
22 
23## Setup-Befehle
24 
25Dieses Repository dient hauptsächlich dem Konsum von Bildungsinhalten. Für die Arbeit mit spezifischen Projekten:
26 
27### Haupt-Repository-Setup
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz-App Setup (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Entwicklungsserver starten
40npm run build      # Für die Produktion erstellen
41npm run lint       # ESLint ausführen
42```
43 
44### Bank-Projekt API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # API-Server starten
50npm run lint       # ESLint ausführen
51npm run format     # Mit Prettier formatieren
52```
53 
54### Browser-Erweiterungsprojekte
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Folgen Sie den browserspezifischen Anweisungen zum Laden der Erweiterung
60```
61 
62### Weltraumspiel-Projekte
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Öffne index.html im Browser oder verwende Live Server
68```
69 
70### Chat-Projekt (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Setze die Umgebungsvariable GITHUB_TOKEN
76python api.py
77```
78 
79## Entwicklungs-Workflow
80 
81### Für Inhaltsanbieter
82 
831. **Forke das Repository** in dein GitHub-Konto
842. **Klon deinen Fork** lokal
853. **Erstelle einen neuen Branch** für deine Änderungen
864. Ändere Inhalte der Lektionen oder Codebeispiele
875. Teste Codeänderungen in den entsprechenden Projektverzeichnissen
886. Reiche Pull Requests gemäß den Beitragsrichtlinien ein
89 
90### Für Lernende
91 
921. Forke oder klone das Repository
932. Navigiere nacheinander zu Lektionen-Verzeichnissen
943. Lies README-Dateien jeder Lektion
954. Absolviere Pre-Lesson-Quizze unter https://ff-quizzes.netlify.app/web/
965. Arbeite die Codebeispiele in den Lektionenordnern durch
976. Bearbeite Aufgaben und Herausforderungen
987. Mache Post-Lesson-Quizze
99 
100### Live-Entwicklung
101 
102- **Dokumentation**: Führe `docsify serve` im Root-Verzeichnis aus (Port 3000)
103- **Quiz-App**: Führe `npm run dev` im Verzeichnis quiz-app aus
104- **Projekte**: Nutze VS Code Live Server Erweiterung für HTML-Projekte
105- **API-Projekte**: Führe `npm start` in den jeweiligen API-Verzeichnissen aus
106 
107## Testanweisungen
108 
109### Quiz-App-Tests
110 
111```bash
112cd quiz-app
113npm run lint       # Überprüfen Sie auf Code-Stil-Probleme
114npm run build      # Überprüfen Sie, ob der Build erfolgreich ist
115```
116 
117### Bank API-Tests
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Überprüfen Sie auf Probleme mit dem Code-Stil
122node server.js     # Überprüfen Sie, ob der Server ohne Fehler startet
123```
124 
125### Allgemeiner Testansatz
126 
127- Dies ist ein Bildungs-Repository ohne umfassende automatisierte Tests
128- Manuelles Testen konzentriert sich auf:
129  - Codebeispiele laufen fehlerfrei
130  - Links in der Dokumentation funktionieren korrekt
131  - Projekte bauen fehlerfrei
132  - Beispiele folgen Best Practices
133 
134### Vorab-Checks vor Pull Requests
135 
136- Führe `npm run lint` in Verzeichnissen mit package.json aus
137- Überprüfe ob Markdown-Links gültig sind
138- Teste Codebeispiele im Browser oder Node.js
139- Prüfe, dass Übersetzungen die richtige Struktur behalten
140 
141## Code Style Richtlinien
142 
143### JavaScript
144 
145- Verwende moderne ES6+ Syntax
146- Folge den standardmäßigen ESLint-Konfigurationen der Projekte
147- Verwende aussagekräftige Variablen- und Funktionsnamen für Bildungszwecke
148- Füge erklärende Kommentare für Lernende hinzu
149- Formatiere mit Prettier, wenn konfiguriert
150 
151### HTML/CSS
152 
153- Semantische HTML5-Elemente
154- Responsive Design Prinzipien
155- Klare Klassennamen-Konventionen
156- Kommentare, die CSS-Techniken für Lernende erklären
157 
158### Python
159 
160- PEP 8 Stilrichtlinien
161- Klare, bildungsorientierte Codebeispiele
162- Type Hints wo hilfreich zum Lernen
163 
164### Markdown-Dokumentation
165 
166- Klare Überschriftenhierarchie
167- Codeblöcke mit Sprachangabe
168- Links zu weiterführenden Ressourcen
169- Screenshots und Bilder in `images/` Verzeichnissen
170- Alt-Text für Bilder für Barrierefreiheit
171 
172### Dateiorganisation
173 
174- Lektionen nummeriert (1-getting-started-lessons, 2-js-basics, etc.)
175- Jedes Projekt hat `solution/` und oft `start/` oder `your-work/` Verzeichnisse
176- Bilder in lektionenspezifischen `images/` Ordnern
177- Übersetzungen in `translations/{language-code}/` Struktur
178 
179## Build und Deployment
180 
181### Quiz-App Deployment (Azure Static Web Apps)
182 
183Die quiz-app ist für Azure Static Web Apps Deployment konfiguriert:
184 
185```bash
186cd quiz-app
187npm run build      # Erstellt den Ordner dist/
188# Führt Bereitstellung über GitHub Actions Workflow bei Push auf main durch
189```
190 
191Azure Static Web Apps Konfiguration:
192- **App Location**: `/quiz-app`
193- **Output Location**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generierung der PDF-Dokumentation
197 
198```bash
199npm install                    # Installiere docsify-to-pdf
200npm run convert               # Erzeuge PDF aus Docs
201```
202 
203### Docsify Dokumentation
204 
205```bash
206npm install -g docsify-cli    # Installiere Docsify global
207docsify serve                 # Auf localhost:3000 bereitstellen
208```
209 
210### Projektspezifische Builds
211 
212Jedes Projektverzeichnis kann einen eigenen Build-Prozess besitzen:
213- Vue-Projekte: `npm run build` erstellt Produktions-Bundles
214- Statische Projekte: Kein Build-Schritt, Dateien werden direkt ausgeliefert
215 
216## Pull Request Richtlinien
217 
218### Titel-Format
219 
220Verwende klare, beschreibende Titel, die den Änderungsbereich angeben:
221- `[Quiz-app] Neues Quiz für Lektion X hinzufügen`
222- `[Lesson-3] Rechtschreibfehler im Terrarium-Projekt korrigieren`
223- `[Translation] Spanische Übersetzung für Lektion 5 hinzufügen`
224- `[Docs] Setup-Anweisungen aktualisieren`
225 
226### Erforderliche Checks
227 
228Vor dem Einreichen eines PR:
229 
2301. **Codequalität**:
231   - Führe `npm run lint` in betroffenen Projektverzeichnissen aus
232   - Behebe alle Linting-Fehler und Warnungen
233 
2342. **Build-Verifikation**:
235   - Führe `npm run build` falls zutreffend aus
236   - Stelle sicher, dass keine Build-Fehler auftreten
237 
2383. **Link-Validierung**:
239   - Teste alle Markdown-Links
240   - Überprüfe Bildreferenzen
241 
2424. **Inhaltsüberprüfung**:
243   - Lektorat auf Rechtschreibung und Grammatik
244   - Stelle sicher, dass Codebeispiele korrekt und didaktisch sind
245   - Prüfe, dass Übersetzungen den Originalinhalt richtig wiedergeben
246 
247### Beitragspflichten
248 
249- D Zustimmung zur Microsoft CLA (automatische Prüfung beim ersten PR)
250- Folge dem [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Siehe [CONTRIBUTING.md](./CONTRIBUTING.md) für detaillierte Richtlinien
252- Verweise Issue-Nummern im PR-Beschreibung, falls zutreffend
253 
254### Review-Prozess
255 
256- PRs werden von Maintainer:innen und Community geprüft
257- Bildnerische Klarheit hat Priorität
258- Codebeispiele sollen aktuellen Best Practices folgen
259- Übersetzungen werden auf Genauigkeit und kulturelle Angemessenheit geprüft
260 
261## Übersetzungssystem
262 
263### Automatische Übersetzung
264 
265- Nutzt GitHub Actions mit co-op-translator Workflow
266- Übersetzt automatisch in über 50 Sprachen
267- Quelldateien in Hauptverzeichnissen
268- Übersetzte Dateien in `translations/{language-code}/`
269 
270### Manuelle Verbesserungen der Übersetzung hinzufügen
271 
2721. Finde Datei in `translations/{language-code}/`
2732. Nimm Verbesserungen vor, Struktur soll erhalten bleiben
2743. Sicherstellen, dass Codebeispiele funktionsfähig bleiben
2754. Teste ggf. Quiz-Inhalte in Lokalisation
276 
277### Übersetzungs-Metadaten
278 
279Übersetzte Dateien enthalten Meta-Daten-Header:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debugging und Fehlerbehebung
293 
294### Häufige Probleme
295 
296**Quiz-App startet nicht**:
297- Prüfe Node.js-Version (v14+ empfohlen)
298- Lösche `node_modules` und `package-lock.json`, führe `npm install` erneut aus
299- Prüfe Port-Konflikte (standardmäßig Vite Port 5173)
300 
301**API-Server startet nicht**:
302- Stelle sicher, dass Node.js Version >=10 ist
303- Prüfe, ob Port bereits belegt ist
304- Stelle sicher, dass alle Abhängigkeiten mit `npm install` installiert sind
305 
306**Browser-Erweiterung lädt nicht**:
307- Prüfe, ob manifest.json korrekt formatiert ist
308- Schau in die Browser-Konsole auf Fehler
309- Folge browserspezifischen Installationsanweisungen
310 
311**Probleme mit Python Chat-Projekt**:
312- Stelle sicher, dass OpenAI-Paket installiert ist: `pip install openai`
313- Prüfe, ob Umgebungsvariable GITHUB_TOKEN gesetzt ist
314- Prüfe GitHub Models-Zugriffsrechte
315 
316**Docsify liefert keine Dokumentation aus**:
317- Installiere docsify-cli global: `npm install -g docsify-cli`
318- Starte im Root-Verzeichnis des Repos
319- Stelle sicher, dass `docs/_sidebar.md` existiert
320 
321### Tipps zur Entwicklungsumgebung
322 
323- Verwende VS Code mit Live Server-Erweiterung für HTML-Projekte
324- Installiere ESLint und Prettier Erweiterungen für konsistente Formatierung
325- Nutze Browser DevTools zum Debuggen von JavaScript
326- Für Vue-Projekte: Installiere Vue DevTools Browser Erweiterung
327 
328### Performance-Überlegungen
329 
330- Große Anzahl übersetzter Dateien (50+ Sprachen) führt zu großen Vollklonen
331- Verwende flachen Klon wenn nur Inhalt bearbeitet wird: `git clone --depth 1`
332- Schließe Übersetzungen von Suchvorgängen aus, wenn du an englischen Inhalten arbeitest
333- Build-Prozesse können beim ersten Lauf langsam sein (npm install, Vite Build)
334 
335## Sicherheitsüberlegungen
336 
337### Umgebungsvariablen
338 
339- API-Schlüssel dürfen niemals im Repository hinterlegt werden
340- Verwende `.env`-Dateien (schon in `.gitignore` enthalten)
341- Dokumentiere benötigte Umgebungsvariablen in Projekt-READMEs
342 
343### Python-Projekte
344 
345- Nutze virtuelle Umgebungen: `python -m venv venv`
346- Halte Abhängigkeiten aktuell
347- GitHub-Tokens sollten minimale erforderliche Berechtigungen haben
348 
349### GitHub Models Zugriff
350 
351- Personal Access Tokens (PAT) sind für GitHub Models erforderlich
352- Tokens sollten als Umgebungsvariablen gespeichert werden
353- Tokens oder Zugangsdaten niemals committen
354 
355## Zusätzliche Hinweise
356 
357### Zielgruppe
358 
359- Absolute Anfänger in der Webentwicklung
360- Studierende und autodidaktische Lernende
361- Lehrkräfte, die das Curriculum im Unterricht verwenden
362- Inhalte sind auf Barrierefreiheit und schrittweise Kompetenzentwicklung ausgelegt
363 
364### Pädagogische Philosophie
365 
366- Projektbasiertes Lernen
367- Regelmäßige Wissensüberprüfungen (Quizze)
368- Praxisorientierte Coding-Übungen
369- Beispiele aus der realen Welt
370- Fokus auf Grundlagen vor Frameworks
371 
372### Repository-Wartung
373 
374- Aktive Community aus Lernenden und Beitragenden
375- Regelmäßige Updates von Abhängigkeiten und Inhalten
376- Probleme und Diskussionen werden von Maintainer:innen überwacht
377- Übersetzungsupdates automatisiert via GitHub Actions
378 
379### Verwandte Ressourcen
380 
381- [Microsoft Learn Module](https://docs.microsoft.com/learn/)
382- [Student Hub Ressourcen](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) empfohlen für Lernende
384- Zusätzliche Kurse: Generative KI, Data Science, ML, IoT Curricula verfügbar
385 
386### Arbeit mit spezifischen Projekten
387 
388Für detaillierte Anweisungen zu einzelnen Projekten siehe README-Dateien in:
389- `quiz-app/README.md` - Vue 3 Quiz-Anwendung
390- `7-bank-project/README.md` - Banking-Anwendung mit Authentifizierung
391- `5-browser-extension/README.md` - Browser-Erweiterungsentwicklung
392- `6-space-game/README.md` - Canvas-basiertes Spiel
393- `9-chat-project/README.md` - KI-Chat-Assistent Projekt
394 
395### Monorepo-Struktur
396 
397Obgleich kein klassisches Monorepo, enthält dieses Repository mehrere unabhängige Projekte:
398- Jede Lektion ist autark
399- Projekte teilen keine Abhängigkeiten
400- Arbeit an einzelnen Projekten ohne Einfluss auf andere
401- Gesamtes Repo klonen für das komplette Curriculum-Erlebnis
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Haftungsausschluss**:  
407Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir Genauigkeit anstreben, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Für kritische Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die durch die Verwendung dieser Übersetzung entstehen.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->