---
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.