Un prompt qui fonctionne parfaitement pendant vos tests peut devenir instable une fois placé dans une application réelle.
Claude peut retourner la bonne information dans le mauvais format, modifier progressivement son comportement au fil d’une conversation, inventer une structure que votre programme n’attend pas ou échouer uniquement sur certains cas particuliers.
L’erreur classique consiste alors à ajouter toujours plus d’instructions au prompt.
En production, une meilleure approche consiste à commencer par identifier pourquoi le prompt échoue, puis à appliquer la technique correspondant précisément au problème.
Quatre techniques jouent ici un rôle essentiel :
system prompts;- balises XML ;
few-shot examples;output constraints.
Et lorsque le format doit être garanti par l’application, l’API Claude permet d’aller plus loin avec les structured outputs.
1. Un bon prompt de test n’est pas forcément un bon prompt de production
Prenons un cas très simple.
Nous voulons classifier les tickets d’un support client dans trois catégories :
BILLINGTECHNICALESCALATION
On pourrait commencer avec :
System:
You are a support classifier.
Classify the ticket.
User:
<ticket>
I was charged twice for the same month.
</ticket>
Claude comprend parfaitement la demande.
Le problème est qu’il peut répondre :
Billing
ou :
billing
ou encore :
This looks like a billing issue.
Pour un humain, ces trois réponses signifient pratiquement la même chose.
Pour une application qui attend exactement :
BILLING
elles sont différentes.
Le problème n’est donc pas la compréhension de la tâche.
Le problème est la forme de la sortie.
2. Diagnostiquer avant de modifier le prompt
C’est l’un des principes les plus importants du Production-Grade Prompting.
Lorsqu’un résultat n’est pas satisfaisant, ne commencez pas automatiquement par reformuler ou allonger votre prompt.
Commencez par identifier le type d’échec.
| Problème observé | Élément probablement manquant |
|---|---|
| Mauvais format de sortie | output constraint |
| Mauvais contenu ou dérive du périmètre | system prompt insuffisamment précis |
| Bonne tâche mais structure inventée | few-shot examples |
| Fonctionne sur les cas simples mais échoue sur un cas particulier | contrainte ou exemple couvrant cet edge case |
Cette grille est importante parce que les quatre techniques ne résolvent pas le même problème.
3. Les System Prompts : définir le contrat comportemental
Le system prompt définit les règles générales qui doivent rester valables pendant toute la session.
Il peut notamment définir :
- le rôle de Claude ;
- son périmètre ;
- les règles à respecter ;
- le format attendu ;
- les comportements qui doivent rester constants entre les différents tours.
Reprenons notre classifier.
Version trop vague
You are a support classifier.
Classify the ticket.
Le rôle est défini, mais le contrat est insuffisant.
Claude sait qu’il doit classifier.
Il ne sait pas précisément comment la réponse doit être produite.
On peut renforcer le contrat :
You are a support classifier.
Classify each ticket into exactly one of:
BILLING
TECHNICAL
ESCALATION
Return only the label.
No other text.
Cette version définit beaucoup mieux le comportement attendu.
À retenir
Le system prompt doit contenir les règles qui doivent rester stables indépendamment du message utilisateur courant.
Il constitue le contrat comportemental persistant de la session.
4. XML : séparer clairement les différentes parties du prompt
Lorsque les prompts deviennent plus complexes, il devient important de distinguer clairement :
- les instructions ;
- les données ;
- les exemples ;
- le contenu utilisateur.
Claude peut utiliser des balises XML pour structurer ces différentes zones.
Par exemple :
<ticket>
I was charged twice for the same month.
</ticket>
Pour les exemples :
<sample_input>
My account shows two charges for April.
</sample_input>
<ideal_output>
BILLING
</ideal_output>
Cette structure rend explicite la fonction de chaque élément.
Le principe n’est pas que les noms de balises possèdent une signification magique.
Ils servent avant tout à créer des frontières explicites dans le contexte.
5. Few-shot examples : montrer plutôt que seulement expliquer
Supposons maintenant que nous voulions que Claude retourne exactement les labels attendus.
Nous pouvons lui fournir des exemples.
<sample_input>
My account shows two charges for April.
</sample_input>
<ideal_output>
BILLING
</ideal_output>
<sample_input>
The API keeps returning a 429 error.
</sample_input>
<ideal_output>
TECHNICAL
</ideal_output>
Claude dispose désormais d’exemples explicites montrant :
- le type d’entrée ;
- le type de sortie ;
- le format ;
- la casse ;
- le niveau de verbosité attendu.
C’est le principe du few-shot prompting.
Au lieu de seulement décrire le résultat souhaité, nous montrons à Claude des exemples du comportement attendu.
6. Output Constraints : imposer la forme attendue
Dans une application, le format peut être aussi important que le contenu.
Une contrainte comme :
Return only the label.
est utile.
Mais elle peut être rendue encore plus précise :
Classify each ticket into exactly one of:
BILLING
TECHNICAL
ESCALATION
Return only the label.
No other text.
Cette contrainte définit :
- les valeurs autorisées ;
- le nombre de valeurs à retourner ;
- l’absence de texte supplémentaire.
On évite ainsi des réponses telles que :
BILLING / TECHNICAL
ou :
This ticket should be classified as BILLING.
7. Combiner les quatre techniques
Ces techniques peuvent être utilisées ensemble lorsque la tâche le justifie.
Voici une version plus robuste de notre classifier :
System:
You are a support classifier.
Classify each ticket into exactly one of:
BILLING
TECHNICAL
ESCALATION
Return only the label.
No other text.
<sample_input>
My account shows two charges for April.
</sample_input>
<ideal_output>
BILLING
</ideal_output>
<sample_input>
The API keeps returning a 429 error.
</sample_input>
<ideal_output>
TECHNICAL
</ideal_output>
Puis :
<ticket>
I was charged twice for the same month.
</ticket>
Chaque élément possède une fonction différente.
System prompt
→ définit le comportement.
XML
→ sépare clairement les différentes zones.
Few-shot examples
→ montrent le comportement attendu.
Output constraint
→ définit précisément les sorties acceptables.
8. Faut-il toujours utiliser les quatre techniques ?
Non.
C’est justement un piège à éviter.
Une tâche simple comme :
Summarize this paragraph.
n’a pas nécessairement besoin :
- d’un long
system prompt; - de cinq exemples ;
- d’une structure XML complexe ;
- d’un schéma de sortie élaboré.
Le principe est plutôt :
Ajouter la structure nécessaire au problème observé, et pas de la complexité par défaut.
Si un prompt devient de plus en plus long à chaque tentative sans devenir plus fiable, il faut arrêter de l’allonger et revenir au diagnostic.
9. Le piège du prompt qui devient toujours plus long
Le module présente un scénario particulièrement instructif.
Un développeur commence avec :
Classify this ticket as billing, technical, or escalation.
Claude retourne :
This appears to be a billing issue.
Le parser échoue.
Le développeur ajoute :
Be concise.
Use only the category name.
Claude retourne parfois :
Billing
et parfois :
billing
Le routeur reste instable.
Le développeur ajoute alors plusieurs paragraphes expliquant précisément ce qu’est un ticket de facturation, un ticket technique et une escalade.
Sur un ticket ambigu, Claude retourne :
billing/technical
Le développeur ajoute :
Never return two categories.
If ambiguous, choose the most likely one.
Puis encore davantage d’explications sur les cas particuliers.
Le prompt devient progressivement beaucoup plus long.
Mais le problème fondamental n’a toujours pas été traité correctement.
10. Pourquoi cette approche échoue
Deux problèmes apparaissent.
Premier problème : mauvais diagnostic
Le développeur améliore la description des catégories alors que le problème principal concerne la contrainte de sortie.
Il améliore donc la mauvaise partie du prompt.
Deuxième problème : verbosité inutile
Un prompt excessivement long peut également entraîner des sorties plus longues et augmenter :
- le nombre de tokens ;
- la latence ;
- le coût.
Le module illustre finalement une solution beaucoup plus structurée :
- un format précisément défini ;
- un
output constraint; - quelques exemples représentatifs.
La leçon est importante :
Un prompt plus long n’est pas nécessairement un prompt plus précis.
11. Quand les contraintes dans le prompt ne suffisent plus
Jusqu’ici, nous demandons à Claude de respecter un format avec des instructions telles que :
Return only JSON.
Cela peut être suffisamment fiable pour certaines applications.
Mais une application de production peut avoir besoin d’une garantie plus forte.
Supposons que votre programme attende :
{
"category": "billing",
"urgency": "high",
"summary": "Customer reports a duplicate charge."
}
Si Claude ajoute :
Here is the result:
avant le JSON, votre parser peut échouer.
S’il change :
"category"
en :
"ticket_category"
votre application peut également échouer.
C’est ici qu’interviennent les structured outputs.
12. Structured Outputs : déplacer la contrainte dans l’API
Avec les structured outputs, la structure attendue n’est plus uniquement exprimée en langage naturel dans le prompt.
L’application fournit un JSON Schema.
Le mécanisme utilise du constrained decoding : la génération est contrainte afin de rester compatible avec le schéma défini.
Autrement dit, on passe de :
Please return JSON with these fields...
à une contrainte définie directement au niveau de l’API.
Deux mécanismes sont particulièrement importants.
13. JSON Outputs
Les JSON outputs permettent de contraindre la réponse finale de Claude.
Le schéma définit par exemple :
{
"type": "object",
"properties": {
"category": {
"type": "string"
},
"urgency": {
"type": "string"
},
"summary": {
"type": "string"
}
},
"required": [
"category",
"urgency",
"summary"
]
}
Le module indique que cette approche utilise output_config.format avec un type json_schema.
Elle est particulièrement adaptée lorsque votre programme consomme directement la sortie structurée de Claude.
Par exemple :
Ticket utilisateur
→ Claude
→ JSON structuré
→ application
→ traitement automatique
Cela réduit le besoin d’écrire une logique du type :
appel Claude
→ tentative de parsing
→ parsing échoue
→ nouveau prompt
→ nouvelle tentative
14. Strict Tool Use
Le même principe existe pour les arguments transmis aux tools.
Avec :
strict: true
sur la définition du tool, les arguments sont contraints par son input_schema.
Cette distinction est importante :
JSON outputs
Contraignent la réponse finale du modèle.
Strict tool use
Contraint les paramètres transmis aux tools.
C’est particulièrement utile dans une boucle agentique.
Un argument incorrect peut sinon :
- provoquer une erreur dans une fonction ;
- envoyer une mauvaise valeur ;
- déclencher une mauvaise opération.
15. Structured Outputs ne signifie pas « aucun contrôle nécessaire »
Une structure garantie ne signifie pas que tous les appels réussiront nécessairement.
Le module signale notamment deux situations à gérer.
Refusal
Claude peut refuser une demande pour des raisons de sécurité.
Le programme doit alors traiter le stop_reason correspondant.
Truncation
La génération peut atteindre max_tokens.
Dans ce cas, le programme doit également examiner le stop_reason.
La règle importante est donc :
Même avec des structured outputs, le programme doit vérifier pourquoi la génération s’est arrêtée.
16. Les compromis des Structured Outputs
Les structured outputs améliorent la fiabilité, mais ils ne sont pas gratuits.
Le module relève plusieurs coûts.
Première requête plus lente
Un nouveau schéma doit être transformé en grammaire utilisable pour contraindre la génération.
Cette compilation ajoute de la latence lors de la première utilisation.
Le module indique que les grammaires compilées sont ensuite mises en cache pendant une durée déterminée.
Tokens d’entrée supplémentaires
L’API ajoute des informations permettant au modèle de produire le format attendu.
Cela augmente légèrement le nombre de tokens d’entrée.
Incompatibilité avec certaines techniques
Le document indique notamment que les JSON outputs ne sont pas compatibles avec le message prefilling.
Il faut donc choisir la technique correspondant au besoin réel.
17. Prompt constraint ou Structured Output ?
On peut retenir cette distinction.
Prompt constraint
Return only one of:
BILLING
TECHNICAL
ESCALATION
Approprié lorsque l’on cherche principalement à guider Claude vers un format précis.
Structured Output
JSON Schema
Approprié lorsque le programme dépend structurellement de la validité de la réponse.
Plus le résultat est destiné à être traité automatiquement par du code, plus la garantie structurelle devient importante.
18. Exemple complet : classifier un ticket support
Partons d’un prompt insuffisant :
You are a support ticket processor.
Extract the key information from the ticket below.
Utilisateur :
<ticket>
My API key stopped working after I rotated it last night.
I have a production deployment that is failing.
This needs to be fixed immediately.
</ticket>
Le problème est évident du point de vue d’une application :
« Extract the key information » ne définit pas la structure attendue.
Claude pourrait retourner :
- trois paragraphes ;
- une liste ;
- du JSON ;
- un résumé ;
- une combinaison de plusieurs formats.
Une version plus robuste doit définir explicitement les informations et le format attendus.
Par exemple :
You are a support ticket processor.
For each ticket, extract:
- category
- urgency
- summary
Return exactly one JSON object.
category must be one of:
BILLING
TECHNICAL
ESCALATION
urgency must be one of:
LOW
MEDIUM
HIGH
summary must contain exactly one sentence.
Return no text outside the JSON object.
Le résultat attendu devient alors beaucoup plus prévisible.
Pour une application nécessitant une garantie de structure, l’étape suivante consiste à déplacer cette définition dans un JSON Schema via les structured outputs.
19. La boucle de diagnostic à retenir
Lorsqu’un prompt échoue :
Étape 1 — Observer
Qu’est-ce qui ne va pas exactement ?
Étape 2 — Classifier le problème
Est-ce :
- le format ?
- le contenu ?
- le périmètre ?
- la structure ?
- un
edge case?
Étape 3 — Appliquer la technique correspondante
Wrong format
→ Output constraint
Scope drift
→ System prompt
Invented structure
→ Few-shot examples
Boundary problem
→ XML / structuration explicite
Edge case
→ Constraint ou exemple supplémentaire
Étape 4 — Tester de nouveau
Ne modifiez qu’un nombre limité d’éléments à la fois afin de comprendre ce qui améliore réellement le résultat.
20. Ce qu’il faut retenir pour la certification
Principe n°1
Un mauvais résultat ne signifie pas automatiquement qu’il faut écrire un prompt plus long.
Il faut diagnostiquer le type d’échec.
Principe n°2
Les quatre techniques principales ont des rôles différents :
System prompt
→ comportement global
XML
→ séparation et structuration
Few-shot
→ démonstration du comportement attendu
Output constraint
→ forme de la réponse
Principe n°3
Un few-shot example montre une structure que des instructions abstraites ne suffisent pas toujours à stabiliser.
Principe n°4
Pour une sortie consommée automatiquement par une application, les structured outputs permettent de renforcer la garantie structurelle avec un JSON Schema.
Principe n°5
Il faut distinguer :
JSON outputs
→ contraignent la réponse finale
Strict tool use
→ contraint les arguments des tools
Principe n°6
Même avec des structured outputs, votre application doit vérifier les conditions d’arrêt et gérer notamment les refus et les générations interrompues.
Pièges fréquents à l’examen
Piège 1
« Le format varie, il faut augmenter l’effort de raisonnement. »
Non.
Un problème de format appelle d’abord une contrainte de sortie.
Piège 2
« Claude choisit parfois une structure différente, ajoutons trois paragraphes d’explications. »
Pas nécessairement.
Des few-shot examples peuvent être plus appropriés pour montrer exactement la structure attendue.
Piège 3
« Return only JSON garantit techniquement un JSON valide. »
Non.
Il s’agit d’une instruction donnée au modèle. Une garantie plus forte passe par les mécanismes de structured outputs.
Piège 4
« Un prompt de production doit toujours utiliser system prompt + XML + few-shot + output constraints. »
Non.
Il faut utiliser les techniques nécessaires à la tâche et au problème observé.
Piège 5
« Plus le prompt est détaillé, plus il est fiable. »
Pas automatiquement.
Un prompt doit surtout être précis et structurellement adapté au problème.
En résumé
Pour construire un prompt Claude robuste en production, retenez cette logique :
Observer l'échec
↓
Identifier sa cause
↓
Choisir la technique adaptée
↓
Contraindre ce qui doit l'être
↓
Tester sur les cas nominaux ET les edge cases
↓
Mesurer avant d'ajouter de la complexité
Le Production-Grade Prompting n’est donc pas l’art d’écrire les prompts les plus longs possible.
C’est l’art de construire le minimum de structure nécessaire pour obtenir un comportement suffisamment fiable pour l’application qui consomme le résultat.
Et lorsque cette fiabilité doit être garantie par le code plutôt que simplement demandée au modèle, il faut savoir déplacer la contrainte du prompt vers l’API grâce aux structured outputs.
Article suivant
Extended Thinking avec Claude : quand le raisonnement supplémentaire vaut-il son coût ?
Nous verrons comment activer le raisonnement, choisir le niveau d’effort, comprendre les thinking blocks et surtout éviter une erreur importante dans les boucles utilisant des tools : modifier ou supprimer un bloc de raisonnement qui doit être renvoyé à l’API.
