neue docs
This commit is contained in:
parent
9372cfb8ca
commit
4204c2c974
|
|
@ -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*
|
||||
|
|
|
|||
152
docs/05_Development/05_genai_best_practices.md
Normal file
152
docs/05_Development/05_genai_best_practices.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user