Der komplette Guide zum Schreiben von Agent System Prompts — Lektionen aus dem Reverse-Engineering von Claude Code

Ich habe den System-Prompt von Claude Code dekompiliert, den Source Code von DeepAgents analysiert und meinen eigenen AI-Agenten von Grund auf neu gebaut. Die meisten Prompt-Guides sind einfach nur heiße Luft.

Gerade spielt sich in der KI-Welt eine kollektive Täuschung ab.

Jedes Tutorial erzählt dir, du sollst System Prompts schreiben, als würdest du einen Zauberspruch weben — finde einfach die richtige Beschwörungsformel und das Modell wird gehorchen. "Du bist ein EXTREM TALENTIERTER Senior Engineer mit 20 Jahren Erfahrung..." Kommt dir das bekannt vor?

Ich habe die letzten Monate damit verbracht, VibeCom zu bauen, einen KI-Startup-Advisor, der tiefgehende Marktforschung betreibt und Analysen auf VC-Niveau erstellt. Auf diesem Weg habe ich den System Prompt von Claude Code reverse-engineered, mich durch den Middleware-Source-Code von DeepAgents gegraben und mehr API-Credits verbrannt, als ich gerne zugeben würde. Die größte Lektion? Das meiste, was die Leute bei System Prompts für wichtig halten, ist es gar nicht. Und über die Dinge, die wirklich zählen, spricht fast niemand.

Dieser Post ist das komplette Playbook — kein 5-Minuten-Überblick, sondern alles, was ich gerne gewusst hätte, bevor ich angefangen habe. Hol dir einen Kaffee.

1. Design-Philosophie: Vertraue dem Modell

"An agent is a model. Not a framework. Not a prompt chain." — shareAI-lab/learn-claude-code

Dieser Gedanke hat für mich alles verändert. Das LLM weiß bereits, wie man logisch schlussfolgert, plant und ausführt. Dein System Prompt bringt ihm nicht das Denken bei — er richtet lediglich die Umgebung ein, in der es arbeiten soll.

Stell es dir vor, als würdest du einen Senior Engineer einstellen. Du gibst ihm keine 20-Punkte-Checkliste für jede einzelne Aufgabe. Du sagst ihm: Das sind wir, das sind die Grenzen, so sieht gute Arbeit aus. Und dann gehst du ihm aus dem Weg.

Dein System Prompt hat genau vier Aufgaben:

Sag ihm, wer es ist — Rolle und Identität
Zeig ihm, wo die Grenzen sind — Sicherheitsbeschränkungen (Safety Constraints)
Definiere, wie gute Arbeit aussieht — Qualitätsstandards
Gib ihm Werkzeuge — Fähigkeiten und Wissen

Das war's. Alles andere ist nur Noise.

Das Harness-Mindset

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Dein System Prompt ist das Betriebshandbuch für dieses Rahmengerüst (Harness). Du entwirfst keine starre Pipeline — du entwirfst eine Umgebung, in der das Modell autonom seine beste Arbeit leisten kann.

Schreibe deinen System Prompt nicht wie ein Flussdiagramm. Das Modell wird die Ausführungsreihenfolge selbst bestimmen.

2. Prompt-Struktur und Reihenfolge der Abschnitte

Das empfohlene Layout (Reverse-Engineered aus Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Read first, anchors behavior
│ 2. Security & Safety                         │  ← IMPORTANT markers, non-negotiable
│ 3. Tone & Style                              │  ← Controls output format
│ 4. Core Workflow                             │  ← How to do the work
│ 5. Tool Usage Policy                         │  ← Tool selection priorities
│ 6. Domain Knowledge                          │  ← On-demand, not pre-loaded
│ 7. Environment Info                          │  ← Runtime context, dynamically injected
│ 8. Reminders                                 │  ← Re-state critical rules
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Not editable, usually very long
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Warum diese Reihenfolge wichtig ist

LLMs haben eine U-förmige Aufmerksamkeitskurve — sie schenken dem Anfang und dem Ende deines Prompts die meiste Aufmerksamkeit und schalten in der Mitte oft ab. Das ist der "Lost-in-the-Middle"-Effekt, und er ist gut dokumentiert.

Identität + Sicherheit ganz oben: Das Modell etabliert zuerst Rolle und Grenzen (Primacy-Effekt)
Kern-Workflow in der oberen Mitte: Dein wichtigster Abschnitt — wie der Agent seine Arbeit erledigt
Tool-Definitionen werden nach deinem Prompt vom System injiziert: Die Tool-Definitionen von Claude Code fressen ca. 11.438 Tokens. Das bedeutet, dass dein benutzerdefinierter Inhalt tatsächlich näher am Anfang landet, als du erwarten würdest — was der Einhaltung der Regeln hilft
Erinnerungen ganz unten: Nutze den Recency-Bias (Rezenzeffekt), um kritische Regeln zu verstärken

3. Das Schreiben der einzelnen Abschnitte

3.1 Identität — Wer ist dieser Agent?

Ziel: Verankere die Rolle des Modells in 1-3 Sätzen.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Richtlinien:

Halte es kurz — maximal 1-3 Sätze
Benenne die Rolle explizit (hilft dem Modell, Kontexte zu unterscheiden)
Nenne die Kernverantwortung ("hilft bei X"), nicht ein vages "du bist ein hilfreicher Assistent"
Erwähne SDK/Plattform, falls zutreffend ("built on Anthropic's Claude Agent SDK")

Anti-Patterns:

"Du bist ein hilfreicher, harmloser und ehrlicher KI-Assistent" — zu generisch, kein Rollenanker
Ein ganzer Absatz voller Hintergrundgeschichte und Lore — verschwendet Tokens, das Modell braucht keine Charakterentwicklung

3.2 Sicherheit & Schutz — Die harten Grenzen

Ziel: Setze unumstößliche Verhaltensgrenzen.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Richtlinien:

Nutze das IMPORTANT: Präfix — Claudes Training zur Anweisungshierarchie gibt dem zusätzliches Gewicht
Verwende absolute Sprache: NEVER, MUST NOT, Refuse to
Gib sowohl an, was erlaubt ist, ALS AUCH, was verboten ist (bidirektionale Einschränkungen sind klarer)
Platziere dies ganz oben, nicht irgendwo in der Mitte versteckt
Wiederhole kritische Sicherheitsregeln am Ende — Claude Code macht genau das

Warum wiederholen? Primacy-Effekt (Anfang) + Recency-Effekt (Ende) = doppelte Verstärkung. Die Sicherheitserklärung von Claude Code taucht sowohl am Anfang als auch am Ende des Prompts auf. Nicht, weil die Entwickler vergesslich waren — sondern weil sie die U-förmige Aufmerksamkeitskurve verstehen.

3.3 Tonfall & Stil — Den Output steuern

Ziel: Kontrolliere das Ausgabeformat und die Tonalität.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Richtlinien:

Liste spezifische Verhaltensweisen auf, kein vages "sei professionell"
Jede Regel sollte auf wahr/falsch testbar sein ("kurz und prägnant" vs. "versuche dich kurzzufassen")
Schließe Anforderungen an das Ausgabeformat ein (Markdown? JSON? Plain Text?)
Schließe ein, was NICHT zu tun ist — viele Stilprobleme lassen sich durch Verbote lösen

Das Glanzstück von Claude Code — Professionelle Objektivität:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Dieser Absatz ist entscheidend: Er blockiert die Sycophancy-Tendenz (Jasagerei) des Modells. Wenn dein Agent objektive Urteile fällen muss (Code Review, Ideen-Evaluierung, Architektur-Entscheidungen), brauchst du unbedingt eine ähnliche Klausel.

3.4 Kern-Workflow — Der wichtigste Abschnitt

Ziel: Bringe dem Modell bei, wie es arbeiten soll — Methodik, keine starren Prozeduren.

Dies ist der am schwersten zu schreibende Abschnitt, und der wirkungsvollste, wenn man ihn richtig hinbekommt.

Das Grundprinzip: Gib Prinzipien vor, keine Prozeduren.

Sag dem LLM, wie guter Output aussieht und warum er gut ist — lass es selbst herausfinden, wie es dorthin gelangt. Vermeide es, genaue Feldanzahlen, Schrittabfolgen oder Formate vorzuschreiben, es sei denn, der Output wird nachgelagert von Maschinen verarbeitet.

Der Ansatz von Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Beachte das Wort "recommended" (empfohlen) — nicht "du musst exakt diese Schritte befolgen". Diese einzige Wortwahl gibt dem Modell Raum zur Anpassung.

Eine gute Workflow-Definition:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Jede Regel hat ein implizites "Warum" — das Modell kann die Absicht verstehen und auf neue Szenarien generalisieren.

Anti-Patterns:

Eine starre 20-Schritte-Prozedur — das Modell wird sie mechanisch abarbeiten und bei unerwarteten Inputs einfrieren
"Mach zuerst A, dann mach B, dann mach C" — das ist eine Prompt-Chain, kein Agenten-Prompt
Dinge übermäßig anleiten, die das LLM ohnehin schon gut kann — verschwendet Tokens

Ich habe das bei VibeCom auf die harte Tour gelernt. Frühe Versionen hatten einen 10-stufigen Research-Workflow. Das Modell führte brav alle 10 Schritte aus, selbst wenn Schritt 3 die Frage des Users bereits beantwortet hatte. Als ich auf Prinzipien umstellte ("recherchiere, bis du ausreichend Beweise hast, dann synthetisiere"), stieg die Qualität und die Token-Kosten sanken.

Die Ausnahme: Wenn der Output nachgelagert von Maschinen verarbeitet wird (Inter-Agenten-Kommunikation, API-Response-Formate), solltest du strikte Formate definieren. Prinzipien sind für Verhalten; Schemata sind für Schnittstellen.

3.5 Tool-Nutzungsrichtlinien — Mehrdeutigkeiten auflösen

Ziel: Wenn mehrere Tools dasselbe tun können, sag dem Modell, welches es bevorzugen soll.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Richtlinien:

Verwende "instead of" (anstelle von), um Prioritäten auszudrücken (A statt B)
Erkläre, warum bestimmte Tools zu bevorzugen sind ("bietet eine bessere User Experience", "reduziert Context Usage")
Definiere die Parallelisierungsstrategie (unabhängig → parallel, abhängig → sequenziell)
Liste Sicherheitsbeschränkungen für die Tool-Nutzung auf (Pfad-Validierung, Berechtigungsprüfungen)

Die entscheidende Beziehung zwischen Tools und Prompts:

Tool-Definitionen werden typischerweise vom System injiziert und du kannst sie nicht direkt bearbeiten. Die Tool-Definitionen von Claude Code umfassen ca. 11.438 Tokens. Das bedeutet:

Wiederhole keine Informationen, die bereits in den Tool-Definitionen stehen
Nutze den System Prompt für strategische Führung: wann jedes Tool genutzt werden soll, warum eines dem anderen vorzuziehen ist, Prioritätenfolge
Die Qualität der Tool-Definitionen wirkt sich direkt auf die Effektivität des Agenten aus — wenn du deinen eigenen Agenten baust, investiere Zeit in das Schreiben exzellenter Tool-Beschreibungen

3.6 Domänenwissen — On-Demand laden, nicht im Voraus

Ziel: Stelle spezialisiertes Wissen bereit, das den Trainingsdaten des Modells möglicherweise fehlt.

Das Schlüsselprinzip: Progressive Disclosure (schrittweise Offenlegung), keine Knowledge Dumps.

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

Diese Strategie teilen sich das Skills-System von Claude Code und die Progressive-Disclosure-Middleware von DeepAgents. Beide laden Wissen bei Bedarf über Tool-Aufrufe, anstatt alles im Voraus zu laden.

Implementierungsansätze:

Setze Pointer im System Prompt: "Nutze das get_api_docs Tool, um bei Bedarf die Dokumentation abzurufen"
Nutze CLAUDE.md / AGENTS.md für Projektkontext — wird zur Laufzeit geladen, nicht hardcodiert
Nutze Skills / SKILL.md für Capability Discovery — das Modell sieht ein Menü verfügbarer Skills und ruft die vollständigen Spezifikationen bei Bedarf ab

3.7 Umgebungsinfos — Laufzeit-Kontext

Ziel: Gib dem Modell ein Bewusstsein für seine Ausführungsumgebung.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Richtlinien:

Dynamisch generieren, niemals hardcodieren
Einschließen: Arbeitsverzeichnis, Plattform, Datum, Modellname, Git-Status
Strukturiertes Format verwenden (XML-Tags oder Code-Blöcke) für einfaches Parsing
Das Datum ist wichtig — das Modell muss das "Jetzt" kennen, um die Aktualität von Informationen beurteilen zu können

3.8 Erinnerungen — Die letzte Verstärkung

Ziel: Wiederhole die kritischsten Regeln am Ende des Prompts.

Claude Code wiederholt seine Sicherheitsbeschränkung und die TodoWrite-Anforderung ganz unten:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Richtlinien:

Wiederhole nur 2-3 der absolut kritischsten Regeln — dupliziere nicht alles
Nutze den Recency-Bias — das Modell merkt sich aktuelle Inhalte stärker
Beste Kandidaten: Sicherheitsbeschränkungen, am häufigsten verletzte Regeln, Erinnerungen an den Kern-Workflow

4. Token-Budget und Kontext-Management

Referenz für die Budgetzuweisung

Abschnitt	Empfohlene Tokens	Notizen
Identität + Sicherheit	200-500	Prägnant, aber nicht verhandelbar
Tonfall & Stil	300-800	Regeln müssen spezifisch sein, aber schweife nicht ab
Kern-Workflow	500-2.000	Wichtigster Abschnitt, die Investition wert
Tool-Nutzungsrichtlinien	300-1.000	Abhängig von der Anzahl der Tools
Domänenwissen	0-1.000	On-Demand-Laden bevorzugt
Umgebungsinfos	100-300	Wird dynamisch generiert
Erinnerungen	100-300	Wiederhole nur das Wesentliche
Dein Gesamtbudget	1.500-6.000
Tool-Definitionen (System)	5.000-15.000	Liegt nicht in deiner Kontrolle

Kontext-Verfallskurve

Community-Tests (Reddit u/CodeMonke_) haben den realen Verfall der Prompt-Adherence (Regeltreue) kartiert:

< 80K Tokens: Prompt-Adherence bleibt stabil
80K - 120K Tokens: Das Befolgen von Anweisungen beginnt sich zu verschlechtern
> 120K Tokens: Signifikante Verschlechterung — das Modell "vergisst" frühe Anweisungen
> 180K Tokens: Massive Verschlechterung

Dein 200K Context Window ≠ 200K effektiver Kontext. Plane entsprechend.

Mitigationsstrategien:

Halte deinen System Prompt schlank (< 6.000 Tokens für deinen Teil)
Nutze Zusammenfassungen, um die Konversationshistorie zu komprimieren (DeepAgents triggert bei ca. 80K Zeichen)
Platziere kritische Regeln an beiden Enden des Prompts (U-förmige Aufmerksamkeit)
Injiziere <system-reminder> Tags mitten in der Konversation (mehr dazu in Abschnitt 8)

5. Schreibprinzipien

5.1 Gib Prinzipien vor, keine Prozeduren

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Prinzipien lassen sich generalisieren. Prozeduren können nur mechanisch befolgt werden. Wenn das Modell auf eine Situation stößt, die du nicht vorhergesehen hast, leiten Prinzipien die richtige Entscheidung. Prozeduren tun das nicht.

Ausnahme: Wenn der Output von Maschinen verarbeitet wird (Inter-Agenten-Kommunikation, API-Formate), definiere strikte Schemata.

5.2 Nutze absolute Sprache für harte Grenzen

Stärke	Sprache	Verwenden für
Absolute Prohibition	`NEVER`, `MUST NOT`	Sicherheit, irreversible Operationen
Starke Anforderung	`ALWAYS`, `MUST`	Kern-Workflow-Regeln
Empfehlung	`recommended`, `prefer`	Best Practices mit Ausnahmen
Vorschlag	`consider`, `you may`	Optionale Optimierungen

Claude Code Beispiele:

NEVER update the git config — absolute Prohibition
ALWAYS prefer editing an existing file — stark, aber es gibt Ausnahmen
The following steps are recommended — vorgeschlagener Workflow

5.3 Nutze Beispiele statt Erklärungen

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Ein einziges Beispiel lehrt mehr als 100 Worte Erklärung:

Modelle lernen Muster aus Beispielen zuverlässiger als aus abstrakten Beschreibungen
Umschließe sie mit <example> Tags, um sie von Regeln zu trennen
Biete sowohl positive ("mach das") als auch negative ("mach das nicht") Beispiele
Nutze echte, spezifische Beispiele — keine "foo/bar" Platzhalter

5.4 Bidirektionale Einschränkungen

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Nur zu sagen "mach das" → das Modell weiß nicht, wann es das NICHT tun soll. Nur zu sagen "mach das nicht" → das Modell kennt die Alternative nicht. Bidirektional → klar und unmissverständlich.

5.5 Erkläre das Warum, nicht nur das Was

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Das Erklären des Warum ermöglicht es dem Modell, in Edge Cases korrekte Urteile zu fällen. Das Git-Sicherheitsprotokoll von Claude Code ist eine Meisterklasse — jede Regel impliziert ihre Rationale.

5.6 Struktur über Prosa

Markdown-Header (##, ###) — Modelle erkennen Hierarchien
Aufzählungslisten statt Absätze — jede Regel ist unabhängig testbar
XML-Tags für spezielle Inhalte: <example>, <env>, <system-reminder>
Tabellen für Vergleiche und Mappings
Lade niemals unstrukturierten Text ab — strukturierte Prompts übertreffen natürlichsprachliche Prosa in Adherence-Tests durchgehend

6. Anti-Patterns, die deine Tokens verschwenden

Als Agenten getarnte Prompt-Chains

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Das ist kein Agenten-Prompt — es ist ein Pipeline-Skript. Das Modell wird es mechanisch ausführen und seine autonome Planungsfähigkeit verlieren.

Die Lösung: Nenne dem Modell das Ziel und die Einschränkungen. Lass es die Schritte selbst entscheiden.

Flattery Engineering

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Komplimente und Superlative verbessern die Output-Qualität nicht. Das Modell hat kein Ego, das man pushen müsste. Spar dir diese 15 Tokens lieber für eine echte Regel.

Knowledge Dumps

"Here is the complete API documentation for our 200 endpoints..."

Das verschlingt dein Context Window und beschleunigt den Context Rot. Ersetze es durch On-Demand-Laden:

"Use the get_api_docs tool to retrieve API documentation when needed."

Tool-Beschreibungen wiederholen

Wenn in der Tool-Definition bereits steht "Read tool reads a file from the filesystem", sag es nicht nochmal in deinem System Prompt. Füge nur strategische Führung hinzu, die die Tool-Definition nicht abdeckt — wann man es nutzt, warum man es bevorzugt, Prioritätenfolge.

Fehlendes Failure Handling

Ohne explizite Anleitung werden Modelle fehlgeschlagene Tool-Aufrufe in einer Endlosschleife wiederholen. Füge immer hinzu:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Den Verfall des Context Windows ignorieren

200K Context Window ≠ 200K effektiver Kontext. Reale Tests zeigen, dass die Degradation bei 80K beginnt. Du brauchst eine Zusammenfassungs-Strategie.

7. Injection Points und Priorität

Die drei Anpassungsmethoden von Claude Code

Methode	Ersetzt	Platzierung	Am besten für
Output Styles	"Tone and style" + "Doing tasks" Abschnitte	Direkt vor den Tool-Definitionen	Änderung des Interaktionsstils
--append-system-prompt	Nichts (additiv)	Nach Output Style, vor Tool-Definitionen	Hinzufügen spezifischer Verhaltensweisen
--system-prompt	Den gesamten System Prompt	Behält Tool-Definitionen + eine Identitätszeile	Volle Anpassung (die nukleare Option)

Wenn du mehrere nutzt: Output Style → Append Prompt → Tool Definitions

Anweisungshierarchie

Claude ist speziell mit einer Anweisungshierarchie trainiert:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

Das bedeutet:

CLAUDE.md-Regeln überschreiben das Standardverhalten des System Prompts
Direkte Anfragen des Users überschreiben alles
Dein Custom Prompt überschreibt den Standard-Prompt

Dynamische Injection-Mechanismen

<system-reminder> — injiziere dies mitten in der Konversation in eine beliebige Nachricht, um das Modell an kritische Regeln zu erinnern
CLAUDE.md / AGENTS.md — wird zur Laufzeit aus Dateien geladen, an den System Prompt angehängt
Skills / SKILL.md — wird bei Bedarf via Tool-Aufruf geladen, null Footprint im System Prompt

8. Mid-Conversation Injection — Die Geheimwaffe

Der System Prompt taucht nur einmal auf, ganz am Anfang des Messages-Arrays. Aber LLMs akzeptieren das gesamte Messages-Array (abwechselnd User- / Assistant- / Tool-Nachrichten) als Input, und du kannst Prompts auch in User-Nachrichten und Tool-Ergebnisse injizieren. Claude Code nutzt diese Technik in Produktion intensiv.

Warum es notwendig ist

Der Kampf gegen den Context Rot. Je länger Konversationen werden, desto mehr nimmt die Regeltreue des Modells gegenüber dem System Prompt ab (spürbar ab 80K+ Tokens). Das Injizieren von Erinnerungen mitten in der Konversation = Auffrischen der Regeln via Recency-Bias.

Das mentale Modell:

System Prompt = die Verfassung (einmal etabliert, langfristige Autorität)
User Message Reminders = Memos (regelmäßig verschickt, um die Durchsetzung aufrechtzuerhalten)

Drei Injection Points im Messages-Array

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

Ort	Vorteil	Nachteil
System prompt	Primacy-Effekt, wird zuerst gelesen	Taucht nur einmal auf, wird in langen Chats "vergessen"
User message injection	Recency-Bias, periodischer Refresh	Jede Injection kostet Tokens
Tool result injection	Natürlichster Injection Point	Funktioniert nur, wenn Tools aufgerufen werden

Wie Claude Code es tatsächlich nutzt

Voraussetzung — deklariere die Tags im System Prompt:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Dieser Schritt ist kritisch: Er sagt dem Modell, dass diese Tags vom System injiziert wurden und keine User-Eingaben sind.

Nutzung 1: Verhaltens-Erinnerungen (periodischer Regel-Refresh)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code nutzt dies, um das Modell daran zu erinnern, mit TodoWrite zu planen — denn Modelle neigen dazu, das Planen zu "vergessen" und einfach drauflos zu coden.

Nutzung 2: Modus-Wechsel (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

Der Plan Mode ist nicht im System Prompt implementiert. Es ist ein Tag, das in die nächste User-Nachricht injiziert wird. So kannst du Modi dynamisch umschalten, ohne den System Prompt zu modifizieren. Brillant.

Nutzung 3: Benachrichtigungen über Dateiänderungen

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Wenn ein externer Prozess (Linter, Formatter, manuelle Bearbeitung) eine Datei ändert, benachrichtigt das System das Modell via Reminder — das verhindert Entscheidungen basierend auf veralteten Dateiinhalten.

Nutzung 4: Dynamischer Kontext (Daten, Projektregeln)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Laufzeit-Kontext (Datum, Git-Status, Projektregeln) wird über User-Nachrichten injiziert, nicht hardcodiert im System Prompt.

Schreibrichtlinien für Reminders

In XML-Tags verpacken (<system-reminder>) — das Modell kann System-Injections von User-Eingaben unterscheiden
Tags im System Prompt vordeklarieren — sonst versucht das Modell möglicherweise, auf den Reminder zu antworten
Nicht in jede Nachricht injizieren — jede Injection kostet Tokens, injiziere nur bei Bedarf
Kurz halten — ein Reminder ist kein zweiter System Prompt, nur 1-2 kritische Regeln
Dem System Prompt nicht widersprechen — Reminders ergänzen und verstärken, sie überschreiben nicht
Für dynamisches Toggling nutzen — Plan Mode, Readonly Mode, Feature Flags

Wann man System Prompt vs. User Message Reminder nutzt

Szenario	System Prompt	User Message Reminder
Rollendefinition	✅	❌
Sicherheitsgrenzen	✅ Erste Deklaration	✅ Periodische Wiederholung
Workflow-Methodik	✅	❌
Modus-Wechsel (Plan Mode)	❌	✅
Dateiänderungs-Infos	❌	✅
Datum / Umgebungsinfos	✅ Initialer Wert	✅ Aktualisierter Wert
Verhaltenskorrektur	❌	✅
Tool-Nutzungs-Erinnerungen	✅ Regeldefinition	✅ Ausführungs-Nudges

9. Prompt Cache — Spare 90% bei wiederholten Tokens

Das Prompt Caching von Anthropic lässt dich den statischen Präfix deines Messages-Arrays cachen. Wenn nachfolgende Requests denselben Präfix teilen, treffen sie den Cache — das spart Geld und reduziert die Latenz.

Für Agenten ist das extrem wichtig: Du sendest den System Prompt + Tool-Definitionen bei jedem einzelnen LLM-Aufruf innerhalb einer Konversation erneut mit.

Die wichtigsten Zahlen

Metrik	Wert
Kosten für Cache Hit	10% des Normalpreises (90% Ersparnis)
Kosten für Cache Write	125% des Normalpreises (25% Aufschlag beim ersten Schreiben)
Cache TTL	5 Minuten (läuft ab, wenn keine Requests kommen)
Minimale Cache-Länge	1.024 Tokens (Claude 3.5+)
Cache-Granularität	Prefix Matching — vom Anfang bis zu einem markierten Breakpoint
Maximale Breakpoints	4

Wie das das Prompt-Design verändert

Kernprinzip: Statischer Content zuerst, dynamischer Content zuletzt.

✅ Cache-friendly layout:
  System prompt (static)      ← Cache breakpoint 1
  Tool definitions (static)   ← Cache breakpoint 2
  CLAUDE.md / project rules   ← Cache breakpoint 3 (changes occasionally)
  Conversation history         ← Breakpoint 4 for rolling window

❌ Cache-destroying layout:
  System prompt
  DYNAMIC TIMESTAMP            ← Changes every request, everything after = cache miss
  Tool definitions
  Conversation history

Die Falle, vor der dich niemand warnt: Wenn du einen dynamischen Zeitstempel in die Mitte deines System Prompts packst, wird alles danach zu einem Cache Miss. Bei. Jedem. Einzelnen. Request. Ein Zeitstempel an der falschen Stelle und du zahlst den vollen Preis für Tausende von Tokens.

API-Nutzung

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marks a cache breakpoint
    }
  ],
  messages: [...]
});

Multi-Breakpoint-Strategie

Breakpoint 1: System prompt           ← Almost never changes
Breakpoint 2: Tool definitions         ← Almost never changes
Breakpoint 3: Project rules / CLAUDE.md ← Changes occasionally
Breakpoint 4: First N history messages  ← Rolling window cache

Selbst wenn sich die Konversationshistorie ändert, greifen die ersten 3 Breakpoints weiterhin. Eine Konversation mit 10 Turns spart so grob 40-60% der Input-Token-Kosten.

Design-Empfehlungen

Keine hochfrequenten dynamischen Werte im System Prompt — das Datum ist okay (ändert sich täglich), präzise Zeitstempel nicht
Packe dynamischen Kontext (Git-Status, etc.) in User Message Injections — nicht in den System Prompt, sonst zerstörst du den Cache
Halte Tool-Definitionen stabil — füge Tools zur Laufzeit nicht dynamisch hinzu oder entferne sie
Nutze ein Rolling Window für die Konversationshistorie — cache die ersten N Nachrichten, nur die neueste Nachricht ist ein Cache Miss

10. Die Checkliste

Nachdem du deinen System Prompt geschrieben hast, überprüfe ihn anhand dieser Checkliste:

Struktur

Identität steht ganz oben?
Sicherheitsgrenzen sind mit IMPORTANT markiert und werden am Ende wiederholt?
Klare Abschnittstrennung mit Headern?
Beispiele sind in <example> Tags verpackt?

Token-Budget

Dein Teil < 6.000 Tokens?
Keine Wiederholung von Infos, die schon in den Tool-Definitionen stehen?
Domänenwissen wird On-Demand geladen, nicht im Voraus?
Keine ausschweifende Lore oder Charakter-Hintergrundgeschichte?

Regel-Qualität

Jede Regel ist auf wahr/falsch testbar?
Harte Grenzen nutzen absolute Sprache (NEVER/MUST)?
Weiche Vorschläge nutzen Empfehlungssprache (recommended/prefer)?
Kritische Regeln erklären das Warum, nicht nur das Was?
Bidirektionale Einschränkungen (mach dies + mach das nicht)?

Agenten-Verhalten

Prinzipien vorgegeben, keine starren Schritt-für-Schritt-Prozeduren?
Das "Tool Call Denied"-Szenario behandelt?
Die "Hindernis aufgetreten"-Strategie behandelt (kein Brute-Force-Retry)?
Kontext-Management-Strategie vorhanden (Zusammenfassungs-Schwellenwert)?

Was man NICHT tun sollte

Keine Schmeicheleien oder Superlative?
Keine redundanten "du bist eine hilfreiche KI"-Deklarationen?
Nicht als Prompt-Chain geschrieben?
Kein Over-Engineering (Features, nach denen niemand gefragt hat)?

Wenn ich heute nochmal anfangen würde

Hier ist genau das, was ich tun würde:

Starte mit Identität + Sicherheit in den ersten 3 Zeilen. Zwei Sätze darüber, wer der Agent ist. Harte Grenzen mit NEVER/MUST. Wiederhole die Sicherheitsregeln am Ende.
Schreibe deinen Kern-Workflow als Prinzipien, nicht als Schritte. Max. 4-5 Bullet Points. Nutze "recommended" und "prefer" für weiche Regeln, "NEVER" und "MUST" für harte.
Budgetiere 1.500-6.000 Tokens für deinen Teil. Tool-Definitionen werden weitere 5.000-15.000 hinzufügen. Wenn du über 6K liegst, lädst du wahrscheinlich Wissen ab, das On-Demand geladen werden sollte.
Strukturiere alles. Markdown-Header, Aufzählungslisten, XML-Tags für Beispiele. Ein strukturierter Prompt schlägt natürlichsprachliche Prosa jedes Mal.
Baue Mid-Conversation Reminders von Tag eins an ein. Deklariere <system-reminder> in deinem System Prompt. Injiziere Erinnerungen für kritische Regeln, Modus-Wechsel und Kontext-Updates.
Design für den Cache. Statischer Content zuerst, dynamischer Content zuletzt. Packe niemals sich ändernde Werte in den Body deines System Prompts.

Die Ironie an all dieser Arbeit? Die besten System Prompts sind kurz. Die Custom Instructions von Claude Code (ohne Tool-Definitionen) sind überraschend prägnant. Jede Zeile verdient ihren Platz.

Früher dachte ich, beim Prompt Engineering ginge es darum, clevere Tricks zu finden. Heute denke ich, es geht um Disziplin — weniger zu sagen, es präzise zu sagen und darauf zu vertrauen, dass das Modell den Rest selbst herausfindet. Das Modell ist schlauer als dein Prompt. Gestalte die Umgebung, nicht das Verhalten.

Referenzen

Quelle	Wichtigste Erkenntnis
Claude Code v2.0.14 System Prompt	Vollständige Referenz für die Struktur eines Production-Agent-Prompts
Reddit: Understanding Claude Code's 3 System Prompt Methods	Deep Dive zu Output Styles / --append / --system-prompt, reale Daten zu Context Rot
shareAI-lab/learn-claude-code	"Das Modell ist der Agent"-Philosophie, Harness-Engineering-Methodik
Anthropic Prompt Engineering Docs	Offizielle Best Practices für Prompts
DeepAgents Framework	Summarization-Middleware, Progressive Disclosure von Skills