mitai-jinkendo/.claude/docs/functional/AI_PROMPTS.md

Fachliche Anforderungen: KI-Prompt Flexibilisierung

Modul: v9f
Status: Fachlich freigegeben, technische Implementierung ausstehend
Letzte Aktualisierung: März 2026

---

1. Überblick

Das bestehende KI-Prompt-System wird von einer fixen Sammlung vordefinierter Prompts zu einer vollständig konfigurierbaren Prompt-Bibliothek erweitert. Admins können Prompts kategorisieren, duplizieren, bearbeiten und mit einem visuellen Platzhalter-Browser ausstatten. Die Pipeline wird konfigurierbar – mehrere Konfigurationen für unterschiedliche Analysezwecke sind möglich.

---

2. Prompt-Bibliothek

2.1 Kategorien

Alle Prompts werden einer Kategorie zugeordnet:

Kategorie	Beschreibung	Beispiel-Prompts
Körper	Gewicht, KF, Umfänge, Caliper	Körperkomposition, Gewichtstrend
Ernährung	Kalorien, Makros, Timing	Kalorienbilanz, Proteinversorgung
Training	Volumen, Typen, HF	Trainingsanalyse, Erholungsstatus
Schlaf	Qualität, Dauer, Muster	Schlafauswertung, Schlaftrend
Vitalwerte	Ruhepuls, HRV, VO2Max	Leistungsfähigkeit, Erholung
Mentales	Stress, Stimmung, Energie	Wohlbefinden, Stressanalyse
Ziele	Fortschritt, Prognose, Zeitplan	Zielerreichung, Zeitplanung
Ganzheitlich	Korrelationen, Übersicht	Gesamtanalyse, Pipeline-Synthese

2.2 Prompt-Verwaltung (Admin)

Ein Admin kann mit jedem Prompt folgendes tun:

Aktivieren / Deaktivieren

• Inaktive Prompts sind für Nutzer nicht sichtbar und nicht ausführbar
• Pipeline-Prompts können separat aktiviert/deaktiviert werden

Duplizieren und anpassen

• Bestehenden Prompt als Vorlage kopieren
• Kopie erhält Suffix " (Kopie)" und kann unabhängig bearbeitet werden

Neu erstellen

• Titel, Beschreibung, Kategorie, Template
• Platzhalter über den Platzhalter-Browser einfügen (siehe Abschnitt 3)

Kategorie zuordnen

• Beim Erstellen und Bearbeiten wählbar
• Nachträgliche Änderung möglich

Reihenfolge festlegen

• Drag & Drop oder Zahleneingabe (sort_order)
• Reihenfolge bestimmt Anzeige in der Nutzer-Ansicht

Auf Standard zurücksetzen

• Systemseitig definierte Prompts haben einen "Standard"-Zustand
• Reset stellt Original-Template wieder her
• Eigens erstellte Prompts haben keinen Standard-Reset

2.3 Prompt-Felder

Jeder Prompt hat:

• Titel – kurzer Name (z.B. "Körperkomposition")
• Beschreibung – wofür ist dieser Prompt? (für Admin sichtbar)
• Kategorie – aus der Kategorienliste
• Template – der eigentliche Prompt-Text mit Platzhaltern
• Aktiv – true/false
• Reihenfolge – Zahl für Sortierung
• Typ – single (Einzelanalyse) oder pipeline (Pipeline-Stufe)
• Pipeline-Stufe – nur bei Typ pipeline: Stufen-Nummer (1, 2, 3...)

---

3. Platzhalter-System

3.1 Platzhalter-Browser

Beim Bearbeiten eines Prompts steht ein visueller Platzhalter-Browser zur Verfügung – Admin tippt Platzhalter nicht mehr manuell, sondern wählt sie aus.

Funktionen:

• Filterung nach Kategorie – zeigt nur Platzhalter der gewählten Kategorie
• Beispielwert – zeigt was der Platzhalter aktuell mit echten Daten ausgeben würde
• Klick zum Einfügen – Platzhalter wird an Cursor-Position ins Template eingefügt
• Warnung bei fehlendem Platzhalter – wenn ein eingetippter Platzhalter nicht existiert
• Warnung bei fehlenden Daten – wenn Daten für diesen Platzhalter nicht vorhanden sind (z.B. noch kein Schlaf-Tracking)

3.2 Prompt-Vorschau

Vor dem Speichern kann der Admin eine Vorschau anfordern:

• System befüllt alle Platzhalter mit echten aktuellen Daten
• Zeigt den fertigen Prompt-Text wie er an die KI gesendet würde
• KI wird dabei nicht aufgerufen – nur der Prompt-Text wird angezeigt

3.3 Platzhalter-Kategorien und Übersicht

Körper:

{{weight_aktuell}}         → "86,1 kg"
{{weight_trend}}           → "sinkend (-0,8 kg letzte 4 Wochen)"
{{kf_aktuell}}             → "19,9%"
{{kf_trend}}               → "stabil"
{{magermasse}}             → "69,4 kg"
{{whr}}                    → "0,90"
{{whtr}}                   → "0,51"
{{bmi}}                    → "27,2"
{{circ_summary}}           → "Taille: 88cm, Hüfte: 98cm, ..."
{{caliper_summary}}        → "KF nach Jackson/Pollock: 19,9%"

Ernährung:

{{kcal_avg}}               → "1.847 kcal/Tag (Ø 30 Tage)"
{{protein_avg}}            → "138g/Tag"
{{protein_ziel_low}}       → "138"
{{protein_ziel_high}}      → "172"
{{fat_avg}}                → "72g/Tag"
{{carb_avg}}               → "195g/Tag"
{{nutrition_summary}}      → kompakte Zusammenfassung
{{nutrition_detail}}       → ausführliche Tabelle
{{nutrition_days}}         → "28 Tage mit Daten"
{{activity_kcal_summary}}  → "Ø 320 kcal aktiver Verbrauch/Tag"

Training:

{{activity_summary}}           → kompakte Zusammenfassung
{{activity_detail}}            → ausführliche Liste
{{trainingstyp_verteilung}}    → "60% Kraft, 30% Cardio, 10% Mobility"
{{trainingstyp_haupttyp}}      → "Kraft" (häufigster Typ)
{{ruhetage_letzte_woche}}      → "2"
{{trainingsphase}}             → "Aufbau / Erholung / Plateau"
{{hf_zonen_verteilung}}        → "Zone 2: 45%, Zone 3: 35%, Zone 4: 20%"

{{faehigkeiten_analyse}}       → Detaillierte Analyse der trainierten Fähigkeiten
{{faehigkeiten_koordinativ}}   → "Orientierung: 3/14 Einheiten, Gleichgewicht: 5/14, ..."
{{faehigkeiten_konditionell}}  → "Kraft: 8/14, Ausdauer: 4/14, Schnelligkeit: 2/14, Flexibilität: 3/14"
{{faehigkeiten_kognitiv}}      → "Konzentration: 2/14, Entscheidung: 1/14, ..."
{{faehigkeiten_psychisch}}     → "Willenskraft: 5/14, Stressresistenz: 2/14, ..."
{{faehigkeiten_taktisch}}      → "Timing: 1/14, Antizipation: 2/14, ..."
{{faehigkeiten_balance}}       → "Ausgewogen / Einseitig + Empfehlung"

Fähigkeiten-System (v9d Integration):

• Jeder Trainingstyp ist mit 1-N Fähigkeiten aus 5 Dimensionen verknüpft
• KI erhält aggregierte Statistik: wie oft wurden welche Fähigkeiten trainiert
• Ermöglicht Aussagen wie: "Dein Training fokussiert stark auf Kraft (8 von 14 Einheiten), aber koordinative Fähigkeiten kommen zu kurz."
• Basis für gezielte Trainingsempfehlungen

Herzfrequenz & Vitalwerte:

{{ruhepuls_aktuell}}       → "52 bpm"
{{ruhepuls_trend}}         → "sinkend (-3 bpm letzte 4 Wochen)"
{{hrv_aktuell}}            → "58 ms"
{{hrv_baseline}}           → "62 ms (30-Tage-Durchschnitt)"
{{erholungsstatus}}        → "gut / teilweise / schlecht"
{{vo2max}}                 → "48,2 ml/kg/min"

Schlaf:

{{schlaf_avg_dauer}}       → "7,2h/Nacht (Ø 7 Tage)"
{{schlaf_qualitaet}}       → "3,8/5 (Ø 7 Tage)"
{{schlaf_trend}}           → "stabil"
{{schlaf_detail}}          → ausführliche Tabelle

Mentales:

{{energie_niveau}}         → "3,2/5 (Ø 7 Tage)"
{{stress_niveau}}          → "2,8/5 (Ø 7 Tage)"
{{stimmung}}               → "3,9/5 (Ø 7 Tage)"
{{meditation_streak}}      → "5 Tage in Folge"

Ziele:

{{goal_weight}}            → "82 kg"
{{goal_bf_pct}}            → "14%"
{{goal_name}}              → "Muskelaufbau"
{{ziel_fortschritt}}       → "Gewicht: 72% erreicht, KF: 45% erreicht"
{{ziel_prognose}}          → "Ziel voraussichtlich in 8 Wochen erreicht"

Profil:

{{name}}                   → "Lars"
{{geschlecht}}             → "männlich"
{{height}}                 → "178"
{{age}}                    → "45"
{{sprache}}                → "Deutsch" (konfigurierbar per Prompt)

Zeitraum:

{{zeitraum_7d}}            → "letzte 7 Tage"
{{zeitraum_30d}}           → "letzte 30 Tage"
{{zeitraum_90d}}           → "letzte 90 Tage"
{{datum_heute}}            → "20. März 2026"

Pipeline (intern):

{{stage1_body}}            → JSON-Summary Körper (Pipeline-Stufe 1)
{{stage1_nutrition}}       → JSON-Summary Ernährung
{{stage1_activity}}        → JSON-Summary Training
{{stage1_sleep}}           → JSON-Summary Schlaf (neu)
{{stage1_vitals}}          → JSON-Summary Vitalwerte (neu)

---

4. Pipeline-Konfiguration

4.1 Was ist eine Pipeline-Konfiguration?

Eine Pipeline-Konfiguration definiert:

• Name – z.B. "Alltags-Check", "Wettkampf-Analyse", "Schlaf-Fokus"
• Aktive Module – welche Datenquellen fließen ein (Körper, Ernährung, Training, Schlaf, Vitalwerte, Mentales)
• Zeitraum je Modul – z.B. Körper 30 Tage, Schlaf 7 Tage, Training 14 Tage
• Stufen – welcher Prompt wird in welcher Stufe verwendet
• Standard – eine Konfiguration kann als Standard markiert werden

4.2 Pipeline-Stufen

Stufe 1 (parallel): Mehrere Module-Prompts laufen gleichzeitig, jeder gibt ein JSON-Summary zurück

Stufe 2: Synthese-Prompt kombiniert alle Stage-1-Summaries zu einer narrativen Analyse

Stufe 3 (optional): Ziel-Abgleich oder spezifische Zusatzanalyse

Admin kann:

• Anzahl der Stufen festlegen (min. 2, max. 4)
• Jeden Stufen-Prompt zuweisen
• Module für Stufe 1 aktivieren/deaktivieren

4.3 Vordefinierte Konfigurationen (Beispiele)

Alltags-Check (Standard):

• Module: Körper (30T), Ernährung (30T), Training (14T)
• Stufe 1: pipeline_body + pipeline_nutrition + pipeline_activity
• Stufe 2: pipeline_synthesis
• Stufe 3: pipeline_goals

Schlaf-Fokus:

• Module: Schlaf (14T), Vitalwerte (7T), Training (14T)
• Stufe 1: pipeline_sleep + pipeline_vitals + pipeline_activity
• Stufe 2: pipeline_synthesis_sleep

Wettkampf-Analyse:

• Module: Körper (90T), Training (90T), Vitalwerte (30T), Ziele
• Stufe 1: alle Körper/Training/Vital-Module
• Stufe 2: pipeline_synthesis_performance

---

5. Nutzer-Ansicht: KI-Analyse starten

5.1 Einzelanalyse

1. Nutzer wählt Prompt aus der Bibliothek (nach Kategorie gefiltert)
2. KI-Analyse startet sofort
3. Ergebnis wird angezeigt und gespeichert

5.2 Pipeline

1. Nutzer wählt Pipeline-Konfiguration
2. Pipeline startet sofort (alle Stufen laufen automatisch)
3. Ergebnis wird angezeigt und gespeichert

5.3 Kein Konfigurationsschritt für Nutzer

Der Nutzer wählt nur Prompt oder Pipeline – kein weiterer Konfigurationsschritt. Zeitraum und Module sind durch Admin in der Pipeline-Konfiguration festgelegt.

---

6. Analyse-Ergebnisse verwalten

6.1 Kategorie-Zuordnung

Jedes gespeicherte Analyse-Ergebnis erbt die Kategorie des ausgeführten Prompts. Ermöglicht spätere Filterung nach Kategorie.

6.2 Filtern nach Kategorie

Im Analyse-Verlauf kann nach Kategorie gefiltert werden:

• "Alle" / "Körper" / "Ernährung" / "Training" / etc.

6.3 Analyse-Verlauf pro Prompt

Für jeden Prompt ist ein Verlauf einsehbar:

• Liste aller bisherigen Analysen mit diesem Prompt (Datum + Kurzauszug)
• Zeigt wie sich die KI-Aussage über Zeit verändert hat

6.4 Favoriten

Nutzer kann Analysen als Favorit markieren (Stern-Symbol). Favoriten sind in der Verlaufs-Ansicht filterbar.

6.5 Löschen

Nutzer kann einzelne Analyse-Ergebnisse manuell löschen. Keine Massen-Löschung (außer Admin).

---

7. Sprache

Die Ausgabesprache wird im Prompt-Template selbst gesteuert über den Platzhalter {{sprache}}. Der Wert wird aus den Profil-Einstellungen gezogen.

Mögliche Werte: "Deutsch", "Englisch", "Französisch" (erweiterbar)

Standard: "Deutsch"

Kein separater Sprach-Schalter auf der Analyse-Seite – Sprache wird einmalig im Profil konfiguriert.

---

8. Abgrenzung & offene Fragen

In diesem Modul enthalten:

• Prompt-Bibliothek mit 8 Kategorien
• Vollständige Admin-Verwaltung (CRUD, Reihenfolge, Reset)
• Platzhalter-Browser mit Beispielwerten und Vorschau
• Pipeline-Konfigurationen (mehrere, speicherbar)
• Analyse-Ergebnisse: Kategorie, Filter, Verlauf, Favoriten, Löschen
• Sprach-Platzhalter

Nicht in diesem Modul:

• Community-Prompts / Prompt-Import von extern → später
• KI-gestützte Prompt-Optimierung → später
• Automatisch geplante Analysen (z.B. wöchentlich) → später
• Prompts für noch nicht implementierte Module (Schlaf, Mentales) werden vorbereitet aber haben keine echten Daten bis die Module existieren

Offene Fragen für technische Planung:

1. Wie werden Pipeline-Konfigurationen gespeichert? (neue DB-Tabelle oder JSON in ai_prompts?)
2. Platzhalter-Definitionen: statisch im Code oder dynamisch in DB (für zukünftige Erweiterung)?
3. Wie wird der Beispielwert für den Platzhalter-Browser berechnet – gleicher Endpunkt wie die echte Analyse?
4. Reihenfolge der Prompts: getrennte sort_order pro Kategorie oder global?

---

9. Trainingstypen & Fähigkeiten-Mapping (v9d → v9f Integration)

9.1 Hintergrund

In v9d wurde die Basis geschaffen:

• training_types Tabelle mit abilities JSONB-Spalte
• Admin-CRUD für Trainingstypen (ohne Abilities-UI)
• Taxonomie-Endpoint: /api/admin/training-types/taxonomy/abilities
• 5 Fähigkeiten-Dimensionen definiert:
  • 🎯 Koordinativ: Orientierung, Differenzierung, Kopplung, Gleichgewicht, Rhythmus, Reaktion, Umstellung
  • 💪 Konditionell: Kraft, Ausdauer, Schnelligkeit, Flexibilität
  • 🧠 Kognitiv: Konzentration, Aufmerksamkeit, Wahrnehmung, Entscheidungsfindung
  • 🎭 Psychisch: Motivation, Willenskraft, Stressresistenz, Selbstvertrauen
  • ♟️ Taktisch: Timing, Strategie, Antizipation, Situationsanalyse

9.2 Was wird in v9f ergänzt?

Admin-UI: Fähigkeiten-Matrix

Im AdminTrainingTypesPage Formular wird eine Fähigkeiten-Matrix hinzugefügt:

• 5 Sections (eine pro Dimension)
• Pro Dimension: Checkboxes für alle Fähigkeiten
• Multi-Select: Ein Trainingstyp kann mehrere Fähigkeiten pro Dimension trainieren
• Beispiel: "Kampfsport-Sparring" trainiert:
  • Koordinativ: Orientierung, Reaktion, Umstellung
  • Konditionell: Schnelligkeit, Ausdauer
  • Kognitiv: Entscheidung, Wahrnehmung
  • Psychisch: Stressresistenz, Selbstvertrauen
  • Taktisch: Timing, Antizipation

Gespeichert als JSONB:

{
  "koordinativ": ["orientierung", "reaktion", "umstellung"],
  "konditionell": ["schnelligkeit", "ausdauer"],
  "kognitiv": ["entscheidung", "wahrnehmung"],
  "psychisch": ["stressresistenz", "selbstvertrauen"],
  "taktisch": ["timing", "antizipation"]
}

Backend: Fähigkeiten-Aggregation

Neue Endpoint-Funktion (oder Platzhalter-Funktion):

def calculate_abilities_summary(profile_id, days=14):
    """
    Aggregiert trainierte Fähigkeiten über Zeitraum.

    Returns:
    {
      "total_activities": 14,
      "koordinativ": {
        "orientierung": 3,      # 3 von 14 Trainings
        "gleichgewicht": 5,
        ...
      },
      "konditionell": {
        "kraft": 8,
        "ausdauer": 4,
        ...
      },
      ...
      "balance_score": 0.67,    # 0-1, wie ausgewogen
      "top_dimension": "konditionell",
      "weak_dimension": "kognitiv"
    }
    """

KI-Prompt Integration:

Die Fähigkeiten-Platzhalter werden befüllt mit aggregierten Daten:

• {{faehigkeiten_analyse}} → vollständige Aufschlüsselung
• {{faehigkeiten_koordinativ}} → nur koordinative Dimension
• etc.

Pipeline-Prompt "Training" erhält zusätzlichen Context:

Analyse die Fähigkeitenverteilung:
{{faehigkeiten_analyse}}

Gib Empfehlungen für untertrainierte Bereiche.

9.3 Nutzen für KI-Analyse

Beispiel-Insight:

"Deine letzten 14 Trainings fokussieren stark auf konditionelle Fähigkeiten (Kraft: 8×, Ausdauer: 4×). Koordinative Fähigkeiten kommen zu kurz (nur 3× Gleichgewicht, 2× Reaktion). Für einen ausgewogenen Trainingsplan empfehle ich 2-3 koordinationslastige Einheiten pro Woche – z.B. Kampfsport-Techniktraining, Balance-Übungen oder Mobility-Routinen mit Fokus auf Bewegungskontrolle."

Korrelationen:

• Verletzungen / Überlastung ↔ Koordinations-Defizit
• Plateaus im Krafttraining ↔ fehlende kognitive/taktische Komponente
• Erholungsprobleme ↔ psychische Fähigkeiten untertrainiert

9.4 Implementierungs-Reihenfolge

1. ✅ v9d Phase 1b: DB-Schema + Admin-CRUD (ohne Abilities-UI) → erledigt
2. 🔲 v9f: Abilities-Matrix UI im Admin-Formular
3. 🔲 v9f: Backend-Funktion calculate_abilities_summary()
4. 🔲 v9f: Platzhalter {{faehigkeiten_*}} implementieren
5. 🔲 v9f: Standard-Prompts aktualisieren mit Fähigkeiten-Context
6. 🔲 v9f: Admin-Doku: "Best Practices" für Fähigkeiten-Zuordnung

---

EOF echo "OK"