De complete gids voor het schrijven van Agent System Prompts — Lessen uit het reverse-engineeren van Claude Code

Ik heb de system prompt van Claude Code gedecompileerd, de broncode van DeepAgents bestudeerd en mijn eigen AI-agent vanaf nul opgebouwd. De meeste prompt-guides zijn namelijk puur nattevingerwerk.

Title: Het Complete System Prompt Playbook: Wat Ik Leerde van het Reverse-Engineeren van Claude Code Content: Er heerst momenteel een massale waan in de AI-wereld.

Elke tutorial vertelt je dat je system prompts moet schrijven alsof je een spreuk uitspreekt — vind simpelweg de juiste bezwering en het model zal gehoorzamen. "Je bent een EXTREEM GETALENTEERDE senior engineer met 20 jaar ervaring..." Klinkt bekend?

Ik heb de afgelopen maanden gebouwd aan VibeCom, een AI startup advisor die diepgaand marktonderzoek doet en analyses op VC-niveau genereert. Tijdens dit proces heb ik de system prompt van Claude Code reverse-engineered, de middleware source van DeepAgents doorgespit, en meer API-credits verbrand dan ik eigenlijk wil toegeven. De grootste les? Het meeste van wat mensen denken dat belangrijk is aan system prompts, is dat helemaal niet. En over de dingen die er écht toe doen, praat bijna niemand.

Deze post is het complete playbook — geen overzicht van 5 minuten, maar alles wat ik had willen weten voordat ik begon. Pak er een kop koffie bij.

1. Design Filosofie: Vertrouw het Model

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

Dit idee veranderde alles voor mij. Het LLM weet al hoe het moet redeneren, plannen en uitvoeren. Je system prompt leert het model niet hóe het moet denken — het creëert de omgeving waarin het kan werken.

Zie het als het aannemen van een senior engineer. Je geeft ze geen checklist van 20 stappen voor elke taak. Je vertelt ze: dit is wie we zijn, dit zijn de grenzen, en dit is hoe goed werk eruitziet. Daarna stap je opzij.

Je system prompt heeft exact vier taken:

Vertel wie het is — rol en identiteit
Geef de grenzen aan — veiligheidsrestricties
Vertel hoe goed werk eruitziet — kwaliteitsstandaarden
Geef het tools — mogelijkheden en kennis

Dat is het. Al het andere is ruis.

De Harness-mindset

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

Je system prompt is de handleiding voor dit 'harness' (tuigje/framework). Je ontwerpt geen rigide pijplijn — je ontwerpt een omgeving waarin het model autonoom zijn beste werk kan doen.

Schrijf je system prompt niet als een flowchart. Het model bepaalt zelf de volgorde van uitvoering wel.

2. Prompt Structuur en Volgorde van Secties

De Aanbevolen Layout (Reverse-Engineered uit 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]                               │
└─────────────────────────────────────────────┘

Waarom Deze Volgorde Belangrijk Is

LLM's hebben een U-vormige aandachtscurve — ze letten het meest op het begin en het einde van je prompt, en verliezen de focus in het midden. Dit is het bekende "Lost in the Middle" effect, en het is goed gedocumenteerd.

Identiteit + Veiligheid bovenaan: Het model stelt eerst zijn rol en grenzen vast (primacy-effect)
Core Workflow in het bovenste midden: Je belangrijkste sectie — hoe de agent zijn werk doet
Tool Definities worden door het systeem geïnjecteerd na je prompt: De tool definities van Claude Code slokken zo'n ~11.438 tokens op. Dit betekent dat jouw custom content eigenlijk dichter bij het begin staat dan je zou verwachten — wat de adherence (het opvolgen van instructies) ten goede komt
Reminders onderaan: Maak gebruik van de recency bias (recentheidseffect) om kritieke regels te versterken

3. Het Schrijven van Elke Sectie

3.1 Identiteit — Wie Is Deze Agent?

Doel: Veranker de rol van het model in 1-3 zinnen.

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

Richtlijnen:

Houd het beknopt — maximaal 1-3 zinnen
Benoem de rol expliciet (helpt het model contexten te onderscheiden)
Benoem de kernverantwoordelijkheid ("helpt met X"), niet een vaag "je bent een behulpzame assistent"
Vermeld de SDK/het platform indien van toepassing ("gebouwd op Anthropic's Claude Agent SDK")

Anti-patronen:

"Je bent een behulpzame, onschadelijke en eerlijke AI-assistent" — te generiek, geen rolverankering
Een hele alinea aan achtergrondverhaal en lore — verspilt tokens, het model heeft geen karakterontwikkeling nodig

3.2 Security & Safety — De Harde Grenzen

Doel: Stel onbreekbare gedragsrestricties in.

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.

Richtlijnen:

Gebruik de IMPORTANT: prefix — Claude's training in instructiehiërarchie geeft dit extra gewicht
Gebruik absolute taal: NEVER, MUST NOT, Refuse to
Benoem zowel wat is toegestaan ALS wat is verboden (bidirectionele restricties zijn duidelijker)
Plaats dit helemaal bovenaan, stop het niet weg in het midden
Herhaal kritieke veiligheidsregels aan het einde — Claude Code doet precies dit

Waarom herhalen? Primacy-effect (begin) + Recency-effect (einde) = dubbele versterking. De veiligheidsverklaring van Claude Code staat zowel aan het begin als aan het einde van de prompt. Niet omdat de engineers vergeetachtig waren — maar omdat ze de U-vormige aandachtscurve begrijpen.

3.3 Tone & Style — De Output Sturen

Doel: Controleer het outputformaat en de tone of voice.

## 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.

Richtlijnen:

Som specifiek gedrag op, niet een vaag "wees professioneel"
Elke regel moet testbaar zijn met waar/onwaar ("kort en bondig" vs. "probeer kort te zijn")
Voeg vereisten voor het outputformaat toe (markdown? JSON? plain text?)
Voeg toe wat het model NIET moet doen — veel stijlproblemen gaan over het verbieden van bepaald gedrag

Het pareltje van Claude Code — Professionele Objectiviteit:

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.

Deze alinea is cruciaal: het blokkeert de sycophancy (de neiging om de gebruiker naar de mond te praten) van het model. Als je agent objectieve oordelen moet vellen (code review, idee-evaluatie, architectuurbeslissingen), heb je absoluut een vergelijkbare clausule nodig.

3.4 Core Workflow — De Belangrijkste Sectie

Doel: Leer het model hoe het moet werken — methodologie, geen rigide procedures.

Dit is de moeilijkste sectie om goed te schrijven, en degene met de meeste impact als je het goed doet.

Het kernprincipe: geef principes, geen procedures.

Vertel het LLM hoe goede output eruitziet en waarom het goed is — laat het zelf uitzoeken hoe het daar komt. Vermijd het voorschrijven van exacte aantallen velden, stappenreeksen of formaten, tenzij de output downstream door machines wordt verwerkt.

De aanpak van 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

Let op het woord "recommended" (aanbevolen) — niet "je moet exact deze stappen volgen." Die ene woordkeuze geeft het model de ruimte om zich aan te passen.

Een goede workflow-definitie:

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.)

Elke regel heeft een impliciet "waarom" — het model kan de intentie begrijpen en generaliseren naar nieuwe scenario's.

Anti-patronen:

Een rigide procedure van 20 stappen — het model zal dit mechanisch uitvoeren en vastlopen bij onverwachte input
"Doe eerst A, dan B, dan C" — dat is een prompt chain, geen agent prompt
Te veel sturing geven op dingen waar het LLM al goed in is — verspilt tokens

Ik heb dit door schade en schande geleerd met VibeCom. Vroege versies hadden een onderzoeksworkflow van 10 stappen. Het model voerde braaf alle 10 stappen uit, zelfs als stap 3 de vraag van de gebruiker al had beantwoord. Toen ik overstapte op principes ("doe onderzoek tot je voldoende bewijs hebt, en synthetiseer dan"), ging de kwaliteit omhoog en de tokenkosten omlaag.

De uitzondering: Wanneer output downstream door machines wordt verwerkt (inter-agent communicatie, API response formaten), moet je wel strikte formaten definiëren. Principes zijn voor gedrag; schema's zijn voor interfaces.

3.5 Tool Usage Policy — Ambiguïteit Oplossen

Doel: Wanneer meerdere tools hetzelfde kunnen doen, vertel het model dan welke de voorkeur heeft.

## 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.

Richtlijnen:

Gebruik "in plaats van" (instead of) om prioriteit aan te geven (A in plaats van B)
Leg uit waarom bepaalde tools de voorkeur hebben ("zorgt voor een betere gebruikerservaring", "vermindert contextgebruik")
Definieer de parallelisatiestrategie (onafhankelijk → parallel, afhankelijk → sequentieel)
Som veiligheidsrestricties op voor toolgebruik (pad-validatie, permissie-checks)

De cruciale relatie tussen tools en prompts:

Tool definities worden meestal door het systeem geïnjecteerd en je kunt ze niet direct bewerken. De tool definities van Claude Code zijn ~11.438 tokens. Dit betekent:

Herhaal geen informatie die al in de tool definities staat
Gebruik de system prompt voor strategische sturing: wanneer je elke tool gebruikt, waarom je de ene boven de andere verkiest, prioriteitsvolgorde
De kwaliteit van de tool definitie heeft directe impact op de effectiviteit van de agent — als je je eigen agent bouwt, investeer dan tijd in het schrijven van uitstekende toolbeschrijvingen

3.6 Domain Knowledge — On-Demand Laden, Niet Vooraf

Doel: Bied gespecialiseerde kennis die mogelijk ontbreekt in de trainingsdata van het model.

Het kernprincipe: progressive disclosure (stapsgewijze onthulling), geen kennis-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"

Deze strategie wordt gedeeld door het Skills-systeem van Claude Code en de Progressive Disclosure middleware van DeepAgents. Beide laden kennis on-demand via tool calls in plaats van alles vooraf in te laden.

Implementatie-aanpakken:

Zet pointers in de system prompt: "Gebruik de get_api_docs tool om documentatie op te halen wanneer nodig"
Gebruik CLAUDE.md / AGENTS.md voor projectcontext — geladen tijdens runtime, niet hardcoded
Gebruik Skills / SKILL.md voor het ontdekken van capabilities — het model ziet een menu van beschikbare skills en haalt de volledige specificaties on-demand op

3.7 Environment Info — Runtime Context

Doel: Geef het model bewustzijn van zijn uitvoeringsomgeving.

<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.

Richtlijnen:

Genereer dit dynamisch, nooit hardcoden
Inclusief: werkmap, platform, datum, modelnaam, git-status
Gebruik een gestructureerd formaat (XML-tags of codeblokken) voor eenvoudige parsing
Datum is belangrijk — het model moet weten wat "nu" is om de versheid van informatie te beoordelen

3.8 Reminders — De Laatste Versterking

Doel: Herhaal de meest kritieke regels aan het einde van de prompt.

Claude Code herhaalt zijn veiligheidsrestrictie en TodoWrite-vereiste onderaan:

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

Richtlijnen:

Herhaal slechts 2-3 van de meest kritieke regels — dupliceer niet alles
Maak gebruik van recency bias — het model onthoudt recente content sterker
Beste kandidaten: veiligheidsrestricties, regels die het vaakst worden overtreden, core workflow reminders

4. Token Budget en Context Management

Budget Allocatie Referentie

Sectie	Aanbevolen Tokens	Opmerkingen
Identiteit + Veiligheid	200-500	Beknopt maar ononderhandelbaar
Tone & Style	300-800	Regels moeten specifiek zijn, maar weid niet uit
Core Workflow	500-2.000	Belangrijkste sectie, de investering waard
Tool Usage Policy	300-1.000	Afhankelijk van het aantal tools
Domain Knowledge	0-1.000	On-demand laden heeft de voorkeur
Environment Info	100-300	Dynamisch gegenereerd
Reminders	100-300	Herhaal alleen de essentie
Jouw totaal	1.500-6.000
Tool Definities (systeem)	5.000-15.000	Heb je geen controle over

Context Degradatie Curve

Community tests (Reddit u/CodeMonkey_) hebben de daadwerkelijke degradatie van instructie-opvolging in kaart gebracht:

< 80K tokens: Prompt adherence blijft stabiel
80K - 120K tokens: Het opvolgen van instructies begint te degraderen
> 120K tokens: Aanzienlijke degradatie — het model "vergeet" vroege instructies
> 180K tokens: Ernstige degradatie

Je 200K context window ≠ 200K aan effectieve context. Houd hier rekening mee.

Mitigatiestrategieën:

Houd je system prompt lean (< 6.000 tokens voor jouw deel)
Gebruik samenvattingen om de conversatiegeschiedenis te comprimeren (DeepAgents triggert bij ~80K karakters)
Plaats kritieke regels aan beide uiteinden van de prompt (U-vormige aandacht)
Injecteer <system-reminder> tags halverwege de conversatie (meer hierover in sectie 8)

5. Schrijfprincipes

5.1 Geef Principes, Geen Procedures

❌ "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."

Principes generaliseren. Procedures kunnen alleen mechanisch worden gevolgd. Wanneer het model een situatie tegenkomt die je niet had voorzien, sturen principes de juiste beslissing. Procedures doen dat niet.

Uitzondering: Wanneer output door machines wordt verwerkt (inter-agent communicatie, API formaten), definieer dan strikte schema's.

5.2 Gebruik Absolute Taal voor Harde Grenzen

Kracht	Taal	Gebruik Voor
Absoluut verbod	`NEVER`, `MUST NOT`	Veiligheid, onomkeerbare operaties
Sterke vereiste	`ALWAYS`, `MUST`	Core workflow regels
Aanbeveling	`recommended`, `prefer`	Best practices met uitzonderingen
Suggestie	`consider`, `you may`	Optionele optimalisaties

Claude Code voorbeelden:

NEVER update the git config — absoluut verbod
ALWAYS prefer editing an existing file — sterk, maar er zijn uitzonderingen
The following steps are recommended — voorgestelde workflow

5.3 Gebruik Voorbeelden in plaats van Uitleg

## 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>

Eén voorbeeld leert meer dan 100 woorden uitleg:

Modellen leren patronen betrouwbaarder van voorbeelden dan van abstracte beschrijvingen
Wikkel ze in <example> tags om ze te scheiden van regels
Geef zowel positieve ("doe dit") als negatieve ("doe dit niet") voorbeelden
Gebruik echte, specifieke voorbeelden — geen "foo/bar" placeholders

5.4 Bidirectionele Restricties

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

Alleen zeggen "doe dit" → model weet niet wanneer het het NIET moet doen. Alleen zeggen "doe dit niet" → model kent het alternatief niet. Bidirectioneel → helder en ondubbelzinnig.

5.5 Leg het Waarom uit, niet alleen het Wat

❌ "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."

Het uitleggen van het waarom stelt het model in staat om de juiste oordelen te vellen in edge cases. Het git-veiligheidsprotocol van Claude Code is een masterclass — elke regel impliceert zijn eigen rationale.

5.6 Structuur boven Proza

Markdown headers (##, ###) — modellen herkennen hiërarchie
Bullet lists boven alinea's — elke regel is onafhankelijk testbaar
XML tags voor speciale content: <example>, <env>, <system-reminder>
Tabellen voor vergelijkingen en mappings
Dump nooit ongestructureerde tekst — gestructureerde prompts presteren in adherence-tests consequent beter dan natuurlijk proza

6. Anti-patronen die je Tokens Verspillen

Prompt Chains Vermomd als Agents

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

Dit is geen agent prompt — het is een pipeline script. Het model zal dit mechanisch uitvoeren en zijn autonome planningsvermogen verliezen.

De oplossing: Vertel het model het doel en de restricties. Laat het zelf de stappen bepalen.

Flattery Engineering (Slijmen)

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

Complimenten en superlatieven verbeteren de outputkwaliteit niet. Het model heeft geen ego dat gestreeld moet worden. Bewaar die 15 tokens voor een daadwerkelijke regel.

Kennis-Dumps

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

Dit vreet je context window op en versnelt context rot. Vervang dit door on-demand laden:

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

Tool-beschrijvingen Herhalen

Als de tool definitie al zegt "Read tool reads a file from the filesystem", zeg het dan niet nog een keer in je system prompt. Voeg alleen strategische sturing toe die de tool definitie niet dekt — wanneer je het moet gebruiken, waarom je het verkiest, prioriteitsvolgorde.

Ontbrekende Foutafhandeling

Zonder expliciete sturing zullen modellen gefaalde tool calls in een oneindige loop blijven proberen. Voeg altijd toe:

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

Context Window Verval Negeren

200K context window ≠ 200K aan effectieve context. Tests in de praktijk tonen aan dat degradatie begint bij 80K. Je hebt een samenvattingsstrategie nodig.

7. Injectiepunten en Prioriteit

De Drie Customization Methoden van Claude Code

Methode	Vervangt	Plaatsing	Beste Voor
Output Styles	"Tone and style" + "Doing tasks" secties	Vlak voor tool definities	Aanpassen van interactiestijl
--append-system-prompt	Niets (additief)	Na output style, voor tool definities	Toevoegen van specifiek gedrag
--system-prompt	Volledige system prompt	Behoudt tool definities + één identity line	Volledige aanpassing (nuclear optie)

Als je er meerdere gebruikt: Output Style → Append Prompt → Tool Definities

Instructiehiërarchie

Claude is specifiek getraind met een instructiehiërarchie:

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

Dit betekent:

CLAUDE.md regels overrulen het standaard system prompt gedrag
Directe verzoeken van de gebruiker overrulen alles
Jouw custom prompt overruled de default prompt

Dynamische Injectiemechanismen

<system-reminder> — injecteer in elk willekeurig bericht halverwege de conversatie om het model te herinneren aan kritieke regels
CLAUDE.md / AGENTS.md — geladen tijdens runtime vanuit bestanden, toegevoegd aan de system prompt
Skills / SKILL.md — on-demand geladen via tool calls, nul footprint in de system prompt

8. Mid-Conversation Injectie — Het Geheime Wapen

De system prompt verschijnt slechts één keer, helemaal aan het begin van de messages array. Maar LLM's accepteren de volledige messages array (afwisselend user / assistant / tool messages) als input, en je kunt prompts ook injecteren in user messages en tool results. Claude Code gebruikt deze techniek intensief in productie.

Waarom Het Nodig Is

Context rot tegengaan. Naarmate conversaties langer worden, degradeert de adherence van het model aan de instructies in de system prompt (merkbaar bij 80K+ tokens). Het injecteren van reminders halverwege de conversatie = het opfrissen van de regels via recency bias.

Het mentale model:

System prompt = de grondwet (één keer vastgesteld, langdurige autoriteit)
User message reminders = memo's (periodiek verstuurd, handhaving van de regels)

Drie Injectiepunten in de 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
└─────────────────────────────────────┘

Locatie	Voordeel	Nadeel
System prompt	Primacy-effect, als eerste gelezen	Verschijnt één keer, "vergeten" in lange chats
User message injectie	Recency bias, periodieke refresh	Elke injectie kost tokens
Tool result injectie	Meest natuurlijke injectiepunt	Werkt alleen wanneer tools worden aangeroepen

Hoe Claude Code Het Daadwerkelijk Gebruikt

Voorwaarde — declareer de tags in de 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.

Deze stap is kritiek: het vertelt het model dat deze tags door het systeem zijn geïnjecteerd, en niet door de gebruiker zijn getypt.

Gebruik 1: Gedragsreminders (periodieke 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 gebruikt dit om het model eraan te herinneren te plannen met TodoWrite — omdat modellen de neiging hebben om planning te "vergeten" en gewoon te beginnen met coderen.

Gebruik 2: Mode Switching (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>

Plan mode is niet geïmplementeerd in de system prompt. Het is een tag die wordt geïnjecteerd in het volgende user message. Hierdoor kun je dynamisch tussen modi schakelen zonder de system prompt aan te passen. Briljant.

Gebruik 3: Notificaties van Bestandsweizigingen

<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>

Wanneer een extern proces (linter, formatter, handmatige bewerking) een bestand wijzigt, stelt het systeem het model op de hoogte via een reminder — dit voorkomt beslissingen op basis van verouderde bestandsinhoud.

Gebruik 4: Dynamische Context (datums, projectregels)

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

Runtime context (datum, git-status, projectregels) wordt geïnjecteerd via user messages, niet hardcoded in de system prompt.

Schrijfrichtlijnen voor Reminders

Wikkel in XML tags (<system-reminder>) — het model kan systeem-injecties onderscheiden van wat de gebruiker zegt
Declareer tags vooraf in de system prompt — anders probeert het model mogelijk te reageren op de reminder
Injecteer niet in elk bericht — elke injectie kost tokens, injecteer alleen wanneer nodig
Houd het kort — een reminder is geen tweede system prompt, slechts 1-2 kritieke regels
Spreek de system prompt niet tegen — reminders vullen aan en versterken, ze overrulen niet
Gebruik voor dynamisch schakelen — plan mode, readonly mode, feature flags

Wanneer System Prompt vs. User Message Reminder te Gebruiken

Scenario	System Prompt	User Message Reminder
Roldefinitie	✅	❌
Veiligheidsrestricties	✅ Eerste declaratie	✅ Periodieke herhaling
Workflow methodologie	✅	❌
Mode switching (plan mode)	❌	✅
Bestandsweizigingen	❌	✅
Datum / environment info	✅ Initiële waarde	✅ Geüpdatete waarde
Gedragscorrectie	❌	✅
Tool usage reminders	✅ Regeldefinitie	✅ Uitvoerings-nudges

9. Prompt Cache — Bespaar 90% op Herhaalde Tokens

Anthropic's prompt caching laat je de statische prefix van je messages array cachen. Wanneer volgende verzoeken dezelfde prefix delen, raken ze de cache — wat geld bespaart en latency vermindert.

Voor agents is dit enorm belangrijk: je stuurt de system prompt + tool definities opnieuw mee bij elke afzonderlijke LLM-call binnen een conversatie.

De Belangrijkste Cijfers

Metriek	Waarde
Cache hit kosten	10% van de normale prijs (90% besparing)
Cache write kosten	125% van de normale prijs (25% premium op eerste write)
Cache TTL	5 minuten (verloopt als er geen verzoeken zijn)
Minimum cachebare lengte	1.024 tokens (Claude 3.5+)
Cache granulariteit	Prefix matching — vanaf het begin tot een gemarkeerd breakpoint
Maximum breakpoints	4

Hoe Dit Prompt Design Verandert

Kernprincipe: statische content eerst, dynamische content laatst.

✅ 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

De valkuil waar niemand je voor waarschuwt: Als je een dynamische timestamp in het midden van je system prompt zet, wordt alles daarna een cache miss. Bij. Elk. Verzoek. Eén timestamp op de verkeerde plek en je betaalt de volle mep voor duizenden tokens.

API Gebruik

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

Zelfs wanneer de conversatiegeschiedenis verandert, raken de eerste 3 breakpoints nog steeds de cache. Een conversatie van 10 beurten bespaart grofweg 40-60% op input token kosten.

Design Aanbevelingen

Geen hoogfrequente dynamische waarden in de system prompt — datum is prima (verandert dagelijks), precieze timestamps niet
Zet dynamische context (git-status, etc.) in user message injecties — niet in de system prompt, anders vernietig je de cache
Houd tool definities stabiel — voeg niet dynamisch tools toe of verwijder ze tijdens runtime
Gebruik een rolling window voor conversatiegeschiedenis — cache de eerste N berichten, alleen het nieuwste bericht is een cache miss

10. De Checklist

Nadat je je system prompt hebt geschreven, controleer je deze aan de hand van deze checklist:

Structuur

Staat de identiteit helemaal bovenaan?
Zijn veiligheidsrestricties gemarkeerd met IMPORTANT en herhaald aan het einde?
Is er een duidelijke scheiding van secties met headers?
Zijn voorbeelden gewikkeld in <example> tags?

Token Budget

Is jouw deel < 6.000 tokens?
Herhaal je geen informatie die al in de tool definities staat?
Wordt domeinkennis on-demand geladen, niet vooraf?
Geen langdradige lore of achtergrondverhalen van karakters?

Kwaliteit van de Regels

Is elke regel testbaar met waar/onwaar?
Gebruiken harde grenzen absolute taal (NEVER/MUST)?
Gebruiken zachte suggesties aanbevelingstaal (recommended/prefer)?
Leggen kritieke regels het waarom uit, niet alleen het wat?
Zijn er bidirectionele restricties (doe dit + doe dat niet)?

Agent Gedrag

Zijn er principes gegeven, in plaats van rigide stap-voor-stap procedures?
Is het "tool call denied" scenario afgehandeld?
Is de "obstakel tegengekomen" strategie afgehandeld (niet brute-force blijven proberen)?
Is er een context management strategie aanwezig (samenvattingsdrempel)?

Wat NIET te Doen

Geen geslijm of superlatieven?
Geen overbodige "je bent een behulpzame AI" declaraties?
Niet geschreven als een prompt chain?
Geen over-engineering (features waar niemand om vroeg)?

Als Ik Vandaag Opnieuw Zou Beginnen

Dit is exact wat ik zou doen:

Begin met identiteit + veiligheid in de eerste 3 regels. Twee zinnen over wie de agent is. Harde grenzen met NEVER/MUST. Herhaal veiligheidsregels aan het einde.
Schrijf je core workflow als principes, niet als stappen. Maximaal 4-5 bullet points. Gebruik "recommended" en "prefer" voor zachte regels, "NEVER" en "MUST" voor harde regels.
Budgetteer 1.500-6.000 tokens voor jouw deel. Tool definities voegen daar nog eens 5.000-15.000 aan toe. Als je boven de 6K zit, ben je waarschijnlijk kennis aan het dumpen die on-demand geladen zou moeten worden.
Structureer alles. Markdown headers, bullet lists, XML tags voor voorbeelden. Een gestructureerde prompt presteert altijd beter dan natuurlijk proza.
Bouw vanaf dag één mid-conversation reminders in. Declareer <system-reminder> in je system prompt. Injecteer reminders voor kritieke regels, mode switches en context updates.
Ontwerp voor de cache. Statische content eerst, dynamische content laatst. Zet nooit veranderende waarden in de body van je system prompt.

De ironie van al dit werk? De beste system prompts zijn kort. De custom instructies van Claude Code (exclusief tool definities) zijn verrassend beknopt. Elke regel verdient zijn plek.

Vroeger dacht ik dat prompt engineering draaide om het vinden van slimme trucjes. Nu denk ik dat het draait om discipline — minder zeggen, het preciezer zeggen, en erop vertrouwen dat het model de rest wel uitvogelt. Het model is slimmer dan je prompt. Ontwerp de omgeving, niet het gedrag.

Referenties

Bron	Belangrijkste Inzicht
Claude Code v2.0.14 System Prompt	Volledige referentie van de structuur van een productie agent prompt
Reddit: Understanding Claude Code's 3 System Prompt Methods	Deep dive in Output Styles / --append / --system-prompt, praktijkdata context rot
shareAI-lab/learn-claude-code	"Het model is de agent" filosofie, harness engineering methodologie
Anthropic Prompt Engineering Docs	Officiële prompt best practices
DeepAgents Framework	Summarization middleware, skills progressive disclosure
Excerpt: Het meeste van wat mensen denken dat belangrijk is aan system prompts, is dat helemaal niet. Na het reverse-engineeren van Claude Code en het bouwen van een AI-startup, is dit het complete playbook voor het ontwerpen van agent-omgevingen die écht werken.