docs/00_General/00_documentation_map.md

@@ -58,6 +58,7 @@ Das Repository ist in **logische Domänen** unterteilt.
 | Datei | Inhalt & Zweck |
 | :--- | :--- |
 | `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
+| `05_genai_best_practices.md` | **AI Workflow.** Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs. |
 
 ### 📂 06_Roadmap & 99_Archive
 *Zielgruppe: Projektleitung*

docs/05_Development/05_genai_best_practices.md

@@ -0,0 +1,152 @@
+---
+doc_type: developer_guide
+audience: developer, architect
+scope: genai, prompting, workflow
+status: active
+version: 1.0
+context: "Leitfaden für die effiziente Softwareentwicklung mit LLMs im Mindnet-Projekt."
+---
+
+# GenAI Development Best Practices & Prompt Library
+
+Dieser Leitfaden definiert Standards für die Zusammenarbeit mit KI-Modellen (ChatGPT, Claude, Gemini) im Rahmen der Mindnet-Entwicklung. Ziel ist es, Halluzinationen zu minimieren, den Kontext effizient zu nutzen und die Dokumentation synchron zum Code zu halten.
+
+---
+
+## 1. Grundprinzipien
+
+### 1.1 Context is King (aber teuer)
+LLMs haben ein begrenztes Kontext-Fenster.
+* **Don't:** "Hier ist mein ganzer Code, fix den Bug." (Führt zu Vergessen von Details).
+* **Do:** Nutze die **"Map & Fetch" Strategie**:
+    1.  Gib der KI eine Inhaltsübersicht (z.B. `project_scan_report.json` oder `tree`).
+    2.  Lass die KI entscheiden, welche Dateien sie für die Aufgabe benötigt.
+    3.  Lade nur diese Dateien hoch.
+
+### 1.2 Trust but Verify (Validierung)
+* **Code:** Führe generierten Code **immer** lokal aus (Unit Tests oder Smoke Tests), bevor du ihn committest.
+* **Pfade:** KIs erfinden gerne Pfade (z.B. `app/utils.py`, obwohl es `app/core/utils.py` ist). Prüfe Importe immer gegen die Projektstruktur.
+* **Security:** Achte darauf, dass keine Secrets (API-Keys) in den Prompts landen und keine Secrets vom LLM halluziniert und hardcodiert werden.
+
+### 1.3 Atomic Chats
+Nutze für verschiedene Aufgaben frische Chat-Kontexte.
+* Ein Chat für "Frontend Refactoring".
+* Ein neuer Chat für "Documentation Update".
+* *Grund:* Alte Chats akkumulieren "Rauschen" und führen zu Fehlern.
+
+---
+
+## 2. Prompt Library (Standard-Vorlagen)
+
+Nutze diese Prompts, um konsistente Ergebnisse zu erzielen.
+
+### 2.1 Der "Render-Safe" Prompt (System Instruction)
+**Wann nutzen?** Immer am Anfang eines Chats, wenn die KI Markdown-Dateien oder Code generieren soll.
+**Zweck:** Verhindert, dass die Antwort im Chat-Fenster abbricht, weil die KI Code-Blöcke falsch verschachtelt.
+
+```text
+# SYSTEM-ANWEISUNG: SICHERES MARKDOWN-RENDERING
+
+Du agierst als technischer Assistent. Deine Aufgabe ist das Erstellen von Markdown-Dateien, die oft selbst Code-Blöcke enthalten.
+
+**DAS PROBLEM:**
+Wenn du eine Markdown-Datei generierst, die Code-Blöcke (```) enthält, und diese Ausgabe selbst in einen Code-Block packst, interpretiert das Chat-Interface das erste innere ``` oft fälschlicherweise als das Ende der Ausgabe.
+
+**DIE REGEL (STRIKT BEFOLGEN):**
+Um eine ununterbrochene Darstellung zu garantieren, musst du zwingend eine der folgenden Kapselungs-Methoden anwenden:
+
+### Methode A: Die 4-Backtick-Methode (Bevorzugt)
+Umschließe den **gesamten** Datei-Inhalt mit **4 Backticks** (````).
+Dies erlaubt dir, innerhalb der Datei normale 3 Backticks zu verwenden.
+
+### Methode B: Die 4-Space-Einrückung (Alternative)
+Wenn du außen 3 Backticks verwendest, darfst du im Inneren **KEINE** Backticks verwenden.
+Stattdessen müssen alle inneren Code-Beispiele mit **4 Leerzeichen (Spaces)** eingerückt werden.
+
+**ZUSAMMENFASSUNG:**
+Generiere niemals verschachtelte 3-Backtick-Blöcke innerhalb von 3-Backtick-Blöcken.
+```
+
+---
+
+### 2.2 Der "Doku-Update" Prompt (Nach WP-Abschluss)
+**Wann nutzen?** Wenn ein Feature fertig codiert ist und die Doku (`docs/`) nachgezogen werden muss.
+**Zweck:** Automatische Identifikation der betroffenen Doku-Dateien ohne manuelles Suchen.
+
+**Vorbedingung:** Lade `docs/00_General/00_documentation_map.md` und `docs/06_Roadmap/06_active_roadmap.md` hoch.
+
+```text
+Du agierst als **Technical Documentation Lead**.
+
+**Kontext:**
+Wir haben soeben ein Workpackage (WP) abgeschlossen. Der Code ist implementiert.
+Jetzt müssen wir die Systemdokumentation (Mindnet v2.6 Modular Docs) aktualisieren.
+
+**Deine Aufgabe - Phase 1: Identifikation**
+Analysiere die durchgeführten Änderungen dieses Workpackages (aus dem Chat-Verlauf).
+Nutze die beiliegende `00_documentation_map.md`, um zu identifizieren, welche Dokumentations-Module betroffen sind.
+
+**Mapping-Logik:**
+* Neue Features? -> `00_glossary.md`, `02_Concepts/*`
+* DB/Payloads geändert? -> `03_tech_data_model.md`
+* Import/Algorithmus geändert? -> `03_tech_ingestion_pipeline.md`, `03_tech_retrieval_scoring.md`
+* Neue Configs? -> `03_tech_configuration.md`, `04_admin_operations.md`
+* UI/UX geändert? -> `01_User_Manual/*`, `03_tech_frontend.md`
+
+**Output für Phase 1:**
+Erstelle eine **Liste der betroffenen Dateien** mit Begründung.
+Fordere mich explizit auf, dir diese Dateien hochzuladen.
+
+---
+
+**Deine Aufgabe - Phase 2: Sequenzielle Bearbeitung**
+Sobald ich die Dateien hochgeladen habe:
+1.  Nimm dir **eine** Datei aus der Liste vor.
+2.  Schreibe den kompletten, aktualisierten Inhalt (Markdown).
+    * *Wichtig:* Halte dich an den bestehenden Stil und die "Render-Safe"-Regel (4 Backticks).
+3.  **Warte** nach der Ausgabe auf mein "OK", bevor du die nächste Datei bearbeitest.
+
+**Bist du bereit für die Analyse?**
+```
+
+---
+
+### 2.3 Der "Code Architect" Prompt (Refactoring & Analyse)
+**Wann nutzen?** Wenn du dich in den Code einarbeiten willst oder Aufräumen musst.
+**Vorbedingung:** Führe lokal `deep_scan.py` aus und lade `project_scan_report.json` hoch.
+
+```text
+Du agierst als **Senior Software Architect**.
+
+**INPUT:**
+Ich habe dir die Datei `project_scan_report.json` hochgeladen. Sie enthält eine Liste aller Dateien und ihrer Import-Beziehungen.
+
+**DIE SOLL-STRUKTUR (4 SÄULEN):**
+Jede Datei muss einem dieser Zweige zugeordnet werden können:
+1.  **Backend:** via `app/main.py`
+2.  **Frontend:** via `app/frontend/ui.py`
+3.  **Batch/Ops:** via `scripts/` (Produktions-Tools)
+4.  **Tests:** via `tests/`
+
+**DEINE AUFGABE:**
+Analysiere das JSON. Identifiziere "Zombies" (Dateien, die nirgends importiert werden und keinen klaren Entrypoint haben).
+Erstelle eine:
+1.  **Modul-Tabelle** (Wer ruft wen auf?).
+2.  **Lösch-Vorschlagsliste** (Dead Code).
+```
+
+---
+
+## 3. Workflow für ein Workpackage (WP)
+
+Ein typisches Mindnet-Feature wird so entwickelt:
+
+1.  **Start:** Neuer Chat. Prompt **2.1 (Render-Safe)** eingeben.
+2.  **Kontext:** `project_scan_report.json` oder relevante Core-Dateien hochladen.
+3.  **Code:** Feature implementieren (Iterativ).
+4.  **Test:** Code lokal validieren.
+5.  **Doku:**
+    * Neuer Chat (optional, für sauberen Kontext).
+    * Prompt **2.1** + Prompt **2.2 (Doku-Update)** eingeben.
+    * Doku aktualisieren lassen.
+6.  **Commit:** Code + Doku zusammen pushen.