Prompt-Versionierung und Katalogverwaltung
Auf dieser Seite
Lektion aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation:
temperatureundtop_pwerden nur mit einem Reasoning-Effort vonnoneakzeptiert, während GPT-5.6-Modelle standardmäßig mitmediumrechnerisch arbeiten. Aufrufe, die diese Parameter festlegen, müssen daherreasoning={"effort": "none"}(Responses API) oderreasoning_effort="none"(Chat Completions) angeben. Quellen: Using GPT-6 · GPT-5.6 Terra.
Prompt-Versionierung und Katalogverwaltung
In der Produktion entwickeln sich Ihre Prompts genauso stark wie Ihr Code. Ohne Versionierung verlieren Sie den Überblick über Änderungen, können nicht auf vorherige Versionen zurückgreifen und wissen nicht, welche Version in der Produktion läuft. In dieser Lektion erfahren Sie, wie Sie Prompts als Software-Artefakte verwalten.
Warum Prompts versionieren
Eine Änderung am Prompt kann das Verhalten Ihrer Anwendung radikal verändern. Im Gegensatz zum Code sind diese Änderungen oft subtil und schwer ohne automatisierte Tests zu erkennen: Ein umformulierter Satz, ein verschobenes Wort, und das Modell beginnt, in einem von zehn Grenzfällen falsch zu klassifizieren. Kein Standard-Einheitstest wird diese Lücke aufdecken, aber der Support wird es drei Wochen später als vage Beschwerde über falsch geroutete Tickets melden.
Die Versionierung adressiert vier unterschiedliche Bedürfnisse. Erstens Nachverfolgbarkeit: Zu wissen, wer was und wann geändert hat, verwandelt eine sterile Teamdebatte in eine einfache Überprüfung der Historie. Zweitens Rollback: Wenn eine Regression auftritt, ist das unmittelbare Ziel nicht das Verständnis des Warum, sondern die Wiederherstellung eines bekannten Verhaltens. Drittens Leistungsvergleich: Dies erfordert, dass ältere Versionen genau so ausführbar bleiben wie zuvor, mit ihrem ursprünglichen Modell und seinen Einstellungen. Schließlich Auditierung: Für Systeme, die der DSGVO (General Data Protection Regulation) oder anderen Compliance-Rahmenwerken unterliegen, müssen Sie nachweisen, welche Anweisungen an einem bestimmten Datum galten – ein Screenshot reicht nicht aus.
Katalogstruktur
Die PromptCatalog-Klasse erfüllt diese Bedürfnisse mit minimaler Infrastruktur: Ein Ordner pro Prompt, eine JSON-Datei pro Version, nummeriert sequentiell. Jede Datei bündelt den System-Prompt-Text zusammen mit dem zugehörigen Modell und der Temperatur – ein Prompt, der auf 0,1 abgestimmt ist, und derselbe Prompt bei 0,7 sind nicht dasselbe, und das Festlegen beider zusammen verhindert, dass Text wiederhergestellt wird, während die Einstellungen vergessen werden.
Das Feld status verfolgt den Lebenszyklus. Eine Version beginnt als draft, was Vorbereitung und Tests ohne Beeinflussung des Live-Traffics ermöglicht. Der Aufruf von activate schaltet sie auf active um und demotiert automatisch die vorherige Version auf deprecated, sodass zu jedem Zeitpunkt nur eine Version den Traffic bedient. Diese Methode macht Rollbacks trivial: Die Wiederaktivierung einer früheren Version ist ein einziger Aufruf, keine Bereitstellung. Ihre Anwendung ruft get_active in der Produktion auf, während list_versions Reviews und Audits unterstützt.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Prompt catalog manager with versioning."""
def __init__(self, catalog_dir: str = "prompts/"):
self.catalog_dir = Path(catalog_dir)
self.catalog_dir.mkdir(parents=True, exist_ok=True)
def save_prompt(self, name: str, system_prompt: str,
model: str, temperature: float,
metadata: dict = None) -> str:
"""Saves a new version of a prompt."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Determine version number
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Save
prompt_data = {
"name": name,
"version": version_str,
"created_at": datetime.now().isoformat(),
"model": model,
"temperature": temperature,
"system_prompt": system_prompt,
"metadata": metadata or {},
"status": "draft" # draft | active | deprecated
}
filepath = prompt_dir / f"{version_str}.json"
filepath.write_text(json.dumps(prompt_data, indent=2,
ensure_ascii=False))
return version_str
def get_prompt(self, name: str,
version: str = "latest") -> dict:
"""Retrieves a prompt by name and version."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompt '{name}' not found")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Retrieves the active version of a prompt."""
prompt_dir = self.catalog_dir / name
for filepath in sorted(prompt_dir.glob("v*.json"),
reverse=True):
data = json.loads(filepath.read_text())
if data["status"] == "active":
return data
raise FileNotFoundError(
f"No active version for '{name}'"
)
def activate(self, name: str, version: str):
"""Activates a version and deactivates others."""
prompt_dir = self.catalog_dir / name
for filepath in prompt_dir.glob("v*.json"):
data = json.loads(filepath.read_text())
if data["version"] == version:
data["status"] = "active"
elif data["status"] == "active":
data["status"] = "deprecated"
filepath.write_text(json.dumps(data, indent=2,
ensure_ascii=False))
def list_versions(self, name: str) -> list[dict]:
"""Lists all versions of a prompt."""
prompt_dir = self.catalog_dir / name
versions = []
for filepath in sorted(prompt_dir.glob("v*.json")):
data = json.loads(filepath.read_text())
versions.append({
"version": data["version"],
"status": data["status"],
"created_at": data["created_at"],
"model": data["model"]
})
return versions
Nutzung des Katalogs in Ihrer Anwendung
Auf der Seite des Aufrufers lautet die Regel einfach: Ihr Code enthält keinen Prompt-Text; er fordert die aktive Version vom Katalog an. Dies hält Prompts modifizierbar, ohne den Anwendungscode zu berühren, und verhindert, dass dreißig-Zeilen-Strings mitten in einer Funktion begraben werden. Metadaten, die während der Speicherung gespeichert werden – Autor, Beschreibung, Änderungsprotokoll – haben keinen Einfluss auf die Ausführung, machen die Historie aber sechs Monate später lesbar, wenn niemand mehr weiß, warum die Formulierung geändert wurde.
Das kritische Detail liegt am Ende von classifier_ticket: Die zurückgegebene Antwort enthält prompt_version. Protokollieren Sie dieses Feld mit jedem Ergebnis, und die Analyse von Vorfällen wird möglich – Sie werden wissen, dass die falsch klassifizierten Tickets am Dienstag nachmittag alle von v004 stammten, ohne Bereitstellungszeitstempel abzugleichen.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Save a prompt
catalog.save_prompt(
name="ticket-classifier",
system_prompt="""You are a support ticket classifier.
Categorize each ticket as: bug, feature, question, billing.
Respond in JSON with category, priority (1-5), summary.""",
model="gpt-5.6-terra",
temperature=0.1,
metadata={
"author": "marie.dupont",
"description": "Automatic classification of Zendesk tickets",
"changelog": "Initial version"
}
)
# In production: use the active version
def classifier_ticket(ticket_text: str) -> dict:
"""Classifies a ticket using the active prompt."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperature requires effort none
instructions=prompt_config["system_prompt"],
input=ticket_text,
temperature=prompt_config["temperature"]
)
return {
"result": json.loads(response.output_text),
"prompt_version": prompt_config["version"]
}
Versionierung mit Git
Für Teams speichern Sie Ihre Prompts in einem dedizierten Git-Repository. Der folgende Baum folgt einer einfachen Konvention: Ein Ordner pro Prompt, der seine Definition, Testfälle und Änderungsprotokoll enthält. Tests beiseite zu halten, die sie verifizieren, ist nicht kosmetisch – eine Pull-Request-Änderung modifiziert beides zusammen, und der Prüfer urteilt über die Änderung anhand von Beweisen, nicht anhand der erklärten Absicht.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML ersetzt hier JSON aus einem spezifischen Grund: Prompts sind mehrzeilige Texte, und die |-Syntax zeigt sie genau so an, wie sie gesendet werden, ohne Escaping oder fremde \n-Zeichen. Ein Git-Diff in dieser Datei liest sich wie ein Prosa-Diff – der Prüfer sieht, dass ein Satz hinzugefügt wurde. Das Ausgabe-Schema reist in derselben Datei mit, sodass die vollständige Konfiguration für einen Aufruf in einem einzigen Artefakt passt.
# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
You are a support ticket classifier.
Categorize each ticket as: bug, feature, question, billing.
Respond in JSON with category, priority (1-5), summary.
schema:
type: object
properties:
category:
type: string
enum: [bug, feature, question, billing]
priority:
type: integer
summary:
type: string
required: [category, priority, summary]
additionalProperties: false
Best Practices
Was einen lebendigen Katalog von einem Archiv-Ordner unterscheidet, hängt von ein paar Hausordnungsvorschriften ab. Halten Sie einen Prompt pro Datei: Das Mischen mehrerer Prompts in einem einzigen Dokument macht Diffs unlesbar und Rollbacks unmöglich gezielt auszuführen. Erzwingen Sie ein Änderungsprotokoll, das nicht dokumentiert, was geändert wurde – das zeigt das Diff – sondern warum: “Hinzugefügte Anweisung zu mehrsprachigen Tickets nach Support-Feedback” ist zehn Zeilen technischer Beschreibung wert.
Koppeln Sie systematisch eine Testsuite mit jedem Prompt; sonst werden die Benutzer die ersten sein, die Ihnen sagen, wann eine Änderung etabliertes Verhalten bricht. Leiten Sie Prompt-Änderungen durch denselben Code-Review-Prozess wie den Code selbst: Ein Prompt, der ohne Review in die Produktion geht, erzeugt dieselben Überraschungen wie unüberprüfter Code. Stellen Sie sicher, dass Rollback weniger als eine Minute dauert, und testen Sie es an einem ruhigen Tag, nicht während eines Vorfalls. Markieren Sie schließlich bereitgestellte Versionen mit Tags, um beobachtetes Verhalten eindeutig mit einem bestimmten Repository-Zustand zu verknüpfen.
Testen des Katalogs mit einem Rollback
Richten Sie ein PromptCatalog für drei echte Prompts Ihrer Anwendung ein, und notieren Sie zwei oder drei Versionen jedes Prompts, indem Sie die Anweisungen in kleinen Schritten weiterentwickeln – eine Ton-Anweisung, eine hinzugefügte Kategorie. Die Versionierung beweist ihren Wert bei diesen feingranularen Änderungen, da es genau diese sind, die Sie nicht mehr merken werden, dass Sie sie vorgenommen haben. Richten Sie Aktivierung und Deaktivierung ein, und hängen Sie eine Testsuite an jeden Prompt an.
Beenden Sie mit der lehrreichsten Übung: Aktivieren Sie absichtlich eine degradierte Version, beobachten Sie die Regression über die Tests und führen Sie das Rollback aus, während Sie die Zeit messen. Wenn die Operation mehr als eine Minute dauert, beheben Sie das Verfahren, bevor Sie einen einzigen Prompt zum Katalog hinzufügen – ein langsames Rollback ist kein Rollback, es ist ein prolongierter Vorfall.
Kernaussagen
- Prompts sind Software-Artefakte, die eine Versionierung erfordern
- Jede Version ist eine JSON- oder YAML-Datei mit Metadaten
- Status (draft, active, deprecated) ermöglicht schrittweise Bereitstellung
- Speichern Sie Prompts in Git mit Tests und einem Änderungsprotokoll
- Rollback muss im Falle einer Regression sofort erfolgen