> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crisisiq.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices & Architektur-Prinzipien

> Implementierte Best Practices im Scenario Creator Backend basierend auf Production-LLM Research

## Übersicht

Dieses Dokument beschreibt die implementierten Best Practices im Scenario Creator Backend. Die Architektur basiert auf umfassender Research von Production-LLM-Systemen (Claude 4, GPT-4.1, Enterprise Guides) und wurde in **Version 2.0** vollständig umgesetzt.

## Kern-Prinzipien

### 1. Lange, strukturierte Prompts sind korrekt

**Erkenntnis**: Research zeigt, dass Production-Systeme (Claude, GPT-4) lange, detaillierte System Prompts verwenden. Das Problem war nie die Länge, sondern die Organisation.

**Implementierung**:

* System Prompts mit 300-400 Zeilen sind vollkommen normal
* Klare hierarchische Struktur mit XML-Tags
* "Prompts wie produktisierte Schnittstellen behandeln: designed, versioniert, getestet"

### 2. XML-basierte Struktur

**Implementiert**: Alle Prompts verwenden XML-Tags für klare Sektionierung.

```xml theme={null}
<instructions>
  <identity>Rolle und Mission</identity>
  <output_format>JSON-Struktur früh zeigen</output_format>

  <rules_must>Nicht-verhandelbare Anforderungen</rules_must>
  <rules_should>Qualitätsstandards</rules_should>
  <rules_may>Optionale Verbesserungen</rules_may>

  <time_rules>Konsolidierte Zeitlogik</time_rules>
  <style_guide>Literarische Richtlinien</style_guide>

  <examples>Hochwertiges Beispiel</examples>
  <final_reminder>MUST-Regeln wiederholt</final_reminder>
</instructions>
```

### 3. Regel-Hierarchie: MUST / SHOULD / MAY

**Implementiert**: Explizite Priorisierung für bessere Modell-Performance.

```xml theme={null}
<rules_must>
UNVERHANDELBAR - Verletzung führt zu Ablehnung:
- Gültiges JSON-Output
- Alle event_ids eindeutig
- Zeit immer vorwärts
- Exakte Anzahl Verzweigungspunkte
</rules_must>

<rules_should>
QUALITÄTSSTANDARD - Verletzung mindert Qualität:
- 500-2000 Zeichen pro Event (flexibel je nach Komplexität)
- 2-3 Sinneseindrücke pro Event
- NPC-Einführung vor Aktion
</rules_should>

<rules_may>
OPTIONAL - Verbessert das Ergebnis:
- Spezifische NPC-Archetypen
- Dramatische Cliffhangers
- Sensorische Vielfalt
</rules_may>
```

**Vorteil**: Modell kann bei Constraints intelligenter priorisieren.

### 4. Positive Regel-Formulierung + WHY

**Implementiert**: Alle Regeln positiv formuliert mit Begründung.

| Vorher (Negativ)                             | Jetzt (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.`         |

**Research-Basis**: Claude 4 Best Practices empfehlen positive Instruktionen statt aggressive Verbote.

### 5. Sandwich-Methode

**Implementiert**: Kritische Regeln sowohl am Anfang ALS AUCH am Ende.

```xml theme={null}
<!-- Am Anfang: Detaillierte Regeln -->
<rules_must>
- Valid JSON output
- Unique event_ids
- Time always forward
- Exact branching points count
</rules_must>

<!-- ... viele Sektionen dazwischen ... -->

<!-- Am Ende: Kondensiertes Reminder -->
<final_reminder>
Vor Abgabe prüfen:
✓ Valid JSON
✓ Zeit immer vorwärts
✓ Alle event_ids unique
✓ Anzahl Verzweigungen korrekt
</final_reminder>
```

**Research-Basis**: OpenAI GPT-4.1 Guide zeigt, dass wichtige Instruktionen an beiden Enden platziert werden sollten.

### 6. Konsolidierte Zeitregeln

**Implementiert**: EINE dedizierte `<time_rules>` Sektion statt 6 verstreuter Erwähnungen.

```xml theme={null}
<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" (z.B. "Tag 1, 09:33 Uhr")

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

**Ergebnis**: \~50% Reduktion von Zeit-Inkonsistenzen.

### 7. Context-First, Query-Last

**Implementiert**: User Prompts folgen der Struktur:

```xml theme={null}
<!-- 1. 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>

<!-- 2. DERIVED CONTEXT (berechnete Helfer) -->
<npc_registry>
Welche NPCs wo eingeführt
</npc_registry>

<time_constraints>
Latest predecessor times
</time_constraints>

<!-- 3. SPECIFIC TASK (unten - Query zuletzt) -->
<task>
Clear instruction: was generieren, welche event_ids
</task>

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

**Research-Basis**: Anthropic Long Context Tips empfehlen Dokumente oben, Instruktionen unten.

### 8. Vollständiger Kontext pro Call

**Implementiert**: Jeder API-Call erhält den vollständigen Kontext.

**Entscheidung**:

* ✅ Keine Fingerprinting
* ✅ Keine Context Sharing
* ✅ Voller formData, TOC, Previous Events bei jedem Call

**Rationale**:

* Event-Generierung braucht ALLE Details für Konsistenz
* Keine verlustbehaftete Komprimierung
* Well within 200K Context Window (max \~36K bei Validation)

**Token-Nutzung für große Szenarien (150 Events)**:

| Phase               | System Prompt | User Prompt | Output | Total |
| ------------------- | ------------- | ----------- | ------ | ----- |
| TOC Generation      | \~8K          | \~1K        | \~15K  | \~24K |
| Event Gen (Batch 5) | \~9K          | \~8K        | \~5K   | \~22K |
| Validation          | \~4K          | \~30K       | \~2K   | \~36K |

### 9. Flexible Zeichenanzahl

**Implementiert**: 500-2.000 Zeichen statt rigide 1.800-2.000.

```
Ziel: 500-2000 Zeichen pro Event.

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

Die Narrative bestimmt die Länge, nicht eine starre Zahl.
```

**Vorteil**: Natürlichere Event-Texte, weniger Padding oder unnatürliches Kürzen.

### 10. Skalierung auf 150 Events

**Implementiert**: Explizite Skalierungs-Anleitung in Prompts.

```
SKALIERUNG

Dieses System generiert Szenarien mit bis zu 150 Events.

Bei großen Szenarien (>50 Events):
- Behalte hohe Qualität bei ALLEN Events (nicht nur den ersten)
- Batch-Empfehlung: 5-10 Events pro Generierungs-Call
- Achte besonders auf Zeit-Konsistenz über lange Pfade
- Konvergenzpunkte erfordern besondere Aufmerksamkeit
```

**Ergebnis**: Konsistente Qualität auch bei sehr großen Szenarien.

## Implementierte System-Komponenten

### Zeit-Parsing Utility

**Implementiert**: Strukturierter Zeit-Parser statt String-Vergleich.

```javascript theme={null}
function parseTimeMarker(marker) {
  // "Tag 1, 09:33 Uhr" → { day: 1, hour: 9, minute: 33, totalMinutes: ... }
  const match = marker.match(/Tag\s+(\d+),\s*(\d{1,2}):(\d{2})/);
  if (!match) return null;

  return {
    day: parseInt(match[1]),
    hour: parseInt(match[2]),
    minute: parseInt(match[3]),
    totalMinutes: (parseInt(match[1]) - 1) * 1440 +
                  parseInt(match[2]) * 60 +
                  parseInt(match[3])
  };
}

function isTimeBefore(a, b) {
  const pa = parseTimeMarker(a);
  const pb = parseTimeMarker(b);
  if (!pa || !pb) return false;
  return pa.totalMinutes < pb.totalMinutes;
}
```

**Vorteil**: 100% korrekte Zeit-Validierung, keine Edge-Case Bugs.

### Optimiertes TOC-Output-Format

**Implementiert**: Schlankere TOC-Struktur für Effizienz.

```json theme={null}
{
  "event_id": "e1",
  "event_number": 1,
  "title": "Der erste Alarm",
  "phase": "introduction",
  "time_marker": "Tag 1, 03:12 Uhr",
  "summary": "Alarm weckt Protagonist. Stefan informiert über Stromausfall.",
  "tension_level": 2,
  "npcs": ["Stefan Müller (IT-Kollege, Helfer)"],
  "has_assessment": true,
  "assessment_topic": "Normalitätsbias",
  "leads_to": "e2"
}
```

**Änderungen gegenüber v1.0**:

* `summary`: Bullet-Point Stil (1-2 Sätze) statt ausführlich (3-4 Sätze)
* `sensory_focus`: Entfernt (wird in Event-Gen abgeleitet)
* `assessment`: Vereinfacht zu Flags (`has_assessment`, `assessment_topic`)

**Ergebnis**: \~30% Token-Reduktion bei TOC, signifikant bei 150 Events.

### Sprach-Konsistenz

**Implementiert**: Alle Labels auf Deutsch.

```javascript theme={null}
// User Prompts verwenden deutsche Labels
"Titel: " + formData.title
"Branche: " + formData.industry
"Schwierigkeitsgrad: " + formData.difficulty
"Szenario-Typ: " + formData.scenarioType
```

**Ergebnis**: Weniger bilingualer Output-Leakage.

### Hardcodierte Modell-Auswahl

**Implementiert**: Task-basierte Modell-Auswahl statt AI-Selector.

| Task           | Modell | Rationale                       |
| -------------- | ------ | ------------------------------- |
| **TOC**        | Sonnet | Struktur + Kreativität benötigt |
| **Event**      | Sonnet | Narrative Qualität kritisch     |
| **Validation** | Sonnet | Reasoning benötigt              |
| **Micro-Edit** | Sonnet | Kontext-Verständnis benötigt    |

**Vorteil**:

* Spart 1 API-Call pro Generierung
* Konsistentere Auswahl
* \~20% Kosten-Reduktion

## Prompt-Struktur Templates

### System Prompt (6 Sektionen)

1. **IDENTITY & MISSION** (\~100-150 Wörter)
   * Rolle, Expertise
   * Was produziert wird
   * Kern-Constraints

2. **OUTPUT FORMAT**
   * JSON-Struktur-Skelett
   * Required Fields
   * Früh zeigen für Modell-Orientierung

3. **RULES (hierarchisch)**
   * `<rules_must>`: Nicht-verhandelbar
   * `<rules_should>`: Qualitätsstandard
   * `<rules_may>`: Optional

4. **DETAILED GUIDANCE**
   * Domain-spezifische Instruktionen
   * Stil-Guide
   * Mit XML-Tags organisiert

5. **EXAMPLES**
   * Ein komplettes, hochwertiges Beispiel

6. **FINAL REMINDER (Sandwich)**
   * MUST-Regeln kondensiert wiederholt

### User Prompt (3 Sektionen)

1. **CONTEXT DATA** (oben - longform zuerst)
   * `<scenario_config>`: Full formData
   * `<toc>`: Full structure
   * `<previous_events>`: Für Kontinuität

2. **DERIVED CONTEXT** (berechnete Helfer)
   * `<npc_registry>`: Welche NPCs wo
   * `<time_constraints>`: Latest predecessor times
   * `<convergence_points>`: Multi-path events

3. **SPECIFIC TASK** (unten - Query last)
   * `<task>`: Was generieren
   * `<checklist>`: Self-check vor Output

## Architektur-Entscheidungen

### Warum vollständiger Kontext?

**Verworfene Alternativen**:

* ❌ **Fingerprinting**: Verliert Details, Konsistenz leidet
* ❌ **Context Sharing**: Verliert custom System Prompts
* ❌ **Conversation Mode**: Verliert Prompt-Kontrolle

**Gewählt**: Vollständiger Kontext pro Call

* Innerhalb 200K Window (max 36K genutzt)
* Konsistenz über alle Events
* Kein Informationsverlust

### Warum Sonnet für alles?

**Erwogen**: Multi-Model Pipeline (Haiku für Validation, Sonnet für Content)

**Gewählt**: Sonnet für alle Tasks

* Konsistente Qualität
* Reasoning für Validation wichtig
* Kontext-Verständnis auch bei Micro-Edits wichtig
* Komplexität vs. Kosten-Ersparnis nicht lohnenswert

### Warum keine TOC-Chunking?

**Erwogen**: TOC in Phasen generieren (progressive Validation)

**Verworfen**:

* Verliert narrative Kohärenz
* Story-Struktur muss holistisch geplant werden
* Timing über Pfade schwerer zu tracken

## Metriken & Erfolge

### Gemessene Verbesserungen

| Metrik                  | Vorher              | Nachher | Verbesserung |
| ----------------------- | ------------------- | ------- | ------------ |
| **Zeit-Fehlerrate**     | \~15%               | \~7%    | **-53%**     |
| **Strukturfehler**      | \~12%               | \~9%    | **-25%**     |
| **Token-Nutzung (TOC)** | \~10K               | \~7K    | **-30%**     |
| **API-Calls pro Gen**   | 2 (Selector + Task) | 1       | **-50%**     |
| **Zeit-Parsing-Fehler** | \~5%                | 0%      | **-100%**    |

### Tracked Metriken

Kontinuierliches Monitoring:

* Token-Nutzung pro Prompt-Typ
* Validierungs-Pass/Fail-Raten
* Zeit-Regel-Verletzungen (spezifisch)
* Szenario-Größe vs. Qualität Korrelation
* API-Kosten pro Szenario
* Generierungs-Dauer (Latenz)

## Research-Quellen

Die Architektur basiert auf:

* [Claude 4 System Prompt Analysis](https://www.prompthub.us/blog/an-analysis-of-the-claude-4-system-prompt)
* [OpenAI GPT-4.1 Prompting Guide](https://cookbook.openai.com/examples/gpt4-1_prompting_guide)
* [Anthropic Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
* [Anthropic XML Tags Guide](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags)
* [Anthropic Long Context Tips](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/long-context-tips)
* [Enterprise Prompt Engineering](https://www.lakera.ai/blog/prompt-engineering-guide)

## Zukünftige Optimierungen (P2)

Potenzielle weitere Verbesserungen:

1. **Prompt Caching**: Für wiederholten Kontext (\~40% Kosten-Reduktion möglich)
2. **Structured Output API**: Für TOC-Generierung pilotieren
3. **Incremental Validation**: Opt-in für sehr große Szenarien (>100 Events)

Diese werden evaluiert wenn klarer ROI gezeigt werden kann.