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 (#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
• AI_PROMPT_SYSTEM_SPEC.md
• PLANNING_PROGRESSION_GRAPH_KI.md
• DESIGN_PRINCIPLES_INDEX.md