Kairo-Jinkendo/docs/reference/design-principles/shinkan/AI_PROMPT_RUNTIME_DESIGN_PRINCIPLES.md

# AI Prompt Runtime – Designprinzipien (Extraktion)

**Status:** Analyse / Arbeitspapier  
**Stand:** 2026-07-04  
**Geltungsbereich:** Modul „AI Prompt Runtime“ — Shinkan-KI-Schicht, keine Planungs-Gesamtarchitektur

**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 5 von 15  
**Mitai-Vergleich:** [PROMPT_ENGINE_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/PROMPT_ENGINE_DESIGN_PRINCIPLES.md) (#1)

**Kernkomponenten:**

| Bereich | Pfade |
|---------|-------|
| Laufzeit | `backend/ai_prompt_runtime.py`, `backend/prompt_resolver.py` |
| Domänen-Orchestrierung | `backend/exercise_ai.py`, `backend/planning_exercise_*.py` |
| OpenRouter | `backend/openrouter_chat.py` |
| Admin | `backend/routers/ai_prompts_admin.py` |
| Zielbild | `.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md` |
| Job-Kontext | `backend/ai_prompt_job.py`, `backend/ai_prompt_context.py` |

---

## Modul

**AI Prompt Runtime**

Schmale Ausführungsschicht für admin-konfigurierbare Prompts in `ai_prompts`: Laden, Mustache-Rendering, Kontext-Arten, OpenRouter-Aufruf. **Kein** vollständiges Unified Prompt System wie Mitai (keine Workflows/Pipelines in Produktion).

---

## Fachliche Verantwortung

1. **Prompt-Laden aus DB** — `load_ai_prompt_row`, `load_and_render_ai_prompt`
2. **Platzhalter-Ersetzung** — Mustache `{{key}}` via `prompt_resolver.py`
3. **Kontext-Arten** — `AiPromptContextKind` trennt Übungs-KI vs. Planungs-KI
4. **Domänen-Builder** — `exercise_ai`, Planungs-Pipelines bauen Variablen-Maps
5. **Admin CRUD + Preview** — ohne LLM in Preview-Pfaden wo vorgesehen

---

## Designprinzipien

### 1. Eine Laufzeit-Fassade für DB-Prompts

| | |
|---|---|
| **Prinzip** | Produktive Aufrufe laden Slugs über `ai_prompt_runtime` — nicht Roh-SQL auf `ai_prompts` in Routern. |
| **Begründung** | Einheitliches inactive-Handling, Modell-Feld, Render-Metadaten. |
| **Quelle** | `AI_PROMPT_TARGET_ARCHITECTURE.md` §2.1; `ai_prompt_runtime.py` |
| **Tragfähigkeit** | **hoch** (Zielrichtung) |
| **Einschränkung** | Planungs-KI hat noch verteilte Orchestratoren; kein einzelner `execute_prompt` wie Mitai. |

### 2. Konfigurierbare Bibliothek in `ai_prompts`

| | |
|---|---|
| **Prinzip** | Template-Texte in DB; Admins ändern ohne Deploy (`ai_prompts_admin`). |
| **Begründung** | Gleiches Familien-Muster wie Mitai Prompt-Bibliothek. |
| **Quelle** | Migration 069+; Admin-UI |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Keine Pipeline/Workflow-Typen; Slugs hardcoded in `context_kind_for_slug`. |

### 3. Kontext-Namespaces statt globaler Platzhalter-Soup

| | |
|---|---|
| **Prinzip** | `AiPromptContextKind` (z. B. `exercise_form_ai`, `planning_exercise_search`) begrenzt erlaubte Builder. |
| **Begründung** | Planungs-Kontext wächst ohne Kollision mit Übungs-Keys. |
| **Quelle** | `AI_PROMPT_TARGET_ARCHITECTURE.md` §2.3 |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Noch keine zentrale Platzhalter-Registry wie Mitai — Mustache ad hoc pro Builder. |

### 4. Trennung Template vs. Domänen-Kontext

| | |
|---|---|
| **Prinzip** | UI/Router liefern Pydantic-DTOs → Builder erzeugen `variables`-Map → `render_mustache_template`. |
| **Begründung** | Prompt-Autoren ändern Text, nicht Python in Routern. |
| **Quelle** | `prompt_resolver.py`; `ExerciseFormAiPromptContext` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Große Planungs-Kontexte noch nicht vollständig über DTOs. |

### 5. Transport (OpenRouter) getrennt von Semantik

| | |
|---|---|
| **Prinzip** | `openrouter_chat.py` für HTTP; Validierung/JSON-Parsing in Domänen-Schicht. |
| **Begründung** | Modellwechsel ohne Router-Anpassung. |
| **Quelle** | `AI_PROMPT_TARGET_ARCHITECTURE.md` §2.2 |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Modell teils global Env, teils Spalte `openrouter_model` — Konvergenz offen. |

### 6. Reset-to-default für System-Prompts

| | |
|---|---|
| **Prinzip** | `default_template` + Admin-Reset — kein vollständiges Versionsmodell. |
| **Begründung** | Familien-Muster aus Mitai; Schutz vor Fehlkonfiguration. |
| **Quelle** | Migration 069 |
| **Tragfähigkeit** | **mittel** |
| **Einschränkung** | Keine Historie benutzerdefinierter Änderungen. |

### 7. Admin-only Schreiben, authentifiziertes Ausführen

| | |
|---|---|
| **Prinzip** | Prompt-CRUD nur Admin; Ausführung mit Capability + Feature-Kontingent. |
| **Begründung** | Systemkonfiguration vs. Nutzung; Kostenkontrolle. |
| **Quelle** | `ai_prompts_admin.py`; `exercises.ai.suggest` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Enforcement teils noch Probe-Phase. |

### 8. Skill-Retrieval orthogonal zu Prompts

| | |
|---|---|
| **Prinzip** | `ai_skill_retrieval_profiles` steuert Katalog für `{{skills_catalog}}` — unabhängig vom Prompt-Text. |
| **Begründung** | Anweisung vs. Kontextfenster trennbar konfigurierbar. |
| **Quelle** | `AI_PROMPT_TARGET_ARCHITECTURE.md` §3.3 |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | — |

---

## Nicht übernehmen (Shinkan-Ist / Mitai-Vermeidung)

1. **Direkte OpenRouter-Calls in Routern** ohne Laufzeit-Schicht — historische Schuld, abbauen.
2. **Hardcodierte Prompt-Strings in Produktion** — nur Fallback/Dev.
3. **Mitai-Workflow-Graph vorreifen** — Shinkan braucht erst Planungs-Kontext-Reife.
4. **Globale Platzhalter-Map ohne Namespace** — Mitai-Lektion `PLACEHOLDER_MAP`-Duplikat.
5. **Fehlende JSON-Schema-Validierung** bei `output_format=json` — Mitai-TODO übernehmen vermeiden.

---

## Verwandte Dokumentation

- [AI_PROMPT_TARGET_ARCHITECTURE.md](../../../.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md)
- [AI_PROMPT_SYSTEM_SPEC.md](../../../.claude/docs/technical/AI_PROMPT_SYSTEM_SPEC.md)
- [PLANNING_PROGRESSION_GRAPH_KI.md](../../architecture/PLANNING_PROGRESSION_GRAPH_KI.md)
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)