Prompt-Architektur - crisisIQ Documentation

Übersicht

Das Prompt-System ist das Herzstück des Scenario Creator Backends. Es besteht aus 10 Dateien mit insgesamt ~2.185 Zeilen Code, die verschiedene Aspekte der Szenario-Generierung steuern.

Research-Erkenntnisse (Version 2.0)

Lange Prompts sind korrekt

Initiale Annahme, dass System Prompts kurz sein sollten, war falsch. Research zeigt:

Quelle	Erkenntnis
Claude 4 System Prompt Analyse	Claudes eigener System Prompt hat mehrere Hauptsektionen: Identity, Boundaries, Tone, Safety, Tool Instructions. Verwendet XML-Tags, ALL CAPS für kritische Regeln
OpenAI GPT-4.1 Guide	Empfiehlt: Role → Instructions → Sub-categories → Reasoning Steps → Output Format → Examples → Context → Final instructions
Enterprise Prompt Engineering	”Prompts können viele Absätze lang sein… Prompts wie produktisierte Schnittstellen behandeln: designed, versioniert, getestet”

Schlussfolgerung: Lange, detaillierte System Prompts sind angemessen. Das Problem ist Organisation, nicht Länge.

Strukturelle Prinzipien

Prinzip	Quelle	Anwendung
Sandwich-Methode	OpenAI GPT-4.1	Kritische Instruktionen sowohl am START als auch am ENDE
XML-Tags für Struktur	Anthropic Docs	`<instructions>`, `<rules>`, `<examples>`
Positiv statt negativ	Claude 4 Best Practices	”Sage was zu tun IST, nicht was NICHT zu tun ist”
WHY erklären	Claude 4 Best Practices	”Reasoning-Kontext liefern statt nur Regeln zu nennen”
Kein aggressives Prompting	Claude 4 Best Practices	Nicht “KRITISCH: Du MUSST” - Claude 4 ist bereits responsiv
ALL CAPS für Kritisches	Claudes eigener Prompt	Betonung nur für nicht-verhandelbare Regeln
Context first, Query last	Anthropic Long Context	Dokumente oben, Instruktionen unten
Prefill für JSON	Anthropic Prefill Guide	Assistant Response mit `{` starten

Was aktuelle Prompts falsch machen

Problem	Aktueller Ansatz	Research sagt
Regel-Framing	Stark negativ (“VERBOTEN”, “NIEMALS”, ”⛔“)	Positives Framing funktioniert besser
Regel-Hierarchie	Alle Regeln flach präsentiert	Explizite MUST/SHOULD/MAY Stufen
Kritische Betonung	Alles ist “KRITISCH”	Nur wirklich kritische Items in ALL CAPS
Struktur	Verstreute Sektionen	Hierarchisch mit XML-Tags
Beispiele	Inline mit Regeln	Dedizierte `<examples>` Sektion
Sandwich	Instruktionen nur am Start	Kritische Regeln am Ende wiederholen

Prompt-Dateien Inventar

Datei	Zeilen	Zweck	Status
`tocPrompt.js`	465	TOC-Generierung	Aktiv
`validatePrompt.js`	231	Validierung	Aktiv
`modelSelectorPrompt.js`	86	Modell-Auswahl	Aktiv
`event/systemPrompt.js`	397	Event System Prompt	Aktiv
`event/generatePrompt.js`	310	Event User Prompt	Aktiv
`event/regeneratePrompt.js`	44	Regenerierung	Aktiv
`event/microEditPrompt.js`	118	Mikro-Bearbeitung	Aktiv
`event/validationPrompt.js`	191	Validierungs-Fix	Aktiv
`event/helpers.js`	331	Hilfsfunktionen	Aktiv
`event/index.js`	12	Barrel Export	Aktiv

Detaillierte Prompt-Analyse

1. TOC Prompt (`tocPrompt.js`)

Zweck: Generiert die komplette Story-Struktur als Graph-Modell.

Stärken

Umfassende Regeln für Graphen-Modell
Klare Beispiele für Event-Struktur
Explizite Zeitkonsistenz-Regeln

Herausforderungen

Das TOC-Prompt hat ~370 Zeilen mit 12+ Regel-Sektionen:

JSON-Struktur-Anforderungen
Zeitregeln (6 verschiedene zeitsynchrone Sektionen)
Verzweigungslogik
Assessment-Platzierung
NPC-Verwaltung
Konvergenz-Handling

Kritische Zeitregeln

ZEITREGEL (Aktuell):
- Jedes Event muss zeitlich nach seinen Vorgängern liegen
- Parallele Pfade müssen synchronisiert werden
- Konvergenzpunkte müssen alle Vorgänger berücksichtigen
- Tag/Uhrzeit Format: "Tag X, HH:MM Uhr"
- Zeitsprünge müssen narrativ begründet sein
- Keine Zeitschleifen

Problem: Diese Regeln sind über 6 Sektionen verteilt, was zu kognitiver Überlastung führt.

2. Event System Prompt (`event/systemPrompt.js`)

Zweck: Definiert den literarischen Stil und die Qualitätsanforderungen für Event-Texte.

Struktur

~400 Zeilen mit 15+ Sektionen
Literarischer Stil-Guide
“Show don’t tell” Prinzipien
Zeichenanzahl-Vorgaben

Kern-Anforderungen

Anforderung	Spezifikation	Typ
Zeichenanzahl	500-2.000 Zeichen (flexibel)	Weich
Sinneseindrücke	2-3 pro Event	Weich
Dramaturgie	Spannungsbogen	Weich
Perspektive	2. Person Singular	Hart
Sprache	Deutsch (DE)	Hart

Hinweis: Komplexe Szenen mit viel Dialog oder mehreren NPCs benötigen mehr Platz. Einfache Übergangsszenen können kürzer sein.

Stil-Richtlinien

SHOW DON'T TELL Beispiele:

❌ Schlecht: "Sie sind nervös."
✅ Gut: "Ihre Finger trommeln auf dem Tisch."

❌ Schlecht: "Der Raum ist chaotisch."
✅ Gut: "Akten stapeln sich auf dem Boden, leere Kaffeetassen säumen den Schreibtisch."

3. Event Generate Prompt (`event/generatePrompt.js`)

Zweck: Baut den konkreten User-Prompt für jedes Event auf.

Kontext-Injektion

Der Prompt injiziert folgende Kontexte:

Formular-Daten
- Industrie
- Szenario-Typ
- Schwierigkeitsgrad
- Titel & Beschreibung
TOC-Struktur
- Vollständiger Graph
- Alle Event-IDs
- Verzweigungslogik
NPC-Registry
- Bereits verwendete NPCs
- Charakter-Beschreibungen
Vorgänger-Inhalte
- Vollständiger Text aller direkten Vorgänger
- Zeit-Constraints
Konvergenz-Information
- Ob dieses Event ein Konvergenzpunkt ist
- Welche Pfade zusammenlaufen

Typischer Prompt-Aufbau

Industrie: [X]
Szenario-Typ: [Y]
Schwierigkeitsgrad: [Z]

TOC-Struktur:
[Gesamter Graph als JSON]

Bereits verwendete NPCs:
[NPC-Liste]

Vorgänger-Event(s):
[Vollständiger Text]

Zeitbeschränkungen:
Muss nach: [Latest Predecessor Time]

GENERIERE JETZT: Event [event_id]

4. Validation Prompt (`validatePrompt.js`)

Zweck: Post-hoc Validierung des gesamten generierten Szenarios.

Validierungs-Kategorien

Kategorie	Severity	Beispiele
Zeitfehler	CRITICAL	Zeitsprünge rückwärts, inkonsistente Marker
Strukturfehler	CRITICAL	Fehlende Events, gebrochene Verzweigungen
Inhaltsfehler	HIGH	NPC-Inkonsistenzen, Plot-Holes
Stilfehler	MEDIUM	Zeichenanzahl, Sinneseindrücke
Kleinigkeiten	LOW	Tippfehler, Formatierung

Explizite “Was NICHT flaggen”

NICHT flaggen:
- Kreative Entscheidungen im Stil
- Dramaturgische Variationen
- Unterschiedliche NPC-Darstellungen (solange konsistent)
- Zeitsprünge die narrativ begründet sind

Problem

Post-hoc Only: Validierung läuft erst NACH Generierung aller Events. Fehler in Event 2 können sich durch Event 3, 4, 5… fortpflanzen, bevor sie erkannt werden.

5. Regeneration & Micro-Edit

Regenerate Prompt (`event/regeneratePrompt.js`)

44 Zeilen: Kompakt und fokussiert
Integriert User-Feedback
Behält Kontext bei

Micro-Edit Prompt (`event/microEditPrompt.js`)

118 Zeilen: Chirurgische Änderungen
Für einzelne Probleme (z.B. Tippfehler, NPC-Namen)
Verwendet Haiku-Modell (kostengünstig)

6. Model Selector Prompt (`modelSelectorPrompt.js`)

Zweck: Wählt das optimale Claude-Modell basierend auf Aufgaben-Komplexität.

Entscheidungskriterien (aktuell)

Haiku:
- Einfache Struktur-Validierung
- Micro-Edits
- Standardisierte Aufgaben

Sonnet:
- Standard-Szenario-Generierung
- Mittlere Komplexität
- TOC mit <20 Events

Opus:
- Sehr komplexe Szenarien
- >30 Events
- Multiple Verzweigungen
- Hohe Qualitätsanforderungen

Problem

Vage Kriterien: “sehr komplex” ist subjektiv und führt zu inkonsistenter Auswahl.

Helper-Funktionen

Zeit-Management (`event/helpers.js`)

Aktuelle Implementierung

// String-basierter Vergleich
pred.time_marker > latestPredecessor.time_marker

Problem: Funktioniert NICHT für Edge Cases:

“Tag 1, 23:59” vs “Tag 2, 00:01”
Verschiedene Formatierungen

Vorgänger-Suche

function findAllPredecessorIds(eventId, toc) {
  // Aktuell: Ein Level tief
  // Problem: Verpasst transitive Abhängigkeiten
}

Konsequenz: Bei langen Ketten können Zeitfehler auftreten.

Prompt-Effizienz-Analyse

Redundanz-Probleme

Problem	Häufigkeit	Impact
Kontext-Duplizierung	Jeder Call	~30-40% Redundanz
TOC wird wiederholt	Jedes Event	~2-3K Tokens/Call
FormData wird wiederholt	Jedes Event	~500 Tokens/Call

Token-Verbrauch pro Aufgabe

TOC Generation:
Input: ~8.500 Tokens
Output: ~2.000 Tokens
Total: ~10.500 Tokens

Event Generation (3 Events):
Input: ~12.000 Tokens
Output: ~3.000 Tokens
Total: ~15.000 Tokens

Validation:
Input: ~15.000 Tokens (gesamtes Szenario)
Output: ~1.000 Tokens
Total: ~16.000 Tokens

Sprach-Konsistenz

Aktuelles Problem: Gemischte EN/DE Labels

// In User Prompts:
"Title: [titel]"           // English label, German content
"Industry: [industrie]"    // English label, German content

// Erwartete Ausgabe: Deutsch
// Kann zu Sprach-Leakage führen

Vorgeschlagene Prompt-Struktur

System Prompt Template (6 Sektionen)

Basierend auf Research sollten System Prompts dieser Struktur folgen:

IDENTITY & MISSION (~100-150 Wörter)
- Wer du bist (Rolle, Expertise)
- Was du produzierst
- Kern-Constraints (Sprache, Perspektive)
OUTPUT FORMAT
- JSON-Struktur-Skelett
- Required Fields
- Format FRÜH zeigen, damit Modell das Ziel kennt

RULES (hierarchisch)

<rules_must>
UNVERHANDELBAR - Verletzung führt zu Ablehnung:
- Valid JSON output
- Unique event_ids
- Time always forward
</rules_must>

<rules_should>
QUALITÄTSSTANDARD - Verletzung mindert Qualität:
- 500-2000 chars per event
- 2-3 senses per event
</rules_should>

<rules_may>
OPTIONAL - Verbessert das Ergebnis:
- Specific NPC archetypes
- Dramatic cliffhangers
</rules_may>

DETAILED GUIDANCE
- Domain-spezifische Instruktionen
- Stil-Guide
- Edge Cases
- Organisiert mit XML-Tags: <time_rules>, <style_guide>, etc.

EXAMPLES

<examples>
Ein komplettes, hochwertiges Beispiel des erwarteten Outputs
</examples>

FINAL REMINDER (Sandwich)
- MUST-Regeln in kondensierter Form wiederholen
- JSON only
- Time forward
- All event_ids unique

User Prompt Template (3 Sektionen)

CONTEXT DATA (oben - longform zuerst)

<scenario_config>
Full formData - ALLE Details für Konsistenz
</scenario_config>

<toc>
Full TOC structure
</toc>

<previous_events>
Previously generated events
</previous_events>

DERIVED CONTEXT (berechnete Helfer)

<npc_registry>
Welche NPCs wo eingeführt
</npc_registry>

<time_constraints>
Latest predecessor times
</time_constraints>

SPECIFIC TASK (unten - Query zuletzt)

<task>
Clear instruction: was generieren, welche event_ids
</task>

<checklist>
Quick self-check vor Output
</checklist>

Regel-Framing: Negativ → Positiv

Aktuell (Negativ)	Vorgeschlagen (Positiv + WHY)
`⛔ VERBOTEN: NIEMALS englische Wörter`	`Schreibe auf Deutsch. Verwende deutsche Fachbegriffe (z.B. "prüfen" statt "checken"), da die Zielgruppe deutschsprachige Fachleute sind.`
`⛔ KRITISCH: Unter 1.800 Zeichen = FEHLER`	`Ziel: 500-2000 Zeichen pro Event. Komplexe Szenen mit viel Dialog benötigen mehr Platz. Einfache Übergangsszenen können kürzer sein.`
`NIEMALS rückwärts in der Zeit!`	`Zeit fließt immer vorwärts. Jedes Event muss zeitlich nach seinem Vorgänger liegen, da die Geschichte chronologisch erlebt wird.`

Konsolidierte Zeitregeln

Aktuell: 6 verstreute Sektionen über Zeit. Vorgeschlagen: EINE dedizierte Sektion:

<time_rules>
ZEITLOGIK

Eine einzige Regel: Zeit fließt vorwärts.

Für jedes Event gilt:
  time_marker MUSS später sein als ALLE Events, die zu diesem führen.

Bei Konvergenz (mehrere Pfade führen zu einem Event):
  Der Konvergenz-Event muss NACH dem spätesten aller Vorgänger liegen.

  Beispiel:
  - e4a endet um 10:15
  - e4b endet um 10:18
  - e4c endet um 10:20 ← spätester
  → e5 muss 10:21 oder später sein

Format: "Tag X, HH:MM Uhr"

Vor Abgabe prüfen:
  Folge jedem Pfad von e1 bis zum Ende.
  Ist die Zeit in jedem Schritt aufsteigend? ✓
</time_rules>

Best Practices (abgeleitet)

Was funktioniert gut

Klare Beispiele: “Show don’t tell” Beispiele sind sehr effektiv
Strukturierte Ausgabe: JSON-Format mit Schema funktioniert zuverlässig
Kontext-Injektion: Vorgänger-Inhalte helfen bei Konsistenz
Severity Levels: Klare Priorisierung in Validierung

Was verbessert werden sollte

Prompt-Restrukturierung mit XML-Tags (P0)
Regel-Hierarchie hinzufügen: MUST vs SHOULD vs MAY (P0)
Positives Regel-Framing: Negativ → Positiv konvertieren (P0)
Zeitregeln konsolidieren: Zu EINER Sektion zusammenfassen (P0)
Sandwich-Methode: MUST-Regeln am Ende wiederholen (P0)
Zeit-Parsing: Strukturierter Vergleich statt String (P1)
Sprach-Konsistenz: Alle Labels auf Deutsch (P1)
TOC-Output optimieren: Schlankere Struktur (P1)

Nächste Schritte

Siehe Bekannte Probleme & Verbesserungen für detaillierte Verbesserungsvorschläge.

​Übersicht

​Research-Erkenntnisse (Version 2.0)

​Lange Prompts sind korrekt

​Strukturelle Prinzipien

​Was aktuelle Prompts falsch machen

​Prompt-Dateien Inventar

​Detaillierte Prompt-Analyse

​1. TOC Prompt (tocPrompt.js)

​Stärken

​Herausforderungen

​Kritische Zeitregeln

​2. Event System Prompt (event/systemPrompt.js)

​Struktur

​Kern-Anforderungen

​Stil-Richtlinien

​3. Event Generate Prompt (event/generatePrompt.js)

​Kontext-Injektion

​Typischer Prompt-Aufbau

​4. Validation Prompt (validatePrompt.js)

​Validierungs-Kategorien

​Explizite “Was NICHT flaggen”

​Problem

​5. Regeneration & Micro-Edit

​Regenerate Prompt (event/regeneratePrompt.js)

​Micro-Edit Prompt (event/microEditPrompt.js)

​6. Model Selector Prompt (modelSelectorPrompt.js)

​Entscheidungskriterien (aktuell)

​Problem

​Helper-Funktionen

​Zeit-Management (event/helpers.js)

​Aktuelle Implementierung

​Vorgänger-Suche

​Prompt-Effizienz-Analyse

​Redundanz-Probleme

​Token-Verbrauch pro Aufgabe

​Sprach-Konsistenz

​Vorgeschlagene Prompt-Struktur

​System Prompt Template (6 Sektionen)

​User Prompt Template (3 Sektionen)

​Regel-Framing: Negativ → Positiv

​Konsolidierte Zeitregeln

​Best Practices (abgeleitet)

​Was funktioniert gut

​Was verbessert werden sollte

​Nächste Schritte

Übersicht

Research-Erkenntnisse (Version 2.0)

Lange Prompts sind korrekt

Strukturelle Prinzipien

Was aktuelle Prompts falsch machen

Prompt-Dateien Inventar

Detaillierte Prompt-Analyse

1. TOC Prompt (`tocPrompt.js`)

Stärken

Herausforderungen

Kritische Zeitregeln

2. Event System Prompt (`event/systemPrompt.js`)

Struktur

Kern-Anforderungen

Stil-Richtlinien

3. Event Generate Prompt (`event/generatePrompt.js`)

Kontext-Injektion

Typischer Prompt-Aufbau

4. Validation Prompt (`validatePrompt.js`)

Validierungs-Kategorien

Explizite “Was NICHT flaggen”

Problem

5. Regeneration & Micro-Edit

Regenerate Prompt (`event/regeneratePrompt.js`)

Micro-Edit Prompt (`event/microEditPrompt.js`)

6. Model Selector Prompt (`modelSelectorPrompt.js`)

Entscheidungskriterien (aktuell)

Problem

Helper-Funktionen

Zeit-Management (`event/helpers.js`)

Aktuelle Implementierung

Vorgänger-Suche

Prompt-Effizienz-Analyse

Redundanz-Probleme

Token-Verbrauch pro Aufgabe

Sprach-Konsistenz

Vorgeschlagene Prompt-Struktur

System Prompt Template (6 Sektionen)

User Prompt Template (3 Sektionen)

Regel-Framing: Negativ → Positiv

Konsolidierte Zeitregeln

Best Practices (abgeleitet)

Was funktioniert gut

Was verbessert werden sollte

Nächste Schritte