Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
003a270548
mindnet/docs/05_Development/05_genai_best_practices.md
Lars 4204c2c974 neue docs
2025-12-15 17:32:38 +01:00

6.3 KiB
Raw Blame History

doc_type audience scope status version context
developer_guide developer, architect genai, prompting, workflow active 1.0 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.

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

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.

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.