Prompt patterns pour coding agents

Pourquoi prompter un coding agent est different

Un chatbot repond une fois; un coding agent travaille dans une boucle, lit votre repository, edite des fichiers, execute vos tests et reagit aux resultats. Cela change ce qu'un bon prompt doit accomplir. Vous ne demandez pas un snippet, vous briefez un coequipier qui execute de vraies actions dans votre codebase, donc le prompt doit porter l'intention (ce que vous voulez et pourquoi), les contraintes (votre stack, vos conventions et ce qu'il ne doit pas toucher) et une definition de "fini" contre laquelle l'agent peut se verifier. Le plus grand levier est de sortir entierement les regles permanentes du prompt: ecrivez votre stack, vos conventions et votre quality gate dans un CLAUDE.md ou AGENTS.md, pour que chaque prompt parte de vos regles et que le prompt lui-meme ne porte que la tache. Les patterns ci-dessous presupposent cette fondation et se concentrent sur la mission par tache.

• L'agent agit: il edite des fichiers et execute des commandes, donc une intention vague devient de mauvais changements, pas juste une mauvaise phrase.
• Les regles permanentes vont dans CLAUDE.md ou AGENTS.md, pas dans chaque prompt; voir Comment utiliser Claude Code.
• Un bon prompt par tache porte l'intention, les contraintes et une definition verifiable de "fini".
• Le contexte est fini: un prompt cible laisse a l'agent de la place pour lire du code et reflechir. Voir le glossaire sur le context window.

Pattern 1: role et spec

Le point de depart le plus fiable est de nommer le role que l'agent doit adopter, puis de specifier la tache comme une spec etroite et testable plutot que comme un souhait. Une spec nomme l'objectif, les contraintes, les fichiers ou la zone dans le scope et les criteres d'acceptation qui decident quand c'est fini. "Ameliore le login" est un souhait; la version ci-dessous est une spec. La ligne de role focalise le modele (un senior engineer revise autrement qu'un tuteur), et les criteres d'acceptation donnent a l'agent quelque chose de concret a verifier, ce qui l'empeche de crier victoire trop tot. Gardez la spec sur l'essentiel: surspecifier chaque ligne retire a l'agent la capacite de prendre de bonnes decisions locales.

Role: act as a senior backend engineer on this codebase.

Goal: add rate limiting to the public /api/contact endpoint.

Constraints:
- Use the existing Convex rate-limit helper; do not add a new dependency.
- Limit to 5 requests per minute per IP. Return 429 with a clear JSON body.
- Touch only the contact route and its test; leave other endpoints alone.

Done when:
- A new test proves the 6th request in a minute gets a 429.
- `bun run lint && bun run typecheck && bun run test` all pass.

Plan first (do not edit yet), show me the plan, and wait for my go-ahead.

Pattern 2: montrez un exemple (few-shot)

Les modeles font correspondre des motifs, donc le moyen le plus rapide d'obtenir un output dans la forme voulue est d'en montrer un. Si vous avez besoin d'un nouveau fichier, composant, test ou migration qui doit ressembler a ce qui existe deja, montrez a l'agent un exemple existant et demandez-lui de suivre la meme structure: "Ecris le nouvel endpoint exactement comme src/api/users.ts, avec son fichier de test." Ce pattern few-shot fonctionne parce que votre codebase est le meilleur guide de style que vous ayez, et il bat de decrire vos conventions en prose. Pour un output sur lequel vous ne pouvez pas pointer, donnez un tout petit exemple inline du format attendu (une ligne de log d'exemple, une forme JSON, un style de message de commit), pour que l'agent ait une cible a faire correspondre.

• Pointez sur un fichier existant: "Suis la structure de src/api/users.ts et son test."
• Votre codebase est votre guide de style; un exemple bat un paragraphe de conventions.
• Pour les nouveaux formats, inlinez un tout petit echantillon de l'output exact (une ligne de log, une forme JSON).
• Un exemple affute surpasse en general plusieurs instructions vagues.

Pattern 3: decoupez le gros travail en etapes

Les grandes requetes vagues sont la ou les agents derivent: sommes de "construire le dashboard", ils prennent cent decisions que vous auriez prises autrement et enfouissent les erreurs dans un enorme diff. La solution est la decomposition. Soit vous decoupez vous-meme le travail en une sequence de petites taches revisables separement, soit vous demandez a l'agent de proposer d'abord un plan et vous l'approuvez avant qu'aucun code ne soit ecrit. Le plan-d'abord est l'habitude la plus puissante avec les coding agents: une mauvaise direction attrapee dans le plan ne coute rien, alors que la meme erreur apres un diff de mille lignes coute du vrai temps. Dans Claude Code, c'est le mode plan (Shift+Tab); dans tout agent, vous pouvez simplement instruire "plan first, do not edit, show me the steps". Ensuite implementez une etape, revisez, et passez a la suivante.

• Divisez une grande tache en petites etapes revisables separement plutot qu'un mega-prompt.
• Demandez un plan avant les edits; corriger un plan est gratuit, un enorme diff non.
• Implementez une etape, revisez le diff, puis continuez; gardez chaque changement lisiblement petit.
• Des etapes plus petites gardent aussi le context window propre, pour que l'agent reste affute sur la tache.

Pattern 4: construisez une verification loop

Le trait definissant d'un coding agent est qu'il peut executer des choses, donc les meilleurs prompts lui disent comment verifier son propre travail et continuer jusqu'a ce que la verification passe. Au lieu de "corrige le test qui echoue", dites "execute la suite de tests, corrige ce qui est rouge, et relance-la; ne t'arrete pas tant qu'elle n'est pas verte". Au lieu de faire confiance qu'un changement fonctionne, dites a l'agent d'executer le type-checker, le linter et les tests et de lire l'output reel plutot que de supposer. Cela transforme l'agent d'un generateur one-shot en une boucle fermee qui s'ancre dans de vrais resultats. La version la plus forte cuit la boucle dans votre projet, pour que ce ne soit meme pas un prompt: des hooks qui lancent votre gate automatiquement (voir le guide Claude Code Hooks) signifient que l'agent est tenu au standard, que vous pensiez a le demander ou non.

• Demandez a l'agent d'executer le gate (types, lint, tests) et de lire l'output reel, pas de supposer.
• Faites-le iterer: "corrige et relance jusqu'a ce que la suite soit verte", pas une seule execution.
• Pour l'UI ou le comportement, faites-lui lancer le dev server ou un check Playwright, pour qu'il voie le vrai resultat.
• Automatisez la boucle avec des hooks, pour que la verification arrive a chaque fois, pas seulement quand vous y pensez.

Pattern 5: donnez a l'agent le bon contexte, pas tout le contexte

Les agents echouent plus souvent par manque de contexte que par un modele faible: sommes d'utiliser une API sans sa doc, ils devinent. Donc apportez a l'agent ce dont il a besoin, sciemment. Pointez sur les fichiers pertinents, collez l'erreur en entier, liez la doc, nommez la fonction exacte. Mais resistez au piege inverse de tout deverser: un context window bourre de vingt fichiers et d'un long historique degrade la qualite, parce que le modele perd le detail important dans le bruit (l'effet "lost in the middle"). L'art est la curation: assez de contexte pour reussir, assez peu pour rester affute. C'est le coeur du context engineering, et notre guide Context Engineering plonge en profondeur dans la gestion du window sur une longue tache.

• Nommez les fichiers exacts, collez l'erreur complete et liez la doc dont l'agent a besoin.
• Ne deversez pas tout le repo; le contexte pertinent bat le contexte maximal a chaque fois.
• Attention au "lost in the middle": un detail cle enfoui dans un enorme prompt est ignore.
• Voir le guide Context Engineering et le glossaire sur le context window et le system prompt.

Les anti-patterns a eviter

La plupart de la douleur de prompting vient d'une courte liste d'erreurs recurrentes. Les nommer les rend faciles a reperer dans ses propres habitudes. Le remede pour chacune est un pattern ci-dessus: soyez specifique, montrez un exemple, decoupez, verifiez et curez le contexte.

• Souhaits vagues: "fais mieux" ne donne rien a verifier a l'agent. Nommez une spec et des criteres d'acceptation.
• Le mega-prompt: une enorme requete qui enfouit cent decisions dans un diff non revisable. Decoupez et planifiez d'abord.
• Confiance sans verification: accepter un output que vous n'avez pas fait tester a l'agent. Construisez une verification loop.
• Deversement de contexte: tout coller au point de noyer le signal. Curez a ce dont la tache a besoin.
• Retaper les regles a chaque tour: stack et conventions vont dans CLAUDE.md ou AGENTS.md, pas dans chaque prompt.
• La politesse comme instruction: "s'il te plait essaie peut-etre" se lit comme optionnel. Soyez direct; les contraintes sont des regles, pas des suggestions.

Questions fréquemment posées

Continuez à apprendre