Quelle longueur pour un prompt destiné à un agent de code ?

Le temps d’énoncer l’objectif, les fichiers de départ, les contraintes et les critères de fin, et pas plus. Pour une petite correction, deux ou trois lignes suffisent. Pour une fonctionnalité, c’est en général un court paragraphe plus une liste. Le contexte valable pour toutes les tâches va dans CLAUDE.md ou AGENTS.md, pas dans chaque prompt.

Faut-il demander un plan à l’agent avant qu’il écrive du code ?

Oui, dès que la tâche touche plus de deux ou trois fichiers ou que vous ne savez pas la décrire précisément. Dans Claude Code, utilisez le plan mode (Shift+Tab ou /plan) ; dans Codex, /plan. Lisez le plan, corrigez-le, puis laissez l’agent l’implémenter. Pour une correction d’une ligne, un plan est superflu.

Les astuces du type « tu es un ingénieur senior » aident-elles les agents de code ?

Bien moins que des informations concrètes. Une ligne de rôle ne coûte pas grand-chose, mais l’agent gagne beaucoup plus avec le fichier par lequel commencer, la commande qui lance les tests et le comportement attendu. Consacrez vos mots aux faits de la tâche.

Où garder les prompts que j’utilise encore et encore ?

Les règles du projet vont dans CLAUDE.md (Claude Code), AGENTS.md (Codex et d’autres agents) ou GEMINI.md (Gemini CLI). Les workflows répétés deviennent des skills : .claude/skills/ /SKILL.md dans Claude Code, .agents/skills dans Codex. Gemini CLI utilise des commandes personnalisées TOML dans .gemini/commands.

Comment empêcher un agent de code de dire qu’une tâche est finie alors qu’elle ne l’est pas ?

Donnez-lui une vérification à exécuter, comme une commande de test, un build ou une requête curl, et demandez-lui de coller la sortie. Demandez un nouveau test qui échoue avant le changement et passe après. Relisez ensuite le diff vous-même ou faites-le relire par un second agent.

Écrire des prompts pour agents de code IA

Un bon prompt pour un agent de code IA dit quatre choses : ce que vous voulez, par où commencer, ce qui ne doit pas changer et comment savoir que ça marche. La plupart des mauvais résultats viennent de l’oubli d’un de ces points, pas d’une mauvaise formulation. L’agent peut lire votre code, lancer des commandes et modifier des fichiers ; le rôle du prompt est d’orienter ce travail dans la bonne direction et de lui donner une ligne d’arrivée.

Ce guide compare de mauvais et de bons prompts, puis couvre le contexte, les plans, le découpage du travail, la vérification et l’endroit où ranger les prompts que vous réutilisez. Les exemples utilisent Claude Code et Codex CLI, mais ces habitudes valent pour Gemini CLI et tout autre agent de code.

Pourquoi un prompt pour un agent diffère d’un prompt pour un chatbot

Un chatbot n’a que votre message. Un agent de code a tout votre dépôt, un shell et une boucle : il lit des fichiers, fait une modification, lance quelque chose, regarde le résultat et recommence. Cela change ce qu’un prompt doit faire :

Inutile de coller du code. Indiquez les fichiers et laissez l’agent les lire.
Il faut en revanche fixer des limites. Un agent qui peut tout modifier risque de modifier ce que vous n’aviez pas prévu.
Il faut une règle d’arrêt. Sans elle, l’agent décide seul quand le travail est assez bon, et son niveau d’exigence n’est pas forcément le vôtre.

Chaque fichier supplémentaire que l’agent lit remplit aussi sa fenêtre de contexte. Un prompt ciblé garde l’agent concentré et la session moins chère.

Mauvais prompt contre bon prompt

Voici une première tentative typique :

fix the login bug

L’agent doit deviner quel bug, où il se trouve et ce que « corrigé » veut dire. Il peut modifier le mauvais fichier, réécrire une fonction qui allait très bien, ou « corriger » le symptôme en interceptant l’erreur.

Voici la même demande, écrite pour un agent :

Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.

Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.

Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.

C’est plus long, mais chaque ligne évite une supposition à l’agent. Voici le rôle de chaque partie :

Partie	Exemple	Pourquoi ça aide
Symptôme	« renvoie 401 même avec le bon mot de passe »	L’agent sait quoi reproduire
Cause, si vous la connaissez	« enregistre les e-mails tels que saisis »	Évite une longue recherche
Fichiers de départ	`src/auth/login.ts`	Moins de lecture, moins de fausses pistes
Contraintes	« ne modifie pas le schéma de la base »	Garde le changement petit et sûr
Critères de fin	un test nommé plus `pnpm test`	Une ligne d’arrivée que l’agent peut vérifier

Vous ne connaissez pas toujours la cause. Ce n’est pas grave : dites-le, et demandez à l’agent de la trouver avant de corriger. « Trouve pourquoi X se produit et explique-le avant de modifier quoi que ce soit » est déjà un excellent prompt à lui seul.

Donnez du contexte, pas des dissertations

Le contexte le plus utile est concret et vérifiable. Par ordre approximatif de valeur :

Chemins de fichiers et symboles. src/billing/invoice.ts, calculateTax(). Dans Claude Code et Codex, tapez @ pour choisir un fichier et le joindre.
Sortie d’erreur. Collez la stack trace exacte ou la sortie du test qui échoue, pas un résumé.
Contraintes. Les bibliothèques que vous utilisez ou non, les dossiers à ne pas toucher, les API qui doivent rester rétrocompatibles.
Exemples dans le code. « Suis le modèle de src/routes/users.ts » vaut mieux qu’un paragraphe qui décrit ce modèle.
Le pourquoi. Une phrase sur l’objectif côté utilisateur aide l’agent à faire des choix raisonnables que vous n’avez pas détaillés.

Ce qu’il faut laisser de côté : le long historique du projet, vos opinions sur du code sans rapport et les instructions valables pour toutes les tâches. Ces dernières ont leur place dans un fichier de projet, présenté plus bas.

Les captures d’écran aident pour le travail d’interface. Claude Code et Codex acceptent tous deux des images ; Codex accepte aussi codex --image path/to/file.png en ligne de commande.

Demandez d’abord un plan

Pour tout ce qui dépasse une petite correction, séparez la réflexion de l’action. Demandez à l’agent de lire le code et de proposer un plan, relisez-le, puis laissez-le implémenter.

Claude Code : appuyez sur Shift+Tab jusqu’à ce que la barre d’état affiche le plan mode, tapez /plan avant un prompt isolé, ou démarrez avec claude --permission-mode plan. En plan mode, Claude lit et propose mais ne modifie rien. Le plan mode de Claude Code entre dans les détails.
Codex CLI : /plan demande à Codex de planifier avant d’implémenter. Vous pouvez aussi ouvrir une session en lecture seule en réglant /permissions sur Read Only.
N’importe quel agent : dites-le en toutes lettres : « Ne modifie rien pour l’instant. Lis les fichiers concernés et donne-moi un plan numéroté avec les fichiers que tu vas changer. »

Un prompt de planification qui fonctionne bien :

We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.

Lire le plan prend une minute et évite les erreurs coûteuses : le mauvais dossier, une nouvelle dépendance dont vous ne voulez pas, une migration inattendue. Si le plan est faux, corrigez-le avec des mots simples (« utilise le helper toRows() existant au lieu d’un nouveau parseur ») et demandez un plan révisé.

Découpez les grosses tâches en étapes

Les agents donnent le meilleur d’eux-mêmes sur des tâches que vous pouvez relire d’une traite. Un prompt comme « construis le système de facturation » produit un énorme diff, difficile à vérifier et difficile à annuler. Découpez :

Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.

L’étape 2 est ensuite l’API, l’étape 3 l’interface, l’étape 4 les e-mails. Après chaque étape, vous relisez, vous commitez et vous lancez la suivante. Deux habitudes font fonctionner cette méthode :

Commitez entre les étapes. Un commit propre est un point de sauvegarde. Si l’étape 3 tourne mal, vous revenez à la fin de l’étape 2 au lieu de démêler un diff mélangé. Annuler les modifications de Claude Code liste les options.
Un contexte neuf pour un travail sans rapport. Utilisez /clear dans Claude Code ou /new dans Codex quand vous changez de sujet. L’ancien contexte coûte des tokens et ramène l’agent vers la tâche précédente.

Les étapes indépendantes peuvent aussi tourner en parallèle, chaque agent dans son propre git worktree pour qu’ils n’écrasent pas les fichiers des autres.

Dites à l’agent comment vérifier

« Fais que ça marche » laisse l’agent décider de ce que « marcher » veut dire. Une consigne de vérification vous rend cette décision. Les bonnes consignes sont des commandes au résultat clair :

Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
  empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.

Quelques réflexes qui relèvent la barre :

Le test d’abord. « Écris un test qui reproduit le bug, lance-le et montre-moi qu’il échoue. Puis corrige le code jusqu’à ce qu’il passe. » Cela prouve que le test couvre vraiment le bug. Plus de détails dans écrire des tests unitaires avec l’IA.
Demandez des preuves, pas des affirmations. « Colle la sortie » est plus difficile à simuler que « confirme que ça marche ».
Nommez ce qui ne doit pas casser. « Les tests existants de tests/auth/ doivent toujours passer. »
Interdisez les raccourcis. « Ne saute pas et ne supprime pas de tests, et n’ajoute pas de casts any pour faire taire les erreurs de typage. » Un agent pressé de faire passer une vérification emprunte parfois ces chemins.

Lisez ensuite le diff. Un second modèle qui relit le changement repère beaucoup de choses ; voir la code review par IA.

Les prompts qui tournent mal, et comment les corriger

Prompt	Ce qui se passe en général	Mieux
« Nettoie ce fichier »	Grosse réécriture, fonctions renommées, imports cassés ailleurs	« Extrais le parsing de `parse.ts` dans sa propre fonction ; garde l’API publique inchangée »
« Ajoute des tests »	Des tests superficiels qui vérifient que le code fait ce qu’il fait	« Ajoute des tests pour une entrée vide, un fichier de 10 Mo et un en-tête mal formé ; chacun doit échouer si je retire la vérification de la ligne 40 »
« Rends-le plus rapide »	Des micro-optimisations au hasard	« L’endpoint `/search` prend 2 s pour 10 000 lignes. Profile-le, dis-moi où part le temps, puis propose une correction »
« Applique les bonnes pratiques »	Ce que le modèle juge le mieux cette fois-ci	Nommez la pratique : « utilise le repository pattern de `src/db/users.ts` »
Une liste de dix corrections sans rapport	À moitié fait, contexte plein dès le sixième point	Une tâche par prompt, ou dix tâches dans une file d’attente

Rendez vos prompts réutilisables

Si vous tapez la même consigne à chaque session, sortez-la de vos prompts.

Règles du projet : CLAUDE.md, AGENTS.md, GEMINI.md

Chaque agent lit un fichier d’instructions de projet au début d’une session : CLAUDE.md pour Claude Code, AGENTS.md pour Codex (et plusieurs autres agents), GEMINI.md pour Gemini CLI. Mettez-y les commandes et les conventions, de façon courte et précise :

## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck

## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.

Désormais, « lance les tests avant de dire que tu as fini » fait partie de chaque prompt sans que vous ayez à le taper. /init dans Claude Code, Codex et Gemini CLI génère un premier brouillon. CLAUDE.md et AGENTS.md explique comment garder un seul jeu de règles pour plusieurs agents.

Workflows répétés : skills et commandes personnalisées

Pour une tâche que vous répétez de temps en temps, comme une release, une migration ou une checklist de review, écrivez-la une fois sous forme de skill ou de commande personnalisée et appelez-la par son nom.

Claude Code utilise des skills : un dossier contenant un fichier SKILL.md, dans .claude/skills/<nom>/ pour le projet ou ~/.claude/skills/<nom>/ pour vous. Le nom du dossier devient une commande, et $ARGUMENTS reçoit ce que vous tapez après :

---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.

Désormais, /fix-issue 123 exécute tout le prompt. Les anciens fichiers Markdown de .claude/commands/ fonctionnent toujours de la même façon, mais la documentation d’Anthropic recommande les skills pour tout nouveau travail, car un dossier de skill peut aussi contenir des scripts et des fichiers de référence. Claude charge aussi un skill de lui-même quand votre demande correspond à sa description. Plus de détails dans les skills de Claude Code.

Codex lit les skills dans .agents/skills pour un projet et ~/.codex/skills pour vous, au même format SKILL.md.

Gemini CLI utilise des commandes personnalisées TOML dans .gemini/commands/ (projet) ou ~/.gemini/commands/ (utilisateur). {{args}} est remplacé par ce que vous tapez après la commande, et les sous-dossiers deviennent des espaces de noms : git/commit.toml devient /git:commit :

description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""

Une bonne règle empirique : les règles qui s’appliquent toujours vont dans le fichier de projet, les workflows occasionnels dans des skills, et le prompt ne porte que ce qui est propre à la tâche du jour.

Un modèle de prompt à copier

Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>

Toutes les lignes ne sont pas nécessaires à chaque fois. Pour une coquille, « Goal » suffit. Pour une nouvelle fonctionnalité, remplissez-les toutes.

Écrire des prompts pour vos agents dans AgentVera

AgentVera est une application de bureau pour macOS, Windows et Linux qui exécute Claude Code, Codex, Gemini CLI et d’autres agents CLI côte à côte, dans de vrais terminaux. Les prompts restent les mêmes ; quelques fonctionnalités prennent en charge les parties répétitives :

Verify : les critères de fin que vous écrivez dans votre message sont extraits comme critères d’acceptation. Quand l’agent termine son tour, un vérificateur séparé lit le diff, lance les commandes de test autorisées et marque chaque critère comme réussi ou échoué, preuves à l’appui. Il ne peut pas modifier de fichiers. Verify est inclus dans les offres Pro et Team.
Code review : à la fin d’un tour, un second modèle Claude relit ce que l’agent a écrit, et les remarques peuvent repartir directement vers l’agent.
Send to agent : envoyez une erreur du terminal, un diff, un log ou une ligne de code à un agent avec ⌘⇧L au lieu de les copier-coller dans votre prompt.
Galerie de skills : créez, modifiez, activez ou désactivez les skills de Claude Code et de Codex dans une seule liste, et installez des skills partagés après une analyse de sécurité.
Workspace : une grille d’agents par projet, pour donner à chaque étape découpée son propre agent et son propre worktree.

Téléchargez AgentVera et essayez votre prochain prompt avec ces outils à portée de main.

En résumé

Rédigez vos prompts comme un ticket destiné à un collègue compétent qui vient d’arriver : l’objectif, où regarder, ce qu’il ne faut pas toucher et comment vous jugerez le résultat. Demandez un plan quand la tâche est grosse, découpez-la en étapes que vous pouvez relire, et donnez toujours une commande qui prouve que c’est fini. Placez ce que vous répétez dans CLAUDE.md, AGENTS.md ou un skill. Ces habitudes comptent encore plus quand l’agent touche à une base de données ; écrire du SQL et des migrations avec l’IA les applique aux schémas et aux migrations.