152 lines
6.3 KiB
Markdown
152 lines
6.3 KiB
Markdown
---
|
|
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. |