La plupart des gens prompttent Claude Code comme ils prompttent ChatGPT. C’est ça, le bug.

ChatGPT est un moteur de questions-réponses. Claude Code est un agent. La forme d’une bonne question n’est pas la forme d’un bon objectif.

Après un an d’utilisation de Claude Code sur des bases de code de production, je l’ai distillé en quatre parties qui doivent toujours apparaître dans le prompt :

• Objectif — à quoi ressemble la réussite.
• Contraintes — ce qui ne doit pas changer.
• Definition of Done — comment l’agent sait qu’il a terminé.
• Contexte — pointeurs vers les fichiers / tickets / erreurs pertinents.

Sautez l’une d’elles et vous obtenez de la dérive. Incluez les quatre et l’agent tournera tranquillement pendant 5 minutes pour revenir avec un diff propre.

Le mauvais prompt

> Refactor le service utilisateur pour la perf.

Pourquoi ça échoue :

• « Perf » n’est pas défini. Latence ? Mémoire ? Débit ?
• Aucune contrainte — il pourrait réécrire votre schéma DB.
• Aucune definition of done — il s’arrête quand il s’ennuie.
• Aucun contexte — il doit deviner quel fichier est « le service utilisateur ».

Vous récupérez un truc qui ressemble à du travail mais qui n’en est pas.

Le bon prompt

> Objectif : Réduire la latence p95 de GET /api/users/:id de 240 ms à moins de 80 ms.
>
> Contraintes :
> - NE PAS changer la forme de l'API publique.
> - NE PAS ajouter de nouvelles dépendances.
> - Garder le code dans app/api/users — pas de nouvelle couche.
>
> Definition of Done :
> - Les tests existants passent.
> - Ajouter un load test (50 appels concurrents × 100 itérations).
> - p95 < 80 ms en local sur Node 20.
> - Ajouter une description de PR d'un paragraphe.
>
> Contexte :
> - app/api/users/route.ts est le point d'entrée.
> - lib/db/users.ts contient la requête N+1 lente.
> - On utilise Postgres 15 et drizzle ORM.

Même tâche. Résultat différent. L’agent va :

1. Lire les deux fichiers.
2. Identifier le N+1.
3. Écrire le fix avec une seule requête batchée.
4. Ajouter le load test.
5. Lancer le test, confirmer le chiffre.
6. Rendre un diff avec la description de PR.

Ça, c’est de la délégation, pas de l’autocomplétion.

Pourquoi chaque partie compte

Objectif

Écrivez-le comme un résultat, pas une action. « Réduire la latence p95 à 80 ms » est un résultat. « Refactor les appels DB » est une action — et un agent médiocre fera l’action sans atteindre le résultat.

Contraintes

Les contraintes, c’est ce qui vous surprendrait. Si un junior réécrivant ce fichier vous surprenait en changeant la forme de l’API, écrivez-le. S’il vous surprenait en ajoutant Redis, écrivez-le.

La plupart des histoires « Claude Code a fait un truc bizarre » sont des contraintes manquantes, pas un manque d’intelligence.

Definition of Done

La partie la plus sous-utilisée de tout prompt. Sans elle, l’agent s’arrête quand il pense que la tâche est finie — généralement après avoir écrit le code, avant d’avoir lancé les tests.

Une bonne DoD est testable :

• « Les tests existants passent. »
• « Le nouvel endpoint retourne 201 et un header Location valide. »
• « lighthouse-ci ne montre aucune régression sur la homepage. »

Si vous ne pouvez pas écrire une DoD, la tâche n’est pas prête à être déléguée.

Contexte

Pas besoin de coller des fichiers. Des pointeurs suffisent :

• app/api/users/route.ts — point d’entrée.
• tests/api/users.test.ts — tests existants.
• « On a vu la régression dans la PR #842. »

Claude Code sait lire et chercher. Il a juste besoin que vous lui pointiez le bon quartier.

Le template 80/20 que je garde dans .claude/commands/

# /goal — colle ce template, remplis les blancs

Objectif : <résultat avec un chiffre si possible>

Contraintes :
- <ce qui ne doit pas changer>
- <règle de dépendance>
- <règle de style ou d'architecture>

Definition of Done :
- <commande de test qui passe>
- <vérification perf ou correction>
- <description de PR en 1 paragraphe>

Contexte :
- <fichier ou dossier>
- <ticket / erreur / log lié>

L’aliaser en slash command fait qu’un nouveau prompt de feature prend 90 secondes à écrire. On couvrira les slash commands en détail dans l’article 4.

Les anti-patterns à abandonner aujourd’hui

• « Rends-le plus propre. » Plus propre selon quelle métrique ? Choisissez : lignes de code, complexité cyclomatique, ou une règle de lint précise.
• « Corrige le bug. » Quel bug ? Quel est le comportement attendu ? L’actuel ?
• « Refactor pour la lisibilité. » La lisibilité, c’est du goût. Choisissez un pattern concret : « extraire en fonctions pures », « remplacer les ifs imbriqués par des early returns ».

Des prompts vagues produisent du code vague. L’agent est un miroir.

Un dernier truc : « l’exemple négatif »

Parfois, la façon la plus propre de contraindre un agent, c’est de lui montrer ce qu’il ne doit pas faire.

> NE PAS ajouter de nouvelle couche d'abstraction.
> La tentative précédente avait ajouté une classe UserRepository — on l'a retirée.
> Le fix devrait faire ~20 lignes dans lib/db/users.ts, pas 200.

Brutalement efficace. Vous anticipez le mode d’échec le plus courant d’un agent trop zélé : bâtir un royaume quand une seule fonction suffisait.

---

Article suivant : Slash commands — comment transformer le template de prompt ci-dessus en une commande /feature à un seul keystroke, et comment chaîner /init, /agents, /compact pour bâtir un squelette de projet complet en une seule session.