Le Guide Complet pour Écrire des System Prompts d'Agents — Leçons du reverse-engineering de Claude Code

J'ai décompilé le system prompt de Claude Code, étudié le code source de DeepAgents et construit mon propre agent IA from scratch. La plupart des guides de prompt, c'est juste du vent.

Title: La vérité sur les System Prompts : Ce que j'ai appris en disséquant Claude Code Content: On nage en plein délire collectif dans le monde de l'IA en ce moment.

Tous les tutos vous disent d'écrire des system prompts comme si vous jetiez un sort — il suffirait de trouver la bonne incantation pour que le modèle obéisse. "Tu es un ingénieur senior EXTRÊMEMENT TALENTUEUX avec 20 ans d'expérience..." Ça vous parle ?

J'ai passé ces derniers mois à construire VibeCom, un conseiller startup IA qui effectue des études de marché approfondies et génère des analyses dignes d'un fonds de VC. En cours de route, j'ai fait de la rétro-ingénierie sur le system prompt de Claude Code, j'ai épluché le code source du middleware de DeepAgents, et j'ai cramé plus de crédits API que je ne veux bien l'admettre. La plus grande leçon ? La plupart des choses que les gens pensent importantes dans les system prompts ne le sont pas. Et ce qui compte vraiment, presque personne n'en parle.

Cet article est le guide complet — pas un survol de 5 minutes, mais tout ce que j'aurais aimé qu'on me dise avant de commencer. Prenez un café.

1. Philosophie de conception : Faites confiance au modèle

"Un agent est un modèle. Pas un framework. Pas une chaîne de prompts." — shareAI-lab/learn-claude-code

Cette idée a tout changé pour moi. Le LLM sait déjà comment raisonner, planifier et exécuter. Votre system prompt ne lui apprend pas à penser — il met en place l'environnement dans lequel il va travailler.

Voyez ça comme l'embauche d'un développeur senior. Vous ne lui donnez pas une checklist de 20 étapes pour chaque tâche. Vous lui dites : voici qui nous sommes, voici les limites, voici à quoi ressemble un bon résultat. Et ensuite, vous le laissez faire.

Votre system prompt a exactement quatre missions :

Lui dire qui il est — rôle et identité
Lui indiquer où sont les murs — contraintes de sécurité
Lui montrer ce qu'est un bon résultat — standards de qualité
Lui donner des outils — capacités et connaissances

C'est tout. Tout le reste n'est que du bruit.

L'état d'esprit "Harness" (L'environnement)

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

Votre system prompt est le manuel d'utilisation de cet environnement (harness). Vous ne concevez pas un pipeline rigide — vous concevez un environnement où le modèle peut faire de son mieux de manière autonome.

N'écrivez pas votre system prompt comme un organigramme. Le modèle décidera lui-même de l'ordre d'exécution.

2. Structure du prompt et ordre des sections

La structure recommandée (Rétro-ingénierie de 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]                               │
└─────────────────────────────────────────────┘

Pourquoi cet ordre est crucial

Les LLMs ont une courbe d'attention en U — ils prêtent le plus d'attention au début et à la fin de votre prompt, et décrochent au milieu. C'est l'effet "Lost in the Middle" (Perdu au milieu), et c'est très bien documenté.

Identité + Sécurité tout en haut : Le modèle établit son rôle et ses limites en premier (effet de primauté).
Workflow principal au milieu-haut : Votre section la plus importante — comment l'agent fait son travail.
Les définitions d'outils sont injectées par le système après votre prompt : Les définitions d'outils de Claude Code consomment environ 11 438 tokens. Cela signifie que votre contenu personnalisé se retrouve en fait plus près du début que vous ne le pensez — ce qui aide au respect des consignes.
Rappels à la fin : Exploitez le biais de récence pour renforcer les règles critiques.

3. Rédiger chaque section

3.1 Identité — Qui est cet agent ?

Objectif : Ancrer le rôle du modèle en 1 à 3 phrases.

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

Lignes directrices :

Restez concis — 1 à 3 phrases maximum.
Nommez le rôle explicitement (aide le modèle à distinguer les contextes).
Énoncez la responsabilité principale ("aide avec X"), pas un vague "tu es un assistant utile".
Mentionnez le SDK/la plateforme si applicable ("basé sur le Claude Agent SDK d'Anthropic").

Anti-patterns :

"Tu es un assistant IA utile, inoffensif et honnête" — trop générique, aucun ancrage de rôle.
Un paragraphe entier de backstory et de lore — gaspille des tokens, le modèle n'a pas besoin de développement de personnage.

3.2 Sécurité & Garde-fous — Les limites strictes

Objectif : Fixer des contraintes comportementales inviolables.

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.

Lignes directrices :

Utilisez le préfixe IMPORTANT: — l'entraînement de Claude sur la hiérarchie des instructions donne un poids supplémentaire à cela.
Utilisez un langage absolu : NEVER, MUST NOT, Refuse to.
Indiquez à la fois ce qui est permis ET ce qui est interdit (les contraintes bidirectionnelles sont plus claires).
Placez-les tout en haut, pas enfouis au milieu.
Répétez les règles de sécurité critiques à la fin — Claude Code fait exactement ça.

Pourquoi répéter ? Effet de primauté (début) + Effet de récence (fin) = double renforcement. La déclaration de sécurité de Claude Code apparaît à la fois au début et à la fin du prompt. Pas parce que les ingénieurs étaient tête en l'air — parce qu'ils comprennent la courbe d'attention en U.

3.3 Ton & Style — Contrôler la sortie

Objectif : Contrôler le format de sortie et la voix.

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

Lignes directrices :

Listez des comportements spécifiques, pas un vague "sois professionnel".
Chaque règle doit pouvoir être testée (vrai/faux) ("court et concis" vs "essaie d'être bref").
Incluez les exigences de format de sortie (markdown ? JSON ? texte brut ?).
Incluez ce qu'il NE FAUT PAS faire — beaucoup de problèmes de style concernent des comportements à interdire.

La pépite de Claude Code — L'objectivité professionnelle :

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.

Ce paragraphe est crucial : il bloque la tendance à la complaisance (sycophancie) du modèle. Si votre agent doit donner des jugements objectifs (revue de code, évaluation d'idées, décisions d'architecture), vous avez absolument besoin d'une clause similaire.

3.4 Workflow Principal — La section la plus importante

Objectif : Apprendre au modèle comment travailler — la méthodologie, pas des procédures rigides.

C'est la section la plus difficile à bien écrire, et celle qui a le plus d'impact quand elle est réussie.

Le principe fondamental : donnez des principes, pas des procédures.

Dites au LLM à quoi ressemble un bon résultat et pourquoi il est bon — laissez-le trouver comment y arriver. Évitez de prescrire des nombres exacts de champs, des séquences d'étapes ou des formats, à moins que la sortie ne soit consommée par des machines en aval.

L'approche de 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

Remarquez le mot "recommended" (recommandé) — et non "tu dois suivre ces étapes exactes". Ce simple choix de mot donne au modèle la marge de manœuvre pour s'adapter.

Une bonne définition de workflow :

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

Chaque règle a un "pourquoi" implicite — le modèle peut comprendre l'intention et généraliser à de nouveaux scénarios.

Anti-patterns :

Une procédure rigide en 20 étapes — le modèle l'exécutera mécaniquement et bloquera sur des inputs inattendus.
"Fais d'abord A, puis B, puis C" — c'est une chaîne de prompts, pas un prompt d'agent.
Sur-guider des choses pour lesquelles le LLM est déjà doué — gaspille des tokens.

Je l'ai appris à mes dépens avec VibeCom. Les premières versions avaient un workflow de recherche en 10 étapes. Le modèle exécutait consciencieusement les 10 étapes même quand l'étape 3 répondait déjà à la question de l'utilisateur. Quand je suis passé aux principes ("cherche jusqu'à ce que tu aies des preuves suffisantes, puis synthétise"), la qualité a augmenté et les coûts en tokens ont baissé.

L'exception : Quand la sortie est consommée par des machines en aval (communication inter-agents, formats de réponse API), vous devez définir des formats stricts. Les principes sont pour le comportement ; les schémas sont pour les interfaces.

3.5 Politique d'utilisation des outils — Résoudre l'ambiguïté

Objectif : Quand plusieurs outils peuvent faire la même chose, dites au modèle lequel privilégier.

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

Lignes directrices :

Utilisez "instead of" (au lieu de) pour exprimer la priorité (A au lieu de B).
Expliquez pourquoi préférer certains outils ("offre une meilleure expérience utilisateur", "réduit l'utilisation du contexte").
Définissez la stratégie de parallélisme (indépendant → parallèle, dépendant → séquentiel).
Listez les contraintes de sécurité pour l'utilisation des outils (validation des chemins, vérification des permissions).

La relation cruciale entre les outils et les prompts :

Les définitions d'outils sont généralement injectées par le système et vous ne pouvez pas les modifier directement. Les définitions d'outils de Claude Code font environ 11 438 tokens. Cela signifie :

Ne répétez pas les informations déjà présentes dans les définitions d'outils.
Utilisez le system prompt pour des conseils stratégiques : quand utiliser chaque outil, pourquoi en préférer un à un autre, l'ordre de priorité.
La qualité de la définition des outils impacte directement l'efficacité de l'agent — si vous construisez votre propre agent, investissez du temps pour écrire d'excellentes descriptions d'outils.

3.6 Connaissance du domaine — Charger à la demande, pas en amont

Objectif : Fournir des connaissances spécialisées qui pourraient manquer dans les données d'entraînement du modèle.

Le principe clé : la divulgation progressive, pas le déversement de connaissances.

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

Cette stratégie est partagée par le système de Skills de Claude Code et le middleware de Divulgation Progressive de DeepAgents. Les deux chargent les connaissances à la demande via des appels d'outils plutôt que de tout précharger.

Approches d'implémentation :

Mettre des pointeurs dans le system prompt : "Utilise l'outil get_api_docs pour récupérer la documentation quand nécessaire".
Utiliser CLAUDE.md / AGENTS.md pour le contexte du projet — chargé à l'exécution, pas codé en dur.
Utiliser Skills / SKILL.md pour la découverte de capacités — le modèle voit un menu de compétences disponibles, et récupère les spécifications complètes à la demande.

3.7 Infos d'environnement — Contexte d'exécution

Objectif : Donner au modèle la conscience de son environnement d'exécution.

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

Lignes directrices :

Générez dynamiquement, ne codez jamais en dur.
Incluez : répertoire de travail, plateforme, date, nom du modèle, statut git.
Utilisez un format structuré (balises XML ou blocs de code) pour faciliter le parsing.
La date compte — le modèle a besoin de connaître "maintenant" pour juger de la fraîcheur des informations.

3.8 Rappels — Le renforcement final

Objectif : Réaffirmer les règles les plus critiques à la fin du prompt.

Claude Code répète sa contrainte de sécurité et son exigence TodoWrite tout en bas :

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

Lignes directrices :

Ne répétez que 2 ou 3 des règles les plus critiques — ne dupliquez pas tout.
Exploitez le biais de récence — le modèle se souvient plus fortement du contenu récent.
Meilleurs candidats : contraintes de sécurité, règles les plus souvent violées, rappels du workflow principal.

4. Budget de tokens et gestion du contexte

Référence d'allocation du budget

Section	Tokens Recommandés	Notes
Identité + Sécurité	200-500	Concis mais non négociable
Ton & Style	300-800	Les règles doivent être spécifiques, sans blabla
Workflow Principal	500-2,000	Section la plus importante, vaut l'investissement
Politique d'Outils	300-1,000	Dépend du nombre d'outils
Connaissance du Domaine	0-1,000	Chargement à la demande privilégié
Infos d'Environnement	100-300	Généré dynamiquement
Rappels	100-300	Ne répétez que l'essentiel
Votre total	1,500-6,000
Définitions d'Outils (système)	5,000-15,000	Hors de votre contrôle

Courbe de dégradation du contexte

Les tests de la communauté (Reddit u/CodeMonkey_) ont cartographié la dégradation réelle du respect des consignes :

< 80K tokens : Le respect du prompt reste stable
80K - 120K tokens : Le suivi des instructions commence à se dégrader
> 120K tokens : Dégradation significative — le modèle "oublie" les premières instructions
> 180K tokens : Dégradation sévère

Votre fenêtre de contexte de 200K ≠ 200K de contexte effectif. Planifiez en conséquence.

Stratégies d'atténuation :

Gardez votre system prompt léger (< 6 000 tokens pour votre partie).
Utilisez la summarization pour compresser l'historique de conversation (DeepAgents se déclenche à ~80K caractères).
Placez les règles critiques aux deux extrémités du prompt (attention en U).
Injectez des balises <system-reminder> en cours de conversation (plus de détails dans la section 8).

5. Principes de rédaction

5.1 Donnez des principes, pas des procédures

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

Les principes se généralisent. Les procédures ne peuvent être suivies que mécaniquement. Quand le modèle rencontre une situation que vous n'aviez pas anticipée, les principes guident la bonne décision. Les procédures, non.

Exception : Quand la sortie est consommée par des machines (communication inter-agents, formats API), définissez des schémas stricts.

5.2 Utilisez un langage absolu pour les contraintes strictes

Force	Langage	À utiliser pour
Interdiction absolue	`NEVER`, `MUST NOT`	Sécurité, opérations irréversibles
Exigence forte	`ALWAYS`, `MUST`	Règles du workflow principal
Recommandation	`recommended`, `prefer`	Bonnes pratiques avec exceptions
Suggestion	`consider`, `you may`	Optimisations optionnelles

Exemples de Claude Code :

NEVER update the git config — interdiction absolue
ALWAYS prefer editing an existing file — fort, mais des exceptions existent
The following steps are recommended — workflow suggéré

5.3 Utilisez des exemples au lieu d'explications

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

Un exemple enseigne mieux que 100 mots d'explication :

Les modèles apprennent les motifs à partir d'exemples de manière plus fiable qu'à partir de descriptions abstraites.
Enveloppez avec des balises <example> pour séparer des règles.
Fournissez des exemples positifs ("fais ça") et négatifs ("ne fais pas ça").
Utilisez des exemples réels et spécifiques — pas des placeholders "foo/bar".

5.4 Contraintes bidirectionnelles

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

Dire seulement "fais ça" → le modèle ne sait pas quand NE PAS le faire. Dire seulement "ne fais pas ça" → le modèle ne connaît pas l'alternative. Bidirectionnel → clair et sans ambiguïté.

5.5 Expliquez pourquoi, pas seulement quoi

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

Expliquer le pourquoi permet au modèle de prendre les bonnes décisions dans les cas particuliers. Le protocole de sécurité git de Claude Code est une masterclass — chaque règle implique sa justification.

5.6 La structure prime sur la prose

En-têtes Markdown (##, ###) — les modèles reconnaissent la hiérarchie.
Listes à puces plutôt que des paragraphes — chaque règle est testable indépendamment.
Balises XML pour le contenu spécial : <example>, <env>, <system-reminder>.
Tableaux pour les comparaisons et les mappings.
Ne balancez jamais de texte non structuré — les prompts structurés surpassent systématiquement la prose en langage naturel dans les tests de respect des consignes.

6. Les Anti-Patterns qui gaspillent vos tokens

Les chaînes de prompts déguisées en 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."

Ce n'est pas un prompt d'agent — c'est un script de pipeline. Le modèle l'exécutera mécaniquement et perdra sa capacité de planification autonome.

La solution : Dites au modèle l'objectif et les contraintes. Laissez-le décider des étapes.

L'ingénierie de la flatterie

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

Les compliments et les superlatifs n'améliorent pas la qualité de la sortie. Le modèle n'a pas d'ego à flatter. Gardez ces 15 tokens pour une vraie règle.

Le déversement de connaissances (Knowledge Dumps)

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

Cela dévore votre fenêtre de contexte et accélère la pourriture du contexte. Remplacez par un chargement à la demande :

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

Répéter la description des outils

Si la définition de l'outil dit déjà "L'outil Read lit un fichier depuis le système de fichiers", ne le répétez pas dans votre system prompt. Ajoutez uniquement des conseils stratégiques que la définition de l'outil ne couvre pas — quand l'utiliser, pourquoi le préférer, l'ordre de priorité.

Oublier la gestion des échecs

Sans conseils explicites, les modèles réessayeront des appels d'outils échoués dans une boucle infinie. Incluez toujours :

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

Ignorer la dégradation de la fenêtre de contexte

Une fenêtre de contexte de 200K ≠ 200K de contexte effectif. Les tests en conditions réelles montrent que la dégradation commence à 80K. Vous avez besoin d'une stratégie de summarization.

7. Points d'injection et priorité

Les trois méthodes de personnalisation de Claude Code

Méthode	Remplace	Emplacement	Idéal pour
Output Styles	Sections "Tone and style" + "Doing tasks"	Juste avant les définitions d'outils	Changer le style d'interaction
--append-system-prompt	Rien (additif)	Après output style, avant les outils	Ajouter des comportements spécifiques
--system-prompt	Tout le system prompt	Garde les outils + une ligne d'identité	Personnalisation totale (l'option nucléaire)

Si vous en utilisez plusieurs : Output Style → Append Prompt → Tool Definitions

Hiérarchie des instructions

Claude est spécifiquement entraîné avec une hiérarchie d'instructions :

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

Cela signifie :

Les règles de CLAUDE.md écrasent le comportement du system prompt par défaut.
Les requêtes directes de l'utilisateur écrasent tout le reste.
Votre prompt personnalisé écrase le prompt par défaut.

Mécanismes d'injection dynamique

<system-reminder> — injecté dans n'importe quel message en cours de conversation pour rappeler au modèle les règles critiques.
CLAUDE.md / AGENTS.md — chargés à l'exécution depuis des fichiers, ajoutés au system prompt.
Skills / SKILL.md — chargés à la demande via des appels d'outils, zéro empreinte sur le system prompt.

8. L'injection en cours de conversation — L'arme secrète

Le system prompt n'apparaît qu'une seule fois, tout au début du tableau des messages. Mais les LLMs acceptent le tableau complet des messages (alternant utilisateur / assistant / outil) comme input, et vous pouvez aussi injecter des prompts dans les messages utilisateur et les résultats d'outils. Claude Code utilise massivement cette technique en production.

Pourquoi c'est nécessaire

Combattre la pourriture du contexte (context rot). À mesure que les conversations s'allongent, le respect des instructions du system prompt par le modèle se dégrade (perceptible à 80K+ tokens). Injecter des rappels en cours de conversation = rafraîchir les règles via le biais de récence.

Le modèle mental :

System prompt = la constitution (établie une fois, autorité à long terme)
Rappels dans les messages utilisateur = mémos (envoyés périodiquement, maintiennent l'application)

Trois points d'injection dans le tableau des messages

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
└─────────────────────────────────────┘

Emplacement	Avantage	Inconvénient
System prompt	Effet de primauté, lu en premier	Apparaît une fois, "oublié" dans les longues convs
Injection msg utilisateur	Biais de récence, rafraîchissement	Chaque injection coûte des tokens
Injection résultat outil	Point d'injection le plus naturel	Ne fonctionne que quand des outils sont appelés

Comment Claude Code l'utilise concrètement

Prérequis — déclarer les balises dans le 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.

Cette étape est critique : elle indique au modèle que ces balises sont injectées par le système, et non des paroles de l'utilisateur.

Usage 1 : Rappels comportementaux (rafraîchissement périodique des règles)

<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 utilise cela pour rappeler au modèle de planifier avec TodoWrite — parce que les modèles ont tendance à "oublier" de planifier et commencent juste à coder.

Usage 2 : Changement de mode (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>

Le mode Plan n'est pas implémenté dans le system prompt. C'est une balise injectée dans le prochain message utilisateur. Cela permet de basculer de mode dynamiquement sans modifier le system prompt. Brillant.

Usage 3 : Notifications de modification de fichier

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

Quand un processus externe (linter, formateur, édition manuelle) modifie un fichier, le système notifie le modèle via un rappel — évitant ainsi des décisions basées sur un contenu de fichier obsolète.

Usage 4 : Contexte dynamique (dates, règles du projet)

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

Le contexte d'exécution (date, statut git, règles du projet) est injecté via les messages utilisateur, pas codé en dur dans le system prompt.

Lignes directrices pour rédiger des rappels

Enveloppez dans des balises XML (<system-reminder>) — le modèle peut distinguer l'injection système de la parole de l'utilisateur.
Pré-déclarez les balises dans le system prompt — sinon le modèle pourrait essayer de répondre au rappel.
N'injectez pas à chaque message — chaque injection coûte des tokens, n'injectez que lorsque c'est nécessaire.
Faites court — un rappel n'est pas un deuxième system prompt, juste 1 ou 2 règles critiques.
Ne contredisez pas le system prompt — les rappels complètent et renforcent, ils n'écrasent pas.
Utilisez-les pour des bascules dynamiques — mode plan, mode lecture seule, feature flags.

Quand utiliser le System Prompt vs. le Rappel dans un message

Scénario	System Prompt	Rappel Message Utilisateur
Définition du rôle	✅	❌
Contraintes de sécurité	✅ Première déclaration	✅ Répétition périodique
Méthodologie du workflow	✅	❌
Changement de mode	❌	✅
Notifs de modif de fichier	❌	✅
Date / infos d'environnement	✅ Valeur initiale	✅ Valeur mise à jour
Correction comportementale	❌	✅
Rappels d'utilisation d'outils	✅ Définition règle	✅ Coups de pouce (nudges)

9. Prompt Cache — Économisez 90% sur les tokens répétés

Le prompt caching d'Anthropic vous permet de mettre en cache le préfixe statique de votre tableau de messages. Quand les requêtes suivantes partagent le même préfixe, elles tapent dans le cache — ce qui fait gagner de l'argent et réduit la latence.

Pour les agents, c'est énorme : vous renvoyez le system prompt + les définitions d'outils à chaque appel LLM au sein d'une conversation.

Les chiffres clés

Métrique	Valeur
Coût d'un Cache hit	10% du prix normal (90% d'économies)
Coût d'écriture en cache	125% du prix normal (prime de 25% sur la 1ère écriture)
TTL du cache	5 minutes (expire s'il n'y a pas de requêtes)
Longueur min. cachable	1 024 tokens (Claude 3.5+)
Granularité du cache	Correspondance de préfixe — du début jusqu'à un point d'arrêt
Points d'arrêt max	4

Comment cela change la conception des prompts

Principe fondamental : contenu statique en premier, contenu dynamique en dernier.

✅ 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

Le piège dont personne ne vous parle : Si vous mettez un horodatage dynamique au milieu de votre system prompt, tout ce qui suit devient un cache miss. À. Chaque. Requête. Un seul timestamp au mauvais endroit et vous payez le prix fort sur des milliers de tokens.

Utilisation de l'API

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: [...]
});

Stratégie multi-points d'arrêt

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

Même quand l'historique de conversation change, les 3 premiers points d'arrêt tapent toujours dans le cache. Une conversation de 10 échanges permet d'économiser environ 40 à 60% sur les coûts des tokens d'entrée.

Recommandations de conception

Pas de valeurs dynamiques à haute fréquence dans le system prompt — la date c'est ok (change tous les jours), les timestamps précis non.
Mettez le contexte dynamique (statut git, etc.) dans les injections de messages utilisateur — pas dans le system prompt, sinon vous détruisez le cache.
Gardez les définitions d'outils stables — n'ajoutez/ne supprimez pas dynamiquement des outils à l'exécution.
Utilisez une fenêtre glissante pour l'historique de conversation — mettez en cache les N premiers messages, seul le message le plus récent est un cache miss.

10. La Checklist

Après avoir rédigé votre system prompt, passez-le en revue avec cette checklist :

Structure

L'identité est-elle tout en haut ?
Les contraintes de sécurité sont-elles marquées avec IMPORTANT et répétées à la fin ?
Séparation claire des sections avec des en-têtes ?
Exemples enveloppés dans des balises <example> ?

Budget de Tokens

Votre partie fait-elle < 6 000 tokens ?
Vous ne répétez pas des informations déjà présentes dans les définitions d'outils ?
Connaissance du domaine chargée à la demande, pas préchargée ?
Pas de lore verbeux ou de backstory de personnage ?

Qualité des Règles

Chaque règle est-elle testable (vrai/faux) ?
Les contraintes strictes utilisent-elles un langage absolu (NEVER/MUST) ?
Les suggestions douces utilisent-elles un langage de recommandation (recommended/prefer) ?
Les règles critiques expliquent-elles le pourquoi, pas seulement le quoi ?
Contraintes bidirectionnelles (fais ça + ne fais pas ça) ?

Comportement de l'Agent

Principes donnés, pas des procédures étape par étape rigides ?
Scénario "appel d'outil refusé" géré ?
Stratégie "obstacle rencontré" gérée (ne pas réessayer en force brute) ?
Stratégie de gestion du contexte en place (seuil de summarization) ?

Ce qu'il NE FAUT PAS faire

Pas de flatterie ou d'adjectifs superlatifs ?
Pas de déclarations redondantes "tu es une IA utile" ?
Pas écrit comme une chaîne de prompts ?
Pas de sur-ingénierie (fonctionnalités que personne n'a demandées) ?

Si je devais recommencer aujourd'hui

Voici exactement ce que je ferais :

Commencez par l'identité + la sécurité dans les 3 premières lignes. Deux phrases pour définir qui est l'agent. Des contraintes strictes avec NEVER/MUST. Répétez les règles de sécurité à la fin.
Écrivez votre workflow principal sous forme de principes, pas d'étapes. Max 4-5 points. Utilisez "recommended" et "prefer" pour les règles souples, "NEVER" et "MUST" pour les règles strictes.
Prévoyez un budget de 1 500 à 6 000 tokens pour votre partie. Les définitions d'outils en ajouteront 5 000 à 15 000 de plus. Si vous dépassez les 6K, vous êtes probablement en train de déverser des connaissances qui devraient être chargées à la demande.
Structurez tout. En-têtes Markdown, listes à puces, balises XML pour les exemples. Un prompt structuré surpasse toujours la prose en langage naturel.
Intégrez des rappels en cours de conversation dès le premier jour. Déclarez <system-reminder> dans votre system prompt. Injectez des rappels pour les règles critiques, les changements de mode et les mises à jour de contexte.
Concevez pour le cache. Contenu statique en premier, contenu dynamique en dernier. Ne mettez jamais de valeurs changeantes dans le corps de votre system prompt.

L'ironie de tout ce travail ? Les meilleurs system prompts sont courts. Les instructions personnalisées de Claude Code (hors définitions d'outils) sont étonnamment concises. Chaque ligne mérite sa place.

Avant, je pensais que le prompt engineering consistait à trouver des astuces intelligentes. Maintenant, je pense que c'est une question de discipline — dire moins, le dire précisément, et faire confiance au modèle pour trouver le reste. Le modèle est plus intelligent que votre prompt. Concevez l'environnement, pas le comportement.

Références

Source	Insight Clé
Claude Code v2.0.14 System Prompt	Référence complète de la structure d'un prompt d'agent en production
Reddit: Understanding Claude Code's 3 System Prompt Methods	Plongée dans Output Styles / --append / --system-prompt, données réelles sur la pourriture du contexte
shareAI-lab/learn-claude-code	Philosophie "Le modèle est l'agent", méthodologie d'ingénierie du harness
Anthropic Prompt Engineering Docs	Bonnes pratiques officielles pour les prompts
DeepAgents Framework	Middleware de summarization, divulgation progressive des compétences (skills)
Excerpt: La plupart des choses que les gens pensent importantes dans les system prompts ne le sont pas. Voici le guide complet sur ce qui compte vraiment, basé sur la rétro-ingénierie de Claude Code.