From 4204c2c9742a45a06e6ecf0f3ba68af416851abc Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 15 Dec 2025 17:32:38 +0100 Subject: [PATCH] neue docs --- docs/00_General/00_documentation_map.md | 1 + .../05_Development/05_genai_best_practices.md | 152 ++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 docs/05_Development/05_genai_best_practices.md diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md index 1a443b9..f575fd6 100644 --- a/docs/00_General/00_documentation_map.md +++ b/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* diff --git a/docs/05_Development/05_genai_best_practices.md b/docs/05_Development/05_genai_best_practices.md new file mode 100644 index 0000000..86df623 --- /dev/null +++ b/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. \ No newline at end of file