Prompt-Engineering-Grundlagen für bessere KI-Antworten

1. Warum Prompt-Engineering für Entwickler zählt

Prompt-Engineering ist keine esoterische Zauberformel, sondern die praktische Fähigkeit, eine Aufgabe so eindeutig zu formulieren, dass ein Sprachmodell sie mit möglichst wenig Rückfragen und Fehlinterpretationen lösen kann. Der Unterschied zwischen einem erfahrenen und einem ungeübten Claude-Nutzer zeigt sich selten am Modell selbst, sondern fast immer an der Qualität der Eingabe. Ein Modell kann keine Informationen erraten, die nicht im Kontext stehen, und es kann kein Format einhalten, das nie spezifiziert wurde.

Für Entwickler ist das besonders relevant, weil Code-Aufgaben selten aus einem einzigen, klar abgegrenzten Problem bestehen. Ein Feature betrifft mehrere Dateien, folgt Projektkonventionen, die nirgendwo im Prompt stehen, und muss sich in eine bestehende Architektur einfügen. Wer Prompt-Engineering ernst nimmt, reduziert nicht nur die Anzahl der Korrekturschleifen, sondern bekommt Code, der beim ersten Versuch näher an dem liegt, was tatsächlich gebraucht wird. Die folgenden Abschnitte behandeln die vier wichtigsten Hebel: Format, Kontext, Iteration und konkrete Beispiele, ergänzt um ein reales Vorher-Nachher-Beispiel aus dem Magento-Alltag.

2. Output-Format und Constraints präzise definieren

Ein Modell wählt bei fehlender Vorgabe irgendein plausibles Format, oft eine Mischung aus Erklärtext, Codeblock und Zusammenfassung. Für eine schnelle Konsole ist das lästig, für eine automatisierte Pipeline unbrauchbar. Wer stattdessen explizit festlegt, dass die Antwort ausschließlich ein unified diff sein soll, ohne einleitenden Fließtext, bekommt eine Ausgabe, die sich direkt weiterverarbeiten lässt. Dasselbe gilt für Constraints: Wenn PHP 8.4 mit Constructor Property Promotion Pflicht ist, PHPStan Level 5 fehlerfrei bleiben muss und keine neuen Composer-Abhängigkeiten hinzukommen dürfen, gehört das in den Prompt, nicht in die Hoffnung, dass Claude es errät.

Format-Vorgaben wirken am zuverlässigsten, wenn sie konkret und überprüfbar sind, etwa eine feste JSON-Struktur mit benannten Feldern statt der vagen Bitte um „strukturierte Ausgabe“. Bei mehrteiligen Antworten hilft eine explizite Reihenfolge: zuerst die Analyse, dann der Code, dann eine kurze Liste offener Fragen. Wichtig ist außerdem, negative Constraints klar zu benennen, etwa „keine Kommentare im Code“ oder „keine Erklärung, nur der Patch“. Ein Modell hält sich an Grenzen deutlich zuverlässiger, wenn sie explizit als Verbot formuliert sind, statt implizit aus dem Kontext erschlossen werden zu müssen.

#!/usr/bin/env bash
# Claude Code CLI: explizites Output-Format und harte Constraints im Prompt
claude -p "$(cat <<'EOF'
Aufgabe: Fixe den Bug in app/code/Mironsoft/SeoSuite/Model/MetaGenerator.php,
bei dem leere Produktbeschreibungen einen Fatal Error auslösen.

Format der Antwort:
- Ausschließlich ein unified diff (git diff Format)
- Keine Erklärung, kein Fließtext, kein Codeblock drumherum
- Maximal eine Datei ändern

Constraints:
- PHP 8.4, Constructor Property Promotion beibehalten
- PHPStan Level 5 muss danach fehlerfrei bleiben
- Keine neuen Composer-Abhängigkeiten
- Bestehende PHPDoc-Blöcke nicht entfernen
EOF
)"

3. Kontext liefern statt Codebase-Konventionen vorauszusetzen

Claude kennt die Konventionen eines konkreten Projekts nicht, solange sie nicht im Prompt oder in referenzierten Dateien stehen. Ein häufiger Fehler ist die Annahme, das Modell „wisse schon“, dass in einem Magento-Projekt ViewModels statt Block-Klassen bevorzugt werden oder dass Repositories statt direkter Collection-Zugriffe verwendet werden sollen. Ohne diesen Hinweis generiert das Modell plausiblen, aber projektfremden Code, der zwar funktioniert, aber gegen etablierte Muster verstößt und im Review zurückgewiesen wird.

Der wirksamste Kontext ist selten eine lange Beschreibung in eigenen Worten, sondern Ausschnitte aus dem echten Code: eine bestehende, ähnliche Klasse als Vorbild, die relevante Interface-Definition oder ein kurzer Auszug aus der db_schema.xml. Claude Code liest Dateien direkt und kann bestehende Muster ableiten, wenn man es explizit bittet, „folge dem Muster aus Model/ExistingViewModel.php“. Wichtig ist auch negativer Kontext: zu erwähnen, was nicht mehr verwendet werden soll, etwa dass InstallScripts durch deklaratives Schema ersetzt wurden, verhindert, dass veraltete Trainingsdaten des Modells in den generierten Code einfließen.

#!/usr/bin/env bash
# Projektkontext vor dem eigentlichen Prompt einsammeln, statt ihn zu erraten
echo "=== Bestehendes ViewModel als Vorbild ==="
cat app/code/Mironsoft/SeoSuite/ViewModel/MetaData.php

echo "=== Relevantes Interface ==="
cat app/code/Mironsoft/SeoSuite/Api/MetaGeneratorInterface.php

echo "=== di.xml Ausschnitt für Konvention ==="
grep -A 3 "MetaGeneratorInterface" app/code/Mironsoft/SeoSuite/etc/di.xml

# Diese drei Ausschnitte werden dem Prompt vorangestellt, damit Claude
# das bestehende Muster erkennt, statt eine eigene Struktur zu erfinden

4. Iterative Verfeinerung statt Ein-Schuss-Prompts

Ein weit verbreitetes Missverständnis ist die Erwartung, dass ein einziger, perfekt formulierter Prompt sofort das gewünschte Ergebnis liefert. In der Praxis ist Prompting ein Dialog: Der erste Prompt liefert einen brauchbaren ersten Entwurf, der zweite präzisiert eine Randbedingung, die vorher fehlte, der dritte korrigiert einen konkreten Fehler in der Ausgabe. Diese Schleife ist kein Zeichen für ein schlechtes Modell, sondern der normale Weg, mit dem Menschen auch untereinander Anforderungen klären, nur eben schneller.

Entscheidend ist, wie die Korrektur formuliert wird. „Das ist falsch“ liefert kaum Verbesserung, weil das Modell nicht weiß, welcher Teil falsch ist und warum. Wirksamer ist konkretes Feedback: „Die Methode wirft keine Exception bei einem ungültigen SKU, das muss über InvalidArgumentException laufen, wie im Rest der Klasse.“ Jede Iteration sollte den vorherigen Kontext nicht verlieren, weshalb sich das Arbeiten in derselben Konversation lohnt statt eines Neustarts mit einem längeren, aber isolierten Prompt. Nach drei bis vier erfolglosen Iterationen lohnt sich meist ein Schritt zurück: das ursprüngliche Ziel neu und präziser formulieren, statt weiter nachzubessern.

{
  "iteration_1": {
    "prompt": "Schreibe eine Funktion, die Produktpreise formatiert",
    "problem": "Ergebnis nutzt number_format ohne Währungssymbol und Locale"
  },
  "iteration_2": {
    "prompt": "Nutze Magentos PriceCurrencyInterface statt number_format, Store-Locale beachten",
    "problem": "Rückgabetyp ist string statt float, Rundung nicht konsistent mit Checkout"
  },
  "iteration_3": {
    "prompt": "Rückgabetyp bleibt float für interne Berechnung, Formatierung erst in der ViewModel-Ausgabeschicht, gleiche Rundungslogik wie Quote::getGrandTotal verwenden",
    "result": "Akzeptiert, entspricht bestehendem Muster in Model/Pricing"
  }
}

5. Rollen, Beispiele und Few-Shot-Prompting

Eine Rollenzuweisung wie „Agiere als Senior-PHP-Entwickler mit Magento-2-Schwerpunkt“ verändert den Stil und die Sorgfalt der Antwort messbar, weil sie einen impliziten Qualitätsmaßstab setzt. Wirkungsvoller als eine reine Rollenbeschreibung ist aber Few-Shot-Prompting: ein oder zwei konkrete Beispiele für Eingabe und gewünschte Ausgabe im selben Prompt. Statt zu beschreiben, wie ein PHPDoc-Block aussehen soll, zeigt ein vollständiges Beispiel eines bereits korrekt dokumentierten Methodenkopfs aus dem eigenen Projekt, was tatsächlich erwartet wird.

Few-Shot-Beispiele lohnen sich besonders bei Aufgaben mit hoher Formatsensibilität, etwa der Generierung von Testfällen, Übersetzungsdateien oder strukturierten Konfigurationsdateien, wo kleine Abweichungen im Format zu echten Fehlern führen. Bei kreativeren oder offeneren Aufgaben, etwa der Architekturplanung für ein neues Modul, bremsen zu viele starre Beispiele eher, weil das Modell dazu neigt, die Beispiele zu kopieren statt die zugrunde liegende Regel zu verallgemeinern. Ein bis drei gut gewählte Beispiele sind meist wirkungsvoller als fünf ähnliche.

# Few-shot prompt: two concrete examples steer the output format
# more reliably than a verbal description alone
from anthropic import Anthropic

client = Anthropic()

system_prompt = "You are a senior PHP developer following strict PSR-12 " \
                "and Magento 2 coding conventions."

few_shot_examples = """
Example 1:
Input: getPriceInclTax(int $productId): float
Output:
/**
 * Returns the product price including tax for the given product id.
 *
 * @param int $productId
 * @return float
 * @throws NoSuchEntityException
 */

Example 2:
Input: isEligibleForDiscount(CartInterface $cart): bool
Output:
/**
 * Checks whether the given cart is eligible for the active discount rule.
 *
 * @param CartInterface $cart
 * @return bool
 */
"""

response = client.messages.create(
    model="claude-sonnet-4-5",
    system=system_prompt,
    max_tokens=1024,
    messages=[
        {"role": "user", "content": f"{few_shot_examples}\n\nInput: calculateShippingCost(QuoteInterface $quote): float\nOutput:"}
    ]
)

print(response.content[0].text)

6. CLAUDE.md als projektweiter Kontext

Ein System-Prompt oder eine projektweite Kontextdatei wie CLAUDE.md löst ein wiederkehrendes Problem: Konventionen, die in jedem einzelnen Prompt neu erklärt werden müssten, werden stattdessen einmal festgelegt und automatisch in jede Konversation geladen. In Claude Code übernimmt die CLAUDE.md im Projekt-Root genau diese Rolle. Dort stehen Tech-Stack, Coding-Standards, verbotene Patterns und projektspezifische Workflows, sodass jeder einzelne Prompt kürzer und der Kontext trotzdem vollständiger wird.

Der Nutzen zeigt sich besonders bei Teams: Ohne zentrale Kontextdatei entwickelt jeder Entwickler eigene, leicht abweichende Prompt-Gewohnheiten, was zu inkonsistentem KI-generiertem Code führt. Mit einer gepflegten CLAUDE.md greifen alle auf dieselbe Grundlage zu, unabhängig davon, wer den Prompt formuliert. Wichtig ist, die Datei schlank zu halten und nur stabile, projektweit gültige Regeln aufzunehmen, nicht aufgabenspezifische Details. Eine zu lange, unspezifische Kontextdatei verwässert die wichtigen Punkte und wird vom Modell schwerer priorisiert als ein kurzer, klar strukturierter Katalog.

7. Häufige Fehler beim Prompten von Code-Aufgaben

Der häufigste Fehler ist ein zu breiter Auftrag in einem einzigen Prompt, etwa „Baue das komplette Checkout-Modul“. Ein Modell liefert dazu zwangsläufig eine oberflächliche, generische Lösung, weil zu viele Entscheidungen implizit getroffen werden müssen. Kleinere, klar abgegrenzte Aufgaben mit expliziten Erfolgskriterien liefern zuverlässigere Ergebnisse und lassen sich einfacher überprüfen. Ein zweiter häufiger Fehler ist das Fehlen von Abnahmekriterien: Ohne eine Definition, wann eine Aufgabe als erledigt gilt, prüft das Modell sein eigenes Ergebnis nicht gegen einen klaren Maßstab.

Ein dritter Fehler ist blindes Vertrauen in generierten Code ohne Review, gerade bei sicherheitsrelevanten Bereichen wie SQL-Queries, Zugriffskontrollen oder Preisberechnungen. Ein Modell kann plausiblen, syntaktisch korrekten Code erzeugen, der trotzdem eine Sicherheitslücke oder einen Logikfehler enthält, weil es kein echtes Verständnis der Laufzeitumgebung hat, sondern Muster aus Trainingsdaten reproduziert. Ein vierter, oft übersehener Fehler: veraltete oder widersprüchliche Informationen im Kontext, etwa ein Prompt, der auf eine bereits gelöschte Klasse verweist. Das Modell versucht dann, die Widersprüche plausibel aufzulösen, statt nachzufragen, was zu falschen Annahmen führt.

8. Vorher-Nachher: aus einem vagen Prompt wird ein präziser

Der Unterschied zwischen einem vagen und einem präzisen Prompt lässt sich am besten an einem konkreten Beispiel zeigen. Die Ausgangslage: Ein Entwickler braucht ein Dropdown-Menü für die Mini-Cart in einem Hyvä-Theme, das sich per Klick öffnet und bei Klick außerhalb schließt. Ein vager Prompt wie „Baue ein Dropdown für den Warenkorb mit Alpine.js“ liefert funktionierenden, aber unvollständigen Code: keine Tastatursteuerung, keine ARIA-Attribute, kein Schließen bei Escape, und der Alpine-Store folgt nicht dem im Projekt bereits etablierten Muster für globale UI-Zustände.

Der präzise Prompt benennt stattdessen das gewünschte Verhalten, die Barrierefreiheit-Anforderungen, das bestehende Alpine-Store-Muster als Vorbild und die Formatvorgabe für die Antwort. Das Ergebnis unterscheidet sich nicht nur im Detail, sondern strukturell: Statt einer isolierten Lösung entsteht Code, der sich nahtlos in bestehende Patterns einfügt und beim ersten Versuch review-fähig ist. Der Mehraufwand beim Formulieren des Prompts liegt bei wenigen Minuten, die eingesparte Korrekturzeit typischerweise bei einem Vielfachen davon.

// VORHER: Ergebnis aus dem vagen Prompt "Baue ein Dropdown für den
// Warenkorb mit Alpine.js" - funktioniert, ignoriert aber Projektkonventionen
function miniCartDropdown() {
  return {
    open: false,
    toggle() { this.open = !this.open; }
    // Kein Escape-Handler, keine ARIA-Attribute, kein Klick-außerhalb-Schließen,
    // eigener lokaler State statt des bestehenden Alpine.store('ui') Musters
  };
}

// NACHHER: Ergebnis aus dem präzisen Prompt, der Barrierefreiheit,
// das bestehende Store-Pattern und Klick-außerhalb explizit fordert
document.addEventListener('alpine:init', () => {
  Alpine.data('miniCartDropdown', () => ({
    init() {
      this.$watch('$store.ui.miniCartOpen', (open) => {
        if (open) this.$refs.firstItem?.focus();
      });
    },
    toggle() {
      Alpine.store('ui').miniCartOpen = !Alpine.store('ui').miniCartOpen;
    },
    close() {
      Alpine.store('ui').miniCartOpen = false;
    }
  }));
});
// Template: @click.outside="close()" @keydown.escape.window="close()"
// role="menu" aria-expanded, konsistent mit bestehendem Alpine.store('ui')

9. Prompt-Patterns im direkten Vergleich

Die folgende Übersicht fasst die häufigsten Entwickleranfragen zusammen und zeigt, wie sich ein vager Prompt in ein präzises, überprüfbares Prompt-Pattern übersetzen lässt. Der Unterschied ist selten die Länge des Prompts, sondern die Konkretheit der Vorgaben.

Auffällig ist, dass das präzise Prompt-Pattern in jeder Zeile nicht grundsätzlich länger ist als der vage Prompt, sondern gezielter. Statt fünf zusätzlicher Sätze allgemeiner Höflichkeit oder Kontextlosigkeit stehen dort zwei bis drei konkrete, überprüfbare Angaben. Genau das lässt sich trainieren: Vor jedem Prompt kurz zu fragen, welches Format, welcher Kontext und welches Abnahmekriterium fehlen würden, wenn ein Kollege statt eines Modells die Aufgabe übernehmen müsste.

10. Zusammenfassung

Die Grundlagen des Prompt-Engineering lassen sich auf wenige, aber wirkungsvolle Prinzipien reduzieren: Format und Constraints explizit benennen, statt sie zu erhoffen. Echten Projektkontext liefern, etwa bestehenden Code als Vorbild, statt anzunehmen, das Modell kenne die eigenen Konventionen. Iterativ verfeinern, statt einen einzigen perfekten Prompt zu erwarten, und Feedback konkret statt pauschal formulieren. Few-Shot-Beispiele gezielt bei formatsensiblen Aufgaben einsetzen, eine gepflegte CLAUDE.md als stabilen, projektweiten Kontext nutzen.

Der größte Hebel liegt selten in einer einzelnen Technik, sondern in der Kombination: ein präzise formuliertes Ziel mit klarem Format, angereichert um relevanten Kontext aus dem echten Projekt, verfeinert über zwei bis drei gezielte Iterationen. Wer generierten Code trotzdem konsequent reviewt, gerade bei sicherheits- und geschäftskritischer Logik, nutzt Claude als Werkzeug zur Beschleunigung, nicht als Ersatz für fachliches Urteilsvermögen.

11. FAQ: Prompt-Engineering-Grundlagen