Prompts iterieren und systematisch verbessern

1. Warum Prompt-Entwicklung wie Debugging funktioniert

Ein erster Prompt-Entwurf funktioniert selten auf Anhieb vollständig richtig, genauso wenig wie ein erster Code-Entwurf beim ersten Lauf fehlerfrei durchläuft. Der Unterschied liegt darin, wie Entwickler mit diesem Umstand umgehen: Bei Code ist ein iterativer Debugging-Prozess selbstverständlich, bei Prompts wird er häufig übersprungen. Ein Prompt wird geschrieben, einmal ausprobiert, als „funktioniert grundsätzlich" akzeptiert und danach nie wieder angefasst, selbst wenn er in der Praxis regelmäßig unerwünschte Ausgaben liefert.

Wer Prompt-Entwicklung stattdessen wie einen Debugging-Zyklus behandelt, gewinnt Struktur zurück: Eine Hypothese formulieren, warum die Ausgabe von der Erwartung abweicht, gezielt eine Variante testen, das Ergebnis beobachten und die nächste Anpassung darauf aufbauen. Der wichtigste Unterschied zum klassischen Debugging ist, dass Sprachmodelle nicht deterministisch arbeiten. Eine einzelne abweichende Ausgabe kann Zufall sein, ein wiederkehrendes Muster über mehrere Läufe hinweg ist ein echtes Signal. Diese Unterscheidung ist die Grundlage jeder systematischen Prompt-Verbesserung.

2. Der Iterationszyklus: Hypothese, Test, Verfeinerung

Der praktische Zyklus besteht aus vier Schritten, die sich beliebig oft wiederholen lassen. Erstens: genau beobachten, welcher Teil der Ausgabe von der Erwartung abweicht, nicht nur pauschal „das Ergebnis ist schlecht" notieren, sondern konkret benennen, was fehlt, was zu viel ist oder welches Format nicht passt. Zweitens: eine Hypothese formulieren, warum das passiert, etwa weil ein Begriff im Prompt mehrdeutig ist, weil Kontext fehlt oder weil zwei Anweisungen sich widersprechen. Drittens: genau eine Änderung testen, die diese Hypothese adressiert. Viertens: das neue Ergebnis mit dem vorherigen vergleichen und entscheiden, ob die Hypothese bestätigt wurde.

Entscheidend ist, pro Iteration nur eine Variable zu ändern. Wer gleichzeitig die Formatvorgabe, den Kontextumfang und die Beispiele anpasst, kann bei einer Verbesserung nicht mehr sagen, welche Änderung tatsächlich gewirkt hat, und riskiert bei der nächsten Aufgabe, denselben Fehler erneut zu machen. Eine kurze Notiz je Iteration, was geändert wurde, warum, und welches Ergebnis das brachte, macht den Prozess nachvollziehbar und beschleunigt spätere Anpassungen erheblich, weil man auf bereits geprüfte Hypothesen zurückgreifen kann.

3. Ein Baseline-Prompt schreiben und Fehlschläge dokumentieren

Der Ausgangspunkt jeder Iteration ist ein bewusst einfacher Baseline-Prompt: die direkteste Formulierung der Aufgabe, ohne Tricks, ohne ausgefeilte Rollenbeschreibung, ohne Few-Shot-Beispiele. Dieser Prompt wird gegen mehrere echte Eingaben getestet, nicht nur gegen eine einzelne, die zufällig gerade griffbereit war. Jede Abweichung wird konkret dokumentiert, etwa „ignoriert die Zeilennummer im Diff" oder „antwortet auf Englisch, obwohl der Code deutsche Kommentare enthält", statt pauschal „nicht gut genug".

Diese Baseline dient als Referenzpunkt für alle folgenden Vergleiche. Ohne dokumentierten Ausgangszustand lässt sich später nicht mehr feststellen, ob eine Änderung wirklich eine Verbesserung war oder nur subjektiv besser wirkt, weil man sich an den vorherigen Fehler nicht mehr genau erinnert. In der Praxis reicht dafür ein einfacher Ordner im Projekt-Repository mit Prompt-Versionen und einer kurzen Log-Datei, die jede Iteration mit Datum, Änderung und Beobachtung festhält.

#!/usr/bin/env bash
# run-prompt-test.sh - runs the current prompt version against sample inputs
# and stores every run for later comparison
set -euo pipefail

PROMPT_VERSION="v3"
PROMPT_FILE="prompts/code-review/${PROMPT_VERSION}.txt"
SAMPLES_DIR="prompts/code-review/samples"
RESULTS_DIR="prompts/code-review/results/${PROMPT_VERSION}"
TIMESTAMP="$(date +%Y%m%d-%H%M%S)"

mkdir -p "$RESULTS_DIR"

for sample in "$SAMPLES_DIR"/*.diff; do
  name="$(basename "$sample" .diff)"
  echo "[RUN] ${PROMPT_VERSION} on ${name}"

  claude --print \
    --append-system-prompt "$(cat "$PROMPT_FILE")" \
    < "$sample" > "${RESULTS_DIR}/${name}-${TIMESTAMP}.txt"
done

echo "[DONE] Results stored in ${RESULTS_DIR}"
echo "Compare against previous run with: diff results/v2/*.txt results/v3/*.txt"

4. Typische Ursachen für Missverständnisse erkennen

Nach mehreren Iterationsrunden über verschiedene Aufgaben hinweg wiederholen sich bestimmte Ursachen für Missverständnisse immer wieder. Die häufigste ist ein mehrdeutiger Begriff ohne Definition: „kurz zusammenfassen" bedeutet für den einen zwei Sätze, für den anderen einen Absatz, und Claude wählt ohne weitere Vorgabe eine eigene Interpretation. Ähnlich häufig fehlt eine explizite Formatvorgabe, sodass die Antwort mal als Fließtext, mal als Liste, mal als Tabelle kommt, obwohl nachgelagerte Verarbeitung ein festes Format braucht.

Weitere wiederkehrende Ursachen sind implizite Annahmen über Kontext, den das Modell schlicht nicht hat, etwa Projektkonventionen, die nur im Kopf des Entwicklers existieren, sowie widersprüchliche Anweisungen wie „sei präzise" und „erkläre ausführlich" im selben Prompt. Auch Few-Shot-Beispiele können schaden, wenn sie ein Muster verankern, das für den konkreten Fall nicht passt. Sobald ein Muster mehrfach auftritt, lohnt sich eine kurze Checkliste, die vor jedem neuen Prompt geprüft wird. Das verhindert wiederholte Fehler und macht die erste Hypothese in künftigen Iterationen deutlich treffsicherer.

5. Eine Prompt-Bibliothek für wiederkehrende Aufgaben aufbauen

Ein Prompt, der nach mehreren Iterationen zuverlässig funktioniert, sollte nicht im Chat-Verlauf verloren gehen, sondern als versionierte Datei im Projekt-Repository landen, ergänzt um Metadaten: für welche Aufgabe er gedacht ist, wann er zuletzt gegen das Testset geprüft wurde, welche bekannten Grenzen er hat und mit welcher Modellversion er getestet wurde. Diese Bibliothek wird wie Code behandelt, inklusive Pull-Request-Review, bevor eine neue Version die alte ersetzt.

In der Praxis hat sich eine einfache Struktur bewährt: ein Verzeichnis pro Aufgabentyp, darin die aktuelle Prompt-Version als Textdatei und eine begleitende Metadaten-Datei mit Testfällen und erwarteten Mustern. Neue Teammitglieder greifen so auf bereits geprüfte Prompts zurück, statt bei jeder wiederkehrenden Aufgabe wie Commit-Message-Generierung oder Code-Review erneut bei null anzufangen und dieselben Missverständnis-Muster erneut zu durchlaufen.

{
  "task": "php-code-review",
  "version": "v3",
  "model_tested": "claude-sonnet-4-5",
  "last_verified": "2026-07-08",
  "prompt_file": "prompts/code-review/v3.txt",
  "output_format": "json-array-of-findings",
  "known_limitations": [
    "flags missing PHPDoc even on trivial private getters",
    "does not detect N+1 queries across repository boundaries"
  ],
  "test_cases": [
    { "input": "samples/order-repository.diff", "min_findings": 1 },
    { "input": "samples/clean-refactor.diff", "min_findings": 0 },
    { "input": "samples/sql-injection-risk.diff", "min_findings": 1, "must_contain": "sql injection" }
  ],
  "changelog": [
    { "version": "v1", "change": "initial generic review prompt" },
    { "version": "v2", "change": "added explicit review criteria" },
    { "version": "v3", "change": "added output format and excluded pure style issues" }
  ]
}

6. Praxisbeispiel: Schritt-für-Schritt-Iteration eines Code-Review-Prompts

Ein konkretes Beispiel macht den Zyklus greifbar. Version 1 lautete schlicht „Review this PHP code". Das Ergebnis: überwiegend Stilkommentare zu Einrückung und Variablennamen, aber keine der beiden echten Sicherheitslücken im Testdiff wurden erwähnt. Hypothese: Ohne konkrete Kriterien wählt das Modell die naheliegendsten, oberflächlichsten Beobachtungen. Version 2 ergänzte explizite Kriterien: Sicherheit, N+1-Queries, Magento-Coding-Standards. Ergebnis: deutlich relevantere Funde, aber das Ausgabeformat variierte zwischen Fließtext, nummerierter Liste und gelegentlich Markdown-Tabellen, was die automatisierte Weiterverarbeitung erschwerte.

Version 3 fügte ein explizites Ausgabeformat mit Beispiel-Output hinzu (ein JSON-Array mit Schweregrad, Zeile und Beschreibung). Das Format war ab da konsistent, aber es tauchten neue False Positives zu reinen Formatierungsfragen auf, die das Team bewusst nicht interessierten. Version 4 löste das mit einer expliziten Ausschlussregel: „Ignoriere reine Stilfragen wie Einrückung oder Leerzeichen, das übernimmt der Linter." Jede dieser vier Versionen wurde nicht nur gegen den einen ursprünglichen Fall getestet, sondern gegen ein festes Set von acht realen Diffs, um sicherzustellen, dass eine Verbesserung an einer Stelle nicht an anderer Stelle neue Probleme erzeugte.

"""
prompt_eval.py - runs multiple prompt versions against a fixed test set
and reports which cases pass the defined assertions.
"""
import json
from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

def run_prompt(prompt_text: str, diff_content: str) -> str:
    """Send one review prompt with a code diff and return the raw response text."""
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        system=prompt_text,
        messages=[{"role": "user", "content": diff_content}],
    )
    return response.content[0].text

def evaluate_version(version_dir: Path) -> None:
    """Run one prompt version against all configured test cases and print results."""
    meta = json.loads((version_dir / "meta.json").read_text())
    prompt_text = (version_dir / "prompt.txt").read_text()

    passed, failed = 0, 0
    for case in meta["test_cases"]:
        diff_content = Path(case["input"]).read_text()
        output = run_prompt(prompt_text, diff_content)

        findings = json.loads(output) if output.strip().startswith("[") else []
        ok = len(findings) >= case["min_findings"]
        if case.get("must_contain"):
            ok = ok and case["must_contain"] in output.lower()

        passed += ok
        failed += not ok
        print(f"  {'PASS' if ok else 'FAIL'} - {case['input']}")

    print(f"{meta['version']}: {passed} passed, {failed} failed")

if __name__ == "__main__":
    evaluate_version(Path("prompts/code-review/v4"))

7. Systematisch mit mehreren Beispielen statt Einzelfällen testen

Ein häufiger Fehler bei der Prompt-Iteration ist, eine Anpassung nur gegen den einen Fall zu testen, der den Anstoß zur Änderung gegeben hat. Das Risiko: Der Prompt wird für genau diesen Fall optimiert und verschlechtert sich gleichzeitig bei anderen, zuvor korrekt behandelten Eingaben, ohne dass das auffällt, weil niemand den Rest erneut prüft. Ein festes Testset von mindestens fünf bis zehn diversen Fällen inklusive Randfällen wie leere Eingabe, ungewöhnlich lange Eingabe oder mehrdeutige Grenzfälle deckt das zuverlässig auf.

Praktisch bedeutet das, das komplette Testset bei jeder Prompt-Änderung automatisiert erneut laufen zu lassen, nicht nur den einen Fall, der aktuell im Fokus steht. Ein einfaches Skript, das alle Testfälle durchläuft und die Ergebnisse mit den vorherigen vergleicht, macht diesen Aufwand vernachlässigbar gegenüber dem Risiko einer unbemerkten Regression. Wichtig ist, das Testset selbst zu pflegen: Sobald eine neue Art von Missverständnis auftaucht, wird ein entsprechender Fall dauerhaft ergänzt, damit derselbe Fehler nicht unbemerkt zurückkehrt.

#!/usr/bin/env bash
# eval-suite.sh - runs the full regression test set against a prompt version
# and prints a pass/fail summary instead of relying on a single sample
set -euo pipefail

VERSION="${1:?Usage: eval-suite.sh <version>}"
PROMPT_DIR="prompts/code-review/${VERSION}"
CASES_DIR="prompts/code-review/testset"

pass_count=0
fail_count=0

for case_file in "$CASES_DIR"/*.json; do
  case_name="$(basename "$case_file" .json)"
  expected_min="$(jq -r '.min_findings' "$case_file")"
  input_file="$(jq -r '.input' "$case_file")"

  output="$(claude --print --append-system-prompt "$(cat "$PROMPT_DIR/prompt.txt")" < "$input_file")"
  actual_count="$(echo "$output" | jq 'length' 2>/dev/null || echo 0)"

  if (( actual_count >= expected_min )); then
    echo "[PASS] $case_name"
    ((pass_count++))
  else
    echo "[FAIL] $case_name (expected >= $expected_min, got $actual_count)"
    ((fail_count++))
  fi
done

echo "Result: ${pass_count} passed, ${fail_count} failed for ${VERSION}"

8. Versionierung und Team-Workflow für Prompts

Prompts, die produktiv genutzt werden, verdienen denselben Workflow wie Code: Versionierung in Git, Pull-Request-Review durch ein zweites Paar Augen und ein Changelog, das begründet, warum eine Version geändert wurde. Das ist besonders wichtig, weil Prompt-Änderungen selten offensichtlich sind, ein einzelnes zusätzliches oder entferntes Wort kann das Verhalten spürbar verschieben, ohne dass der Diff im Code-Review auf den ersten Blick auffällig wirkt.

Ein zweiter, oft übersehener Aspekt ist der Modellwechsel: Wenn ein Team auf eine neue Claude-Version umstellt, sollten alle produktiv genutzten Prompts erneut gegen das gepflegte Testset laufen, weil sich das Antwortverhalten zwischen Modellversionen leicht ändern kann, selbst wenn der Prompt-Text identisch bleibt. In der CI-Pipeline lässt sich das automatisieren: Ein Regressionstest läuft bei jedem Merge gegen definierte Referenzausgaben und meldet Abweichungen als Warnung statt als harten Build-Abbruch, weil die Ausgaben eines Sprachmodells naturgemäß nicht Zeichen für Zeichen deterministisch sind.

// ci-prompt-regression.js - Node script for CI: compares current prompt
// output against stored golden references and flags drift as a warning
import Anthropic from "@anthropic-ai/sdk";
import { readFileSync, readdirSync } from "node:fs";
import path from "node:path";

const client = new Anthropic();
const versionDir = "prompts/commit-message/v2";
const goldenDir = path.join(versionDir, "golden");

async function checkDrift() {
  const promptText = readFileSync(path.join(versionDir, "prompt.txt"), "utf8");
  let driftCount = 0;

  for (const file of readdirSync(goldenDir)) {
    const diffInput = readFileSync(path.join(goldenDir, file, "input.diff"), "utf8");
    const expected = readFileSync(path.join(goldenDir, file, "expected.txt"), "utf8").trim();

    const response = await client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 256,
      system: promptText,
      messages: [{ role: "user", content: diffInput }],
    });

    const actual = response.content[0].text.trim();
    if (!actual.toLowerCase().includes(expected.toLowerCase().slice(0, 20))) {
      console.warn(`[DRIFT] ${file}: expected pattern not found in output`);
      driftCount++;
    }
  }

  console.log(`Checked ${readdirSync(goldenDir).length} cases, ${driftCount} drifted`);
  // Warning only, never a hard exit(1): non-determinism is expected here
}

checkDrift();

9. Prompt-Iterationsmuster im Vergleich

Die folgende Übersicht fasst zusammen, worin sich unsystematisches Prompt-Tüfteln von einer strukturierten Debugging-Schleife konkret unterscheidet, und welchen praktischen Vorteil die systematische Variante jeweils bringt.

Auffällig an der Tabelle: Keine der systematischen Varianten erfordert exotisches Tooling. Ein Testverzeichnis, eine Log-Datei und ein kurzes Skript reichen aus, um von Zufallstreffern zu einem nachvollziehbaren, wiederholbaren Prozess zu wechseln. Der Aufwand lohnt sich vor allem bei Prompts, die mehr als einmal genutzt werden, etwa in wiederkehrenden Reviews, automatisierten Commit-Nachrichten oder Support-Antworten.

10. Zusammenfassung

Systematisches Prompt-Iterieren löst ein Grundproblem, das bei einmalig geschriebenen Prompts unweigerlich auftritt: Qualität schwankt, Fehler wiederholen sich, und Verbesserungen lassen sich nicht mehr von Zufall unterscheiden. Der Debugging-Zyklus aus Hypothese, gezieltem Test und Verfeinerung bringt hier dieselbe Struktur, die sich beim klassischen Code-Debugging seit Jahrzehnten bewährt hat, angepasst an die Nicht-Determinismus-Eigenschaft von Sprachmodellen. Eine dokumentierte Baseline, ein festes Testset mit mehreren diversen Fällen und eine versionierte Prompt-Bibliothek machen aus einzelnen Erfolgserlebnissen einen wiederholbaren Prozess.

Der größte Hebel liegt darin, wiederkehrende Muster hinter Missverständnissen zu erkennen, mehrdeutige Begriffe, fehlende Formatvorgaben, widersprüchliche Anweisungen, und diese Erkenntnisse als Checkliste für künftige Prompts festzuhalten. In Teams zahlt sich zusätzlich aus, Prompts wie Code zu behandeln: mit Versionierung, Review und Regressionstests bei jedem Modellwechsel. Der Aufwand ist überschaubar, der Effekt aber spürbar, besonders bei Prompts, die täglich in Reviews, Commit-Nachrichten oder Support-Antworten produktiv genutzt werden.

11. FAQ: Prompts iterieren und systematisch verbessern