Comment poser des questions et donner des instructions : Parler droit au cœur de Claude
📚 Navigation dans la série : L'article précédent [14 Interface d'interaction et raccourcis] vous a appris où placer vos doigts — le curseur, la touche Entrée, Échap et les commandes slash n'ont plus de secret pour vous. Cet article change de niveau : les mains savent quoi faire, la bouche doit maintenant savoir quoi dire. Pour une même tâche, la qualité de votre instruction fait une différence énorme sur le résultat produit par Claude.
Pour dire une vérité qui dérange un peu : au début, quand les gens commencent à utiliser Claude Code, beaucoup s'en servent comme d'un moteur de recherche.
Imaginez la scène : une erreur de fonction survient dans le projet, vous lancez un désinvolte « Corrige ce bug », sans même mentionner de quel fichier ou de quelle erreur il s'agit. Vous tapez Entrée et attendez que la magie opère. Résultat, il "devine" un bug présumé, modifie trois fichiers, et aucun n'est celui que vous vouliez réparer. Vous fixez les diffs à l'écran, perplexe, en pensant : « Cette IA n'est vraiment pas au point. »
En y réfléchissant bien, ce n'est pas lui le problème. Le problème ne vient pas de Claude, mais de la consigne qui était pitoyable : quantité d'information proche de zéro, il a dû faire appel à son imagination. S'il devine mal, à qui la faute ?
Disons-le franchement : Le potentiel maximum de Claude Code est largement limité par votre façon de formuler vos requêtes. Avec le même modèle, sur le même projet, une personne qui sait formuler sa demande l'obtiendra en trois phrases, tandis qu'une autre fera cinq allers-retours frustrants. Aujourd'hui, nous allons décortiquer les règles universelles pour « exprimer clairement un besoin » — il ne s'agit pas d'apprendre des modèles par cœur, mais de comprendre « ce que Claude doit absolument savoir pour ne pas s'égarer ».
Après avoir lu cet article, vous obtiendrez :
- Un tableau comparatif « Mauvaise requête vs Bonne requête », pour réduire drastiquement les retouches
- Quatre principes fondamentaux : être spécifique, donner le contexte, fournir des critères d'acceptation, et planifier les tâches complexes
- La bonne manière d'utiliser
@pour cibler précisément les fichiers - Une expérience « un besoin, deux formulations » que vous pourrez tester vous-même pour constater la différence
01 En quoi une mauvaise requête est-elle mauvaise ?
Reprenons l'exemple de tout à l'heure. « Corrige ce bug », du point de vue de Claude, c'est dramatiquement incomplet :
- Quel bug ? Il doit deviner de quoi vous parlez.
- Quel fichier ? Il doit chercher dans tout le projet.
- Quel est le comportement correct attendu ? Il n'en a aucune idée, il ne peut qu'imaginer ce qui serait « normal en général ».
Analogie : Former un nouvel employé. Si vous dites à un stagiaire nouvellement arrivé : « Occupe-toi de ce truc », il y a peu de chances qu'il s'en sorte bien. Mais si vous dites : « Change la couleur du bouton de connexion en haut à droite de la page d'accueil, du gris au bleu de la marque #1A73E8 », il le fera les yeux fermés. Plus l'instruction est spécifique, moins le stagiaire fera d'erreurs ; plus vous serez vague, plus il devra deviner, et plus il risquera de se tromper. Claude fonctionne exactement de la même manière.
Regardons ces comparaisons soulignées dans la documentation officielle :
| Scénario | ❌ Mauvaise requête | ✅ Bonne requête |
|---|---|---|
| Corriger un bug | « Corrige l'erreur de connexion » | « Les utilisateurs signalent un échec de connexion après l'expiration de la session. Vérifie le flux d'authentification dans src/auth/, concentre-toi sur le rafraîchissement du token. Écris d'abord un test échouant qui reproduit le problème, puis corrige-le. » |
| Écrire un test | « Ajoute des tests à foo.py » | « Écris des tests pour foo.py, couvre les cas limites où l'utilisateur est déconnecté, n'utilise pas de mock. » |
| Question sur le code | « Pourquoi l'API de ExecutionFactory est-elle conçue de manière aussi horrible ? » | « Parcours l'historique git de ExecutionFactory et résume comment son API a évolué pour devenir ce qu'elle est aujourd'hui. » |
| Ajouter une fonctionnalité | « Ajoute un composant calendrier » | « Regarde d'abord comment sont implémentés les composants existants sur la page d'accueil, HotDogWidget.php est un bon exemple. Implémente un composant calendrier selon ce modèle, permettant à l'utilisateur de choisir le mois et de changer d'année. N'ajoute pas de nouvelle bibliothèque, utilise celles déjà présentes. » |
Vous avez compris le principe ? Les bonnes requêtes font toutes la même chose : elles donnent à l'avance à Claude les informations qu'il aurait dû deviner.
💡 En résumé : Les mauvaises requêtes pêchent par omission (Claude doit compenser), les bonnes requêtes lui disent clairement ce qu'il a besoin de savoir.
Ce comparatif Avant/Après met en évidence deux façons de formuler une même demande : à gauche, une question floue, Claude ne peut que deviner et poser une série de questions ; à droite, le périmètre, le contexte (@fichier) et les critères d'acceptation sont tous réunis, il vise juste du premier coup et valide directement les tests. La différence ne vient pas de Claude, mais de vous.
02 Principe 1 : Spécifique > Vague
C'est de loin le principe le plus important des quatre.
La documentation officielle contient une phrase qu'il faut absolument retenir :
Plus votre instruction sera précise, moins vous aurez de corrections à apporter.
Pour dire les choses simplement : Une phrase de plus au départ, c'est trois allers-retours de moins à la fin. Vous pensez « gagner du temps » en tapant moins de mots, mais les mots économisés vous coûtent double en temps de reprise et d'ajustements.
Jusqu'à quel point faut-il être spécifique ? Intégrez trois dimensions :
Premièrement, délimitez le périmètre — quel fichier, quelle fonction, quel scénario. Ne le laissez pas chercher une aiguille dans une botte de foin.
Deuxièmement, précisez les contraintes — « n'importe pas de nouvelle bibliothèque », « garde la rétrocompatibilité », « ne touche pas aux fichiers de test ». Si vous ne le précisez pas, il agira selon ses propres préférences, qui ne correspondront pas forcément aux vôtres.
Troisièmement, donnez une référence — « Fais-le selon le modèle de HotDogWidget.php ». C'est l'astuce la plus redoutable : Plutôt que d'essayer de décrire le style que vous voulez, fournissez-lui directement un exemple existant qui vous plaît, il s'en inspirera, et ce sera presque parfait du premier coup.
Attention cependant, il y a une exception contre-intuitive à bien comprendre : Une question vague n'est pas toujours une erreur. Lorsque vous êtes en « phase d'exploration » et que vous ne savez pas vous-même quelle direction prendre, un simple « Que penses-tu que l'on pourrait améliorer dans ce fichier ? » peut faire émerger des idées auxquelles vous n'auriez jamais pensé. La documentation officielle dit : « Les instructions vagues peuvent être utiles lorsque vous explorez et pouvez corriger la trajectoire ». La règle est la suivante : si vous voulez un résultat précis, soyez hyper-spécifique ; si vous cherchez l'inspiration, restez volontairement ouvert.
Il est facile de tomber dans ce piège en créant un petit outil — on veut d'abord voir comment Claude comprend le code brouillon, on pose des questions très larges, et ses suggestions sont effectivement inspirantes ; mais une fois que l'on a un objectif précis en tête, continuer à poser des questions vagues est une pure perte de temps, car il devra deviner à chaque fois ce que vous voulez.
💡 En résumé : Pour un résultat certain, soyez ultra-spécifique (Périmètre + Contraintes + Référence), ne restez vague que si vous cherchez activement de l'inspiration.
03 Principe 2 : Donnez le contexte, ne le laissez pas deviner
Au-delà d'être spécifique, la deuxième astuce consiste à lui servir les éléments sur un plateau, plutôt que de lui décrire où ils se trouvent.
Deux actions très fréquentes à retenir pour régler la majorité des cas :
Premièrement, utilisez @ pour référencer des fichiers. En tapant @ dans la zone de saisie, l'auto-complétion des chemins de fichiers apparaît. Une fois sélectionné, le contenu complet de ce fichier sera directement inséré dans la conversation — Claude n'aura pas à le chercher ni à le lire, gagnant ainsi une étape et évitant les erreurs de sélection.
Prends exemple sur la définition des types dans @src/types/user.ts, et ajoute des annotations de type à UserService.C'est infiniment plus fiable que de dire « cherche le fichier de type user dans le projet ». La documentation officielle indique explicitement que la référence avec @ « lit le contenu complet du fichier avant de répondre ».
Analogie : La clé USB. @ c'est comme brancher directement une « clé USB » sur le poste de travail de Claude — c'est plug-and-play, les données dont il a besoin sont disponibles instantanément ; si vous vous contentez de lui dire « les documents sont au troisième étage, dans la deuxième armoire », il devra y aller lui-même, et s'il se trompe de chemin, cela prendra plus de temps.
Deuxièmement, collez directement les erreurs complètes. C'est un réflexe à développer — quand vous rencontrez un traceback (une trace d'exécution de bug), ne résumez pas en disant « il m'indique un pointeur nul », collez la trace complète telle quelle :
J'ai eu cette erreur à l'exécution, aide-moi à en trouver la cause :
TypeError: Cannot read properties of null (reading 'userId')
at getUserProfile (src/services/user.ts:42:18)
at async ProfileController.getProfile (src/controllers/profile.ts:15:20)Pourquoi coller l'intégralité ? Parce que la trace contient les noms des fichiers, les numéros de ligne et la chaîne d'appels. Claude pourra pointer précisément user.ts:42. Si vous ne faites que résumer, c'est comme si vous supprimiez ces coordonnées clés, et il devra tout deviner.
| Ce que vous voulez partager | ❌ Décrire avec des mots | ✅ Donner directement |
|---|---|---|
| Le contenu d'un fichier | « Il y a un fichier qui gère l'authentification dans le projet » | @src/auth/session.ts |
| Une erreur | « Il m'indique une erreur "undefined" » | Coller le traceback complet tel quel |
| Un problème d'interface (UI) | « Le bouton n'est pas au bon endroit » | Coller directement une capture d'écran (Claude lit les images) |
| Une spécification d'API | « Suis notre standard d'API » | @docs/api-spec.md |
En un mot : Tout ce qui peut être « collé », ne le « racontez » jamais. Claude interprétera toujours mieux le matériel original que votre transcription de ce matériel.
💡 En résumé : Utilisez
@pour les fichiers, collez directement les erreurs et les captures d'écran sous ses yeux, ne le laissez pas deviner à partir de votre description.
04 Principe 3 : Donnez un critère de succès « vérifiable »
C'est souvent ignoré, mais c'est d'une puissance redoutable : Vous devez dire à Claude « à quoi on voit que le travail est réussi », et ce critère, il doit pouvoir le vérifier lui-même.
Pourquoi est-ce crucial ? La documentation officielle explique la logique sous-jacente :
Lorsque le travail semble terminé, Claude s'arrête. Sans contrôle qu'il peut exécuter, le "semble terminé" est son seul signal, et vous devenez la boucle de validation : chaque erreur attend que vous la remarquiez.
Qu'est-ce que cela signifie ? Si vous ne lui donnez pas de critère, Claude s'arrêtera quand il estimera que « c'est à peu près bon », et c'est vous qui ferez la vraie recette de fin de projet, et qui traquerez chaque faille. Mais dès que vous lui donnez un test qui peut indiquer « succès / échec », la boucle se ferme d'elle-même : il fait le travail → lance le test → regarde le résultat → si ça échoue, il corrige de lui-même, sans que vous n'ayez besoin de surveiller.
Regardez la différence :
| Tâche | ❌ Pas de critère | ✅ Critère vérifiable |
|---|---|---|
| Écrire une fonction | « Implémente une fonction pour valider les emails » | « Écris une fonction validateEmail. Exemples de cas : user@example.com est vrai, invalid est faux, user@.com est faux. Une fois écrit, lance les tests. » |
| Modifier l'UI | « Rends ce tableau de bord plus joli » | « [Coller la maquette] Implémente ceci, puis fais une capture d'écran du résultat, compare-la avec la maquette originale, liste les différences et corrige-les. » |
| Réparer un build | « Le build a planté » | « Le build renvoie cette erreur : [Coller l'erreur]. Corrige-la et vérifie que le build passe. Règle la cause principale, ne te contente pas de masquer l'erreur. » |
Faites attention à la dernière partie de la dernière ligne : « Règle la cause principale, ne te contente pas de masquer l'erreur » — une leçon apprise à mes dépens. Sans cette phrase, il peut lui arriver, par facilité, d'encapsuler le code dans un try/except ou d'ajouter un @ts-ignore pour faire disparaître l'alerte. L'erreur n'apparaît plus, mais le problème reste entier.
Usage avancé : /goal transforme le critère en « pas terminé tant que l'objectif n'est pas atteint ». (Nécessite Claude Code v2.1.139 ou supérieur) Poser un critère dans une conversation standard, c'est pour « l'itération en cours » ; avec /goal, vous définissez le critère comme objectif principal de toute la session — à chaque fois, un plus petit modèle (par défaut Haiku) vérifie si vos conditions sont remplies. Si ce n'est pas le cas, il lance automatiquement la boucle suivante, sans vous redonner la main, jusqu'à ce que l'objectif soit atteint.
/goal tous les tests dans test/auth passent, et l'étape lint ne renvoie aucune erreurFaites cependant attention à un détail important avec /goal : ce petit modèle d'évaluation ne regarde que ce que Claude « affiche » dans la conversation, il n'ira pas exécuter de commande ou lire des fichiers lui-même. Vos conditions doivent donc pouvoir être prouvées par la sortie de Claude. Le succès de « tests test/auth passent » est possible parce que Claude va réellement lancer les tests et en imprimer le résultat dans la conversation. Si vous demandez « la qualité du code est très bonne », une notion qui ne se prouve pas via la console, l'évaluation sera impossible.
💡 En résumé : Donnez-lui un test avec un résultat clair (succès/échec, comparaison d'images, code de sortie du build), pour que la boucle se referme toute seule ; si vous voulez qu'il ne s'arrête pas avant le succès, utilisez
/goal.
05 Principe 4 : Pour les tâches complexes, demandez-lui un plan avant d'agir
Le dernier principe, réservé aux « gros chantiers » : Lorsqu'une tâche implique des changements majeurs, croise plusieurs fichiers, ou que vous n'êtes pas vous-même sûr de la marche à suivre, ne le laissez pas se lancer tête baissée dans le code — demandez-lui d'abord un plan que vous validerez.
On en parlait déjà dans l'article 06 (Forfaits et tarification), expliquons-en la raison ici. Le constat officiel est très clair :
Laisser Claude se précipiter sur le code risque de le conduire à résoudre le mauvais problème.
En d'autres termes, explorez d'abord, planifiez ensuite, et codez à la fin — séparez le fait de « réfléchir » et « d'agir », cela lui évite de partir dans la mauvaise direction, pour que vous découvriez le désastre une fois les fichiers modifiés.
Analogie : Refaire la décoration, d'abord les plans, ensuite abattre les murs. Aucun artisan sérieux ne commencerait à casser des murs porteurs à grands coups de masse sans vous prévenir. Il s'accordera avec vous : « Ce mur tombe, les fils passent par là, les canalisations sont déviées ici », et ne commencera que si vous êtes d'accord. Le plan, c'est le croquis que Claude vous tend avant d'abattre un mur. Si vous y voyez un défaut, corriger un plan coûte infiniment moins cher que de réparer un mur déjà démoli.
Comment lui demander de faire des plans ? Deux méthodes :
Méthode 1 : Dites clairement « ne modifie rien pour l'instant ». Ajoutez simplement cette contrainte dans une conversation classique :
Je veux ajouter un bouton pour le mode sombre sur la page des paramètres. Dis-moi quels fichiers tu penses toucher, et quelle est ton approche,
ne modifie aucun code pour l'instant.Méthode 2 : Passez en Mode Planification (Plan Mode). C'est un mode exclusif à Claude Code pour la création de plans en « lecture seule » — il va lire des fichiers, proposer des solutions, mais n'écrira pas un seul caractère avant votre approbation. Pour y accéder : dans la conversation, appuyez sur Maj + Tab (une ou deux fois pour arriver sur Plan Mode), le mode passera de default → acceptEdits → plan. Si vous voulez qu'une seule instruction soit exécutée en Mode Plan sans changer toute la session, préfixez ce message avec /plan.
Cependant, la documentation officielle nous donne un conseil très pragmatique, ne tombez pas dans l'excès inverse de tout planifier :
Pour les tâches dont le périmètre est bien délimité et les corrections mineures (comme corriger une faute de frappe, ajouter un log ou renommer une variable), demandez à Claude d'agir directement. La planification est utile lorsque la méthode est incertaine, que les changements touchent plusieurs fichiers ou que vous ne maîtrisez pas le code modifié. Si vous êtes capable de décrire le diff (la modification) en une seule phrase, passez l'étape du plan.
La méthode la plus terre-à-terre est contenue dans cette dernière phrase : « Êtes-vous capable d'expliquer l'aspect des modifications en une seule phrase ? » Si oui, foncez ; si vous bloquez, c'est que la tâche est assez complexe pour nécessiter un plan. Utiliser le Plan Mode pour corriger une faute de frappe, c'est faire des manières pour rien.
💡 En résumé : Vous n'êtes pas sûr / Impact sur plusieurs fichiers / Code inconnu → Planifiez (Dites « ne modifie rien » ou
Maj+Tabpour le Plan Mode) ; Un petit changement qui se décrit en une phrase, laissez-le faire directement.
06 Pratique : Un même besoin, deux formulations, la différence saute aux yeux
Connaître la théorie ne suffit pas, faisons une petite expérience pour voir la différence de nos propres yeux. Préparez un petit fichier « bac à sable » de trois lignes, pas besoin de projet complexe. Ouvrez votre terminal.
Première étape : Créez un fichier brouillon avec un « piège » (Mac / Linux)
mkdir prompt-demo
cd prompt-demo
echo 'def average(nums):
return sum(nums) / len(nums)' > stats.pyUtilisateurs Windows : Tapez mkdir prompt-demo, cd prompt-demo, ouvrez le Bloc-notes pour créer stats.py et collez-y les deux lignes de code ci-dessus.
Cette fonction contient un piège : Si l'on passe une liste vide [], len(nums) vaut 0, ce qui provoquera un plantage « division par zéro ». Nous utiliserons ce cas pour tester.
Deuxième étape : Lancez Claude dans ce répertoire
claudeRésultat attendu : L'écran de bienvenue apparaît, avec la zone de saisie en bas.
Troisième étape : Testez d'abord la « mauvaise requête », pour voir comment il improvise
@stats.py aide-moi à corriger cette fonctionRésultat attendu : Il y a de grandes chances que Claude « devine » ce que vous voulez : peut-être qu'il ajoutera des annotations de type, peut-être des commentaires, mais il ignore que ce qui vous intéresse vraiment, c'est le plantage de la liste vide. La direction qu'il prendra relèvera de la pure chance. C'est le prix des questions vagues : il prend les décisions à votre place.
Quatrième étape : Passez à la « bonne requête » — Spécifique + Contexte + Critères d'acceptation
La fonction average dans @stats.py contient un bug : passer une liste vide provoque un plantage par division par zéro.
Le comportement attendu pour une liste vide est de retourner 0.
Aide-moi à corriger cela, et ajoute des tests : average([]) doit retourner 0, average([2, 4]) doit retourner 3.
Une fois écrit, exécute les tests et vérifie qu'ils passent.Résultat attendu : Cette fois-ci, les actions de Claude sont claires et ordonnées : il identifie le problème de la liste vide → ajoute la condition pour retourner 0 → écrit les deux tests que vous avez demandés → exécute réellement les tests → et vous montre qu'ils réussissent. Il ne devine plus ce que vous voulez, car vous avez tout précisé : quoi modifier, comment modifier, et comment vérifier.
Cinquième étape : Quittez et vérifiez les modifications
cat stats.py(Pour Windows PowerShell, utilisez type stats.py)
Résultat attendu : stats.py contient bien une gestion de la liste vide (comme if not nums: return 0). Ça correspond exactement à ce que vous aviez demandé à l'étape quatre = Vous maîtrisez maintenant l'art d'« exprimer clairement vos besoins ».
En mettant côte à côte ces deux requêtes, la différence est évidente :
| Troisième étape ❌ Mauvaise requête | Quatrième étape ✅ Bonne requête | |
|---|---|---|
| Où modifier | Rien dit, il devine partout | Précise la fonction average |
| Comment modifier | Rien dit, libre à lui | Retourner 0 pour une liste vide |
| Critères de succès | Aucun, il s'arrête « quand il le sent » | Deux cas de tests + Exécution pour valider |
| Votre expérience | Fixer les diffs en pensant « Ce n'est pas ce que j'ai demandé » | Il suit le scénario à la lettre, du premier coup |
💡 En résumé : Sur le même fichier et le même bug, une mauvaise requête laisse Claude deviner, une bonne requête définit clairement « quoi, comment, avec quels critères de validation » — Faites l'expérience vous-même, la différence vaut mieux que de grandes théories.
07 Résumé
Cet article ne traite que d'un seul sujet : Comment formuler une demande en une phrase pour que Claude puisse s'en saisir parfaitement.
Pour résumer ces quatre principes, si vous ne deviez retenir qu'un tableau :
| Principe | En une phrase | Comment l'appliquer |
|---|---|---|
| Spécifique > Vague | Précisez le périmètre + les contraintes + une référence | « Modifie average, pas de nouvelle bibliothèque, selon le modèle de xxx » |
| Donnez le contexte | Ce qui peut être collé ne doit pas être décrit | @fichier, coller l'erreur entière, capture d'écran |
| Critères d'acceptation | Laissez-le vérifier lui-même « si ça marche » | Fournissez des tests, demandez-lui d'exécuter ; ou utilisez /goal |
| Planifier d'abord | Les grosses tâches : les plans avant de casser des murs | Dire « ne modifie rien » ou Maj+Tab vers Plan Mode |
Maintenant, vous devriez pouvoir : Traduire un vague « Aide-moi à corriger ça » en une demande que Claude peut réellement traiter : définir le périmètre de manière ciblée, fournir le contexte, donner des critères d'acceptation vérifiables, et demander un plan en cas de besoin complexe. Ces règles de communication sont la « force intérieure » qui soutiendra toutes vos interactions avec Claude Code — même avec des fonctionnalités sophistiquées, si les requêtes sont mauvaises, les résultats seront décevants.
Une réflexion pour terminer : Sachant l'importance de « formuler clairement », allez-vous devoir répéter à chaque fois certaines règles de votre projet (comme « n'ajoute jamais de nouvelle bibliothèque » ou « les tests vont tous dans le dossier
tests/») ? Y a-t-il un moyen de faire en sorte que Claude s'en « souvienne », pour vous éviter de répéter indéfiniment ?
L'article suivant : 16 « Les workflows fréquents » — Cet article vous a montré les règles universelles de communication. Le prochain appliquera ces règles aux quatre types de tâches les plus courantes : explorer une nouvelle base de code, corriger des bugs, refactoriser, et écrire des tests, avec des modèles standard pour chacune d'elles. Les principes de base sont posés, voyons maintenant l'application pratique.