System-Prompts richtig einsetzen

1. Was ein System-Prompt ist und wofür er dient

Ein System-Prompt ist eine Instruktion, die nicht Teil des eigentlichen Nachrichtenverlaufs ist, sondern als eigene, übergeordnete Ebene vor jeder Konversation gesetzt wird. In der Anthropic API existiert dafür ein eigener Parameter namens system, getrennt vom messages-Array. Technisch wird dieser Parameter bei jeder Anfrage neu mitgeschickt, weil die API zustandslos ist, aber für den Nutzer wirkt er wie eine konstante Rahmenbedingung, die über die gesamte Konversation hinweg gilt, ohne dass sie in jeder einzelnen Nachricht wiederholt werden muss.

Für einen Coding-Assistenten definiert der System-Prompt typischerweise die Rolle (etwa: erfahrener PHP- und Magento-Entwickler), den Ton der Antworten und harte Randbedingungen, die unabhängig vom konkreten Task gelten sollen. Ein Beispiel: Wenn jede Antwort mit Strict Types und Constructor Property Promotion arbeiten soll, gehört diese Regel in den System-Prompt statt in jede einzelne Nutzeranfrage. Das reduziert Wiederholung und sorgt dafür, dass die Regel auch dann greift, wenn der Nutzer sie in einer konkreten Anfrage vergisst zu erwähnen.

2. System-Prompt, User-Prompt und CLAUDE.md: drei Ebenen

In der Praxis begegnen Entwicklern drei unterschiedliche Ebenen von Kontext, die leicht verwechselt werden. Der System-Prompt wird von der Anwendung oder dem API-Aufrufer gesetzt und gilt für die gesamte Sitzung. Der User-Prompt ist die konkrete Nachricht in einem einzelnen Konversationsschritt, formuliert von der Person, die gerade mit dem Modell arbeitet. In Claude Code kommt eine dritte Ebene hinzu: Projekt- und Nutzer-Dateien wie CLAUDE.md, die beim Start einer Sitzung automatisch eingelesen und zusammen mit den eingebauten Harness-Instruktionen in den effektiven System-Kontext eingefügt werden.

Der Unterschied ist relevant, weil jede Ebene eine andere Lebensdauer und einen anderen Geltungsbereich hat. Ein System-Prompt-Parameter in der API gilt für exakt die eine Konversation, für die er gesetzt wurde. CLAUDE.md gilt projektweit und über beliebig viele Sitzungen hinweg, solange die Datei im Repository liegt. Wer diese Ebenen sauber trennt, vermeidet, dass projektweite Konventionen versehentlich in einer einzelnen Nutzernachricht landen, wo sie beim nächsten Task wieder verloren gehen.

{
  "model": "claude-sonnet-4-5",
  "system": "You are a senior PHP/Magento 2 developer. Follow PSR-12, use strict_types, prefer constructor property promotion. Never use error suppression (@) or assert() for type narrowing.",
  "messages": [
    { "role": "user", "content": "Erstelle einen ViewModel für die Anzeige von Produktbewertungen." }
  ],
  "max_tokens": 4096
}

3. Coding-Style-Regeln praxisnah formulieren

Coding-Style-Regeln gehören zu den häufigsten Inhalten eines System-Prompts für Entwicklungsaufgaben, weil sie über jede einzelne Anfrage hinweg konstant bleiben sollen. Sinnvoll sind Angaben zur Sprachversion und ihren Feature-Konventionen (PHP 8.4, Strict Types, Constructor Property Promotion), zu verbotenen Mustern (kein assert(), keine Error-Silencing mit @) und zu Pflichtformaten wie PHPDoc-Blöcken. Wichtig ist, jede Regel als knappe, eindeutige Aussage zu formulieren statt als ausführliche Begründung: Das Modell muss die Regel befolgen können, nicht ihre Herkunft verstehen.

Ein häufiger Fehler ist, Regeln zu formulieren, die das Modell ohnehin schon als Best Practice kennt, etwa generische Hinweise wie „schreibe sauberen Code“ oder „achte auf gute Lesbarkeit“. Solche Sätze verbrauchen Platz im System-Prompt, ohne zusätzliches Signal zu liefern, weil sie kein projektspezifisches Wissen enthalten. Wirksamer sind Regeln, die von allgemeinen Konventionen abweichen oder projektspezifisches Wissen kodieren, das das Modell sonst nicht haben kann, etwa den genauen Pfad-Konventionen eines bestimmten Repositories.

import anthropic

client = anthropic.Anthropic()

# Concise, high-signal system prompt for coding style
system_prompt = (
    "You write PHP 8.4 for a Magento 2 / Hyva project. "
    "Rules: strict_types=1, constructor property promotion, "
    "PHPDoc on every public/protected/private method, "
    "no assert(), no @ error suppression, "
    "prefer ViewModels (ArgumentInterface) over Block classes."
)

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    system=system_prompt,
    messages=[
        {"role": "user", "content": "Schreibe ein ViewModel für Cross-Sell-Produkte."}
    ],
)

print(response.content[0].text)

4. Projekt-Konventionen und Architektur-Vorgaben

Neben reinen Coding-Style-Regeln lohnt es sich, projektweite Architektur-Entscheidungen im System-Prompt zu verankern: Plugins statt Preferences, deklaratives Schema statt InstallScripts, Service Contracts statt direkter Repository-Zugriffe. Diese Vorgaben sind für ein Magento-Projekt nicht aus der Trainingsverteilung des Modells allein ableitbar, weil sie projektspezifische Entscheidungen widerspiegeln, die genauso gut anders hätten getroffen werden können. Genau deshalb gehören sie in den System-Prompt statt darauf zu vertrauen, dass das Modell sie „errät“.

Auch Deployment- und Workflow-Konventionen gehören in diese Kategorie: welche Wrapper-Skripte statt direkter Aufrufe verwendet werden sollen, in welcher Reihenfolge Build-Schritte ablaufen, welche Verzeichnisstruktur für Dual-Vendor-Module gilt. Diese Informationen ändern sich selten, betreffen aber nahezu jede Aufgabe im Projekt, was sie zu idealen Kandidaten für einen projektweiten System-Prompt macht statt für eine einzelne Nutzeranfrage.

#!/usr/bin/env bash
# Example: project-level CLAUDE.md as a persistent system-prompt fragment
cat > CLAUDE.md <<'EOF'
# Project conventions (Magento 2 / Hyva)

- Use ViewModels (ArgumentInterface), not Block classes.
- Use Plugins (Interceptors), never Preferences.
- Use db_schema.xml, never InstallScripts.
- Always use the bin/ wrapper scripts, never call php bin/magento directly.
- New modules always ship config.xml, system.xml and acl.xml.
EOF

git add CLAUDE.md
git commit -m "Add project conventions as persistent context for Claude Code"

5. System-Prompts in Claude Code: CLAUDE.md und --append-system-prompt

Claude Code liest CLAUDE.md-Dateien automatisch beim Start einer Sitzung ein, sowohl auf Projektebene als auch aus einem globalen Nutzerverzeichnis, und fügt deren Inhalt zusammen mit den eingebauten Harness-Instruktionen in den effektiven System-Kontext ein. Das ist der Grund, warum Konventionen aus CLAUDE.md für jede Anfrage in diesem Projekt gelten, ohne dass sie im Chat wiederholt werden müssen. Für einmalige, aufgabenspezifische Ergänzungen bietet die Kommandozeile zusätzlich das Flag --append-system-prompt, das eine zusätzliche Instruktion für genau einen Aufruf anhängt, ohne die projektweite Datei dauerhaft zu verändern.

Diese Kombination erlaubt eine sinnvolle Trennung: stabile, langlebige Regeln gehören in CLAUDE.md und werden versioniert im Repository gepflegt, während kurzlebige oder experimentelle Anpassungen über die Kommandozeile oder projektlokale Konfigurationsdateien injiziert werden, ohne die Basis zu verwässern. Wer alles, auch Ausnahmen für einen einzelnen Task, dauerhaft in CLAUDE.md einträgt, riskiert genau das Overloading-Problem, das im nächsten Abschnitt beschrieben wird.

// Node script: combine CLAUDE.md with a task-specific append-system-prompt
import { readFileSync } from "node:fs";
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const projectConventions = readFileSync("CLAUDE.md", "utf8");

// Task-specific addition, equivalent to --append-system-prompt on the CLI
const taskAddition = "For this task only: skip the dual-vendor Abrams copy step.";

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 2048,
  system: `${projectConventions}\n\n${taskAddition}`,
  messages: [
    { role: "user", content: "Refactor the review ViewModel to use the new repository." }
  ],
});

console.log(response.content[0].text);

6. Warum Overloading den System-Prompt schwächt

Ein System-Prompt mit hunderten Einzelregeln fühlt sich für viele Entwickler nach mehr Kontrolle an, bewirkt aber häufig das Gegenteil. Jede zusätzliche Regel konkurriert mit allen anderen um die begrenzte Aufmerksamkeit des Modells innerhalb eines Kontextfensters. Eine Regel, die als Punkt 47 in einer langen Liste steht, wird in der Praxis seltener konsequent befolgt als eine Regel, die als eine von fünf klar hervorgehobenen Kernanforderungen erscheint. Widersprüchliche oder redundante Formulierungen verschärfen das Problem zusätzlich, weil sich das Modell zwischen konkurrierenden Anweisungen entscheiden muss, ohne dass diese Entscheidung vorhersehbar ausfällt.

Hinzu kommt ein handfester technischer Nachteil: Ein längerer System-Prompt wird bei jeder Anfrage erneut mitgeschickt und verbraucht Tokens, was sich in Latenz und Kosten niederschlägt, insbesondere wenn er nicht effizient gecacht wird. Und schließlich wächst mit der Länge auch der Pflegeaufwand. CLAUDE.md-Dateien, die über Monate nur ergänzt und nie bereinigt werden, sammeln veraltete Regeln an, die niemand mehr aktiv nutzt, aber die weiterhin Aufmerksamkeit binden, ohne echten Nutzen zu stiften.

{
  "system": "You are a helpful assistant. Always write clean code. Follow best practices. Use good naming. Be concise but thorough. Write comments where helpful. Use PHP. Follow PSR standards. Use strict_types. Use dependency injection where appropriate. Write tests when possible. Consider edge cases. Handle errors gracefully. Use meaningful variable names. Keep functions small. Avoid duplication. Follow SOLID principles. Use interfaces where sensible. Prefer composition over inheritance. Write documentation. Use version control best practices. Consider performance. Think about security. Validate input. Sanitize output. Use prepared statements. Avoid hardcoding values. Use configuration files. Log important events. Handle exceptions properly. ... (47 more lines)"
}

7. Kurz und hochsignifikant: Prinzipien guter System-Prompts

Ein wirksamer System-Prompt priorisiert explizit zwischen harten Randbedingungen, die niemals verletzt werden dürfen, und weichen Präferenzen, die als Empfehlung gelten. Diese Unterscheidung sollte sich auch strukturell zeigen: kurze Überschriften und Aufzählungen statt langer Fließtext-Absätze, damit die wichtigsten Punkte visuell und semantisch hervortreten, statt in Prosa unterzugehen. Ein System-Prompt ist kein Aufsatz, der überzeugen soll, sondern eine Spezifikation, die befolgt werden soll.

Ein zweites Prinzip: Regeln, die bereits mechanisch durch Linter, PHPStan oder CI-Pipelines durchgesetzt werden, müssen im System-Prompt nicht noch einmal wiederholt werden, weil ein Werkzeug ohnehin zuverlässiger prüft als ein Sprachmodell. Der System-Prompt sollte sich auf das konzentrieren, was sich nicht automatisiert erzwingen lässt: Architekturentscheidungen, Priorisierung, Kommunikationsstil und projektspezifisches Wissen, das keine Regel-Engine kennt. Diese Fokussierung hält den Prompt kurz, ohne an Wirksamkeit zu verlieren.

8. System-Prompts iterativ testen und pflegen

Ein System-Prompt sollte wie Code behandelt werden: versioniert im Repository, mit nachvollziehbaren Änderungen in Pull Requests und mit der gleichen Bereitschaft, überholte Abschnitte zu entfernen, nicht nur neue hinzuzufügen. Wirksamkeit lässt sich nicht allein durch Lesen der Formulierung beurteilen, sondern muss empirisch beobachtet werden: Folgt das Modell über mehrere reale Konversationen hinweg tatsächlich der Regel, oder wird sie in bestimmten Kontexten regelmäßig ignoriert?

Wichtig ist dabei ein realistisches Verständnis davon, was ein System-Prompt leisten kann. Er ist eine probabilistische Steuerung des Modellverhaltens, kein garantierter Vertrag. Wenn eine Regel gelegentlich verletzt wird, ist die naheliegende Reaktion nicht automatisch, noch mehr erklärenden Text hinzuzufügen. Oft hilft eine kürzere, klarere Formulierung der bestehenden Regel mehr als eine zusätzliche Ausnahme oder ein zusätzlicher Absatz, der die eigentliche Kernaussage weiter verdünnt.

9. Systemprompt-Muster im direkten Vergleich

Die folgende Übersicht stellt typische Muster gegenüber, die in der Praxis häufig zu beobachten sind, und zeigt, welche Variante in der Regel zuverlässiger funktioniert.

Der gemeinsame Nenner aller wirksamen Muster: weniger, aber klarer formulierte Regeln, die tatsächlich projektspezifisches Signal enthalten, schlagen lange Listen aus Allgemeinplätzen und mechanisch prüfbaren Details zuverlässig. Das gilt sowohl für System-Prompts in der API als auch für CLAUDE.md-Dateien in Claude Code.

10. Zusammenfassung

Ein System-Prompt ist die persistente Rahmenbedingung eines Coding-Assistenten: Rolle, Coding-Style und projektspezifische Konventionen, die über die gesamte Konversation gelten, ohne bei jeder Anfrage wiederholt zu werden. In Claude Code übernimmt CLAUDE.md diese Funktion auf Projektebene und wird automatisch mit den eingebauten Harness-Instruktionen zusammengeführt, während --append-system-prompt für kurzlebige, aufgabenspezifische Ergänzungen dient. Die größte Gefahr ist nicht ein zu kurzer, sondern ein überladener System-Prompt: Zu viele, unpriorisierte oder redundante Regeln verdünnen das Signal, kosten Tokens und werden in der Praxis seltener zuverlässig befolgt als wenige, klar formulierte Kernanforderungen.

Wirksame System-Prompts unterscheiden explizit zwischen harten Randbedingungen und weichen Präferenzen, verzichten auf Allgemeinplätze, die das Modell ohnehin kennt, verweisen für mechanisch prüfbare Regeln auf Linter und CI statt sie im Prompt zu wiederholen, und werden wie Code gepflegt, also regelmäßig geprüft, gekürzt und versioniert statt nur ergänzt. Wer diese Prinzipien konsequent anwendet, bekommt einen Coding-Assistenten, der Projekt-Konventionen zuverlässiger einhält, nicht weil mehr Text vorhanden ist, sondern weil der vorhandene Text ein höheres Signal-Rausch-Verhältnis hat.

11. FAQ: System-Prompts richtig einsetzen