Note de l’auteur : cet article s’adresse aux développeurs qui utilisent déjà des agents au travail. Il explique quels éléments de contexte, documents de référence et critères de validation vérifiables préparer avant de confier une tâche, et quels points nécessitent encore une décision humaine.
Depuis que vous utilisez un agent, vous produisez effectivement davantage, mais vous êtes aussi plus fatigué. Le 3 novembre 2026, un développeur a décrit cette situation dans un billet sur V2EX : l’humain reste dans la boucle, doit vérifier les résultats et corriger à tout moment les écarts ou les problèmes de conception. Difficile, dans ces conditions, de vraiment lâcher prise. Le billet rappelle un constat bien connu : fournir davantage de contexte et de documents de référence aide l’agent à comprendre la tâche et à améliorer la qualité du livrable. Mais il ne précise pas ce que « davantage » signifie concrètement.
Ce n’est pas un énième article généraliste sur l’art de rédiger des invites. Nous allons plutôt nous concentrer sur la préparation en amont : décomposer une demande floue en objectifs, contraintes, documents de référence et critères de validation vérifiables. L’agent pourra ainsi contrôler lui-même son travail, et vous n’aurez à intervenir qu’à quelques étapes clés. Précisons qu’il n’existe actuellement aucune donnée comparative publique permettant de quantifier les effets des différentes méthodes de préparation. Les exemples présentés ici synthétisent des situations courantes : à vous d’en vérifier les effets sur vos propres tâches.
L’essentiel : à la fin de cet article, vous disposerez d’une structure réutilisable pour décrire une tâche à un agent et rédiger ses critères de validation. Vous saurez aussi distinguer les étapes que l’agent peut vérifier lui-même de celles où un humain doit trancher.
Contexte et critères d’acceptation : l’essentiel pour guider un Agent
Avant de rédiger une description de tâche, gardez ceci en tête : si un Agent s’écarte de la demande, c’est souvent parce qu’il ne partage pas votre compréhension de ce qu’il faut faire, du niveau de résultat attendu ou de ce qui ne doit pas être modifié. Voici les cinq éléments à inclure dans une bonne description de tâche.
| Élément | Description | Problème résolu |
|---|---|---|
| Objectif | Préciser en une phrase ce qui doit être livré et à qui cela s’adresse | Éviter que l’Agent élargisse lui-même le périmètre ou parte dans la mauvaise direction |
| Contexte | Présenter l’état du projet, les modules concernés et les approches déjà essayées | Éviter de réinventer ce qui existe ou de remettre en cause une conception déjà établie |
| Contraintes | Indiquer les fichiers à ne pas modifier, les technologies à utiliser et les exigences de performance ou de compatibilité | Éviter les solutions qui « fonctionnent, mais ne sont pas utilisables » |
| Références | Fournir des exemples de code existant, de la documentation d’interface et des exemples de style | Rapprocher le style et la structure du résultat de ceux du projet existant |
| Critères d’acceptation | Définir des conditions de réussite vérifiables une par une, idéalement de façon automatique | Permettre à l’Agent de vérifier son travail et vous éviter une revue ligne par ligne |
Les signes typiques qu’un Agent s’écarte de la tâche
Le message d’origine ne donne pas de scénarios précis. Voici donc quelques situations courantes avec les Agents de programmation et d’exécution de tâches. Elles semblent différentes, mais leur cause remonte souvent à un élément manquant dans la description de la tâche.
| Écart observé | Cause fréquente | Mesure préventive |
|---|---|---|
| L’Agent corrige un bug et en profite pour remanier la moitié d’un module | Les limites de l’objectif et le périmètre des modifications ne sont pas clairs | Préciser dans les contraintes quels fichiers ou fonctions peuvent être modifiés |
| Il ajoute une dépendance qui n’existe pas dans le projet | Il ne connaît pas les technologies déjà utilisées | Lister les dépendances existantes dans le contexte et interdire l’ajout de nouvelles dépendances |
| Le style du code diffère du reste du projet | Il manque des exemples de référence | Fournir une ou deux implémentations similaires comme références |
| Il annonce que la tâche est « terminée », mais ne couvre pas des scénarios essentiels | Les conditions de réussite sont floues | Formuler les critères d’acceptation sous forme de vérifications exécutables |
| La solution est techniquement viable, mais ne correspond pas à l’intention produit | Les décisions de conception n’ont pas été précisées à l’avance | Prendre d’abord les décisions de conception, puis confier leur mise en œuvre à l’Agent |
Le dernier cas mérite une attention particulière. Le problème ne vient pas d’un manque de contexte : les choix de conception eux-mêmes doivent être faits par une personne. Nous y reviendrons plus loin.
Préparer une description de tâche pour un Agent : une structure en cinq parties
En réunissant les cinq éléments ci-dessus dans un document, vous obtenez une description de tâche que l’Agent peut comprendre et utiliser pour vérifier son travail. Il est conseillé de la rédiger en Markdown et de la placer dans le dépôt du projet, par exemple sous le nom TASK.md. Vous pouvez aussi mettre les contraintes générales dans un fichier propre au projet, comme AGENTS.md, et les objectifs précis dans un document dédié à chaque tâche.
Première partie : définir l’objectif de la tâche
L’objectif doit préciser en une phrase ce qui doit être livré, à qui cela servira et dans quel contexte. Face à une consigne comme « optimiser le module de connexion », l’Agent pourrait aussi bien comprendre qu’il faut améliorer les performances, remanier le code ou revoir l’interface. Une formulation plus précise serait : « Faire en sorte que l’interface de connexion renvoie un code d’erreur uniforme lorsque le mot de passe est incorrect, afin que le frontend affiche un message, sans modifier le déroulement d’une connexion réussie. »
Pour une tâche plus importante, ajoutez sous l’objectif une phrase indiquant ce qui ne sera pas fait. Les exclusions explicites évitent souvent mieux que les descriptions positives que l’Agent élargisse le périmètre.
Deuxième partie : fournir le contexte à l’Agent
Un bon contexte n’est pas forcément abondant : il doit surtout être pertinent. Donner tout le dépôt à l’Agent ne suffit pas à lui fournir un contexte adéquat ; il doit encore savoir quelles parties concernent la tâche. Organisez ces informations dans l’ordre suivant :
- Modules concernés : indiquez les fichiers ou répertoires directement liés à la tâche, par exemple la logique de connexion dans
src/auth/et les fichiers de test correspondants. - Décisions déjà prises : expliquez les raisons des choix existants, par exemple : « Les codes d’erreur sont tous définis dans le module
errors, et non codés en dur dans le code métier. » - Solutions déjà essayées : si une approche a été testée puis abandonnée, précisez pourquoi pour éviter que l’Agent ne la reprenne.
- Terminologie : expliquez les termes métier propres au projet que l’Agent ne peut pas déduire de façon fiable à partir du code.
Troisième partie : lister les contraintes de l’Agent
Les contraintes permettent d’éviter un résultat qui fonctionne techniquement, mais qui n’est pas utilisable. Présentez les contraintes courantes sous forme de liste pour que l’Agent puisse les vérifier avant de commencer, puis une fois le travail terminé :
- Le périmètre des modifications autorisées et les fichiers qu’il est expressément interdit de modifier, comme les scripts de migration de base de données ou les définitions d’interfaces publiques.
- Les limites liées à la pile technique, par exemple : « Ne pas ajouter de dépendance tierce » ou « Utiliser uniquement la bibliothèque de journalisation déjà présente dans le projet ».
- Les exigences de compatibilité et de performance, par exemple : « Ne pas modifier les signatures des interfaces existantes ».
- La marche à suivre en cas d’incertitude, par exemple : « Si une modification d’une interface publique semble nécessaire, arrêtez-vous et expliquez pourquoi ; ne la modifiez pas de votre propre initiative. »
Ce dernier point est important. Indiquer clairement à l’Agent quand il doit s’arrêter pour demander l’avis d’une personne demande bien moins d’efforts que de découvrir après coup qu’il a pris une décision de lui-même.
Quatrième partie : choisir les références pour l’Agent
Les références servent à montrer à l’Agent comment reproduire les pratiques existantes, plutôt que de partir de zéro. Les plus utiles sont généralement des implémentations similaires dans le même projet, par exemple : « Pour ajouter une interface, inspirez-vous du code dans src/user/, notamment pour la validation des paramètres et la gestion des erreurs. » Pour la documentation externe, fournissez uniquement les sections pertinentes et précisez leur version, afin d’éviter que l’Agent ne code à partir d’une ancienne version de l’interface.
Comment rédiger des critères d’acceptation vérifiables par l’Agent
Les critères d’acceptation sont la partie de la description d’une tâche où il est le plus facile de rester vague, et celle qui mérite le plus de temps. Le principe est simple : si l’Agent ne peut pas vérifier lui-même qu’un critère est respecté, ce n’est pas un critère, mais un souhait.
| Formulation vague | Formulation vérifiable | Méthode de vérification |
|---|---|---|
| Le code doit être de bonne qualité | Les vérifications lint existantes du projet passent sans nouvel avertissement | L’Agent exécute la commande de vérification et communique le résultat |
| La fonctionnalité doit fonctionner | De nouveaux tests unitaires couvrent les trois cas suivants : mot de passe incorrect, compte inexistant et connexion réussie. Ils passent tous | Exécuter les tests et fournir un résumé des résultats |
| Ne pas affecter les autres fonctionnalités | Tous les tests existants passent et aucun fichier interdit par les contraintes n’a été modifié | Exécuter l’ensemble des tests et dresser la liste des fichiers modifiés |
| La documentation doit être complète | Ajouter une description des codes d’erreur à la documentation de l’API, dans le même format que les entrées existantes | Comparer chaque élément à l’exemple de référence |
| Les performances ne doivent pas se dégrader | Aucune requête supplémentaire à la base de données sur le chemin critique | Indiquer dans le bilan l’évolution du nombre de requêtes |
Une fois les critères rédigés, demandez à l’Agent, à la fin de la description de la tâche, de faire un bilan « critère par critère » : pour chacun, il doit préciser s’il est satisfait, sur quelle preuve il s’appuie et, le cas échéant, pourquoi il ne l’est pas. Pour vérifier le résultat, il vous suffira alors de consulter ce tableau plutôt que de relire toutes les modifications.
Prise en main rapide du contexte et des critères d’acceptation d’un agent
Voici une procédure que vous pouvez suivre directement à partir des éléments précédents. Aucun outil supplémentaire n’est nécessaire : un document Markdown suffit pour commencer.
Préparer une description de tâche pour l’agent en 5 étapes
- Rédigez d’abord les critères d’acceptation, puis l’objectif : procéder dans cet ordre vous oblige à définir concrètement ce que signifie « terminé » et évite de fixer un objectif trop vaste.
- Ajoutez le contexte nécessaire : limitez-vous aux modules concernés, aux décisions déjà prises et aux tentatives qui ont échoué.
- Listez les contraintes et les conditions d’arrêt : précisez ce qui ne doit pas être modifié et les situations où l’agent doit s’arrêter pour demander des précisions.
- Choisissez un ou deux exemples de référence : privilégiez les implémentations similaires dans le projet et ne fournissez que les sections pertinentes de la documentation externe.
- Demandez un compte rendu structuré : une fois la tâche terminée, l’agent doit rendre compte de chaque critère d’acceptation et joindre la liste des fichiers modifiés ainsi que les problèmes non résolus.
Exemple de consigne pour un agent : corriger les messages d’erreur de connexion
Voici un modèle de consigne pour un scénario fictif, présenté sous forme de liste. Vous pouvez remplacer son contenu par celui de votre propre tâche :
- Objectif : l’API de connexion doit renvoyer un code d’erreur unique lorsque le mot de passe est incorrect ou que le compte n’existe pas. Le frontend affiche un message en conséquence. Ne modifiez pas le parcours de connexion réussie ni le style de la page.
- Contexte : les codes d’erreur sont définis de manière centralisée dans le module
errors. Une tentative précédente consistait à analyser le texte des erreurs côté frontend, mais cette approche a été abandonnée à cause de la prise en charge de plusieurs langues. - Contraintes : seules les modifications dans
src/auth/et les tests associés sont autorisées ; n’ajoutez aucune dépendance ; si une modification de la définition d’une interface publique est nécessaire, arrêtez-vous d’abord et expliquez pourquoi. - Référence : la gestion des erreurs de l’API d’inscription dans
src/user/. - Critères d’acceptation : ajouter des tests unitaires pour trois scénarios et vérifier qu’ils passent tous ; vérifier que tous les tests existants passent ; ne générer aucun nouvel avertissement de lint ; ajouter à la documentation de l’API la description de deux codes d’erreur.
- Format du compte rendu : passer en revue chaque critère d’acceptation, lister les fichiers modifiés et signaler les problèmes restants.
🚀 Pour commencer : vous pouvez confier la même consigne à différents modèles et comparer leur capacité à respecter les contraintes et les conditions d’arrêt. Avec une plateforme d’agrégation comme APIYI apiyi.com, une seule interface et une même clé API suffisent pour passer d’un fournisseur à l’autre. Vous évitez ainsi de créer et de configurer plusieurs comptes, ce qui facilite les tests comparatifs sur vos tâches réelles.
Faire vérifier une solution d’Agent par des modèles de différents fournisseurs
L’auteur du billet d’origine soulève aussi une inquiétude : les modèles d’un même fournisseur pourraient partager des angles morts. Il aimerait donc que des Agents de fournisseurs différents vérifient mutuellement leur travail. Pour l’instant, il faut toutefois faire circuler les informations au moyen de documents Markdown ou de copier-coller, ce qui complique la coordination.
Cette idée peut se combiner avec la méthode présentée ici : la description de la tâche et les critères d’acceptation constituent une base commune pour la vérification croisée. Les vérificateurs n’ont pas besoin de comprendre toutes vos intentions : il leur suffit d’examiner le résultat point par point à partir des mêmes critères.
Une approche légère consiste à attribuer un rôle différent à chaque modèle, en leur fournissant à tous la même description de tâche :
| Rôle | Entrée | Responsabilité | Mode d’accès |
|---|---|---|---|
| Exécutant | Description de la tâche | Mettre en œuvre la solution et la vérifier selon les critères d’acceptation | Votre Agent de programmation habituel |
| Vérificateur A | Description de la tâche + résumé des modifications | Examiner les critères d’acceptation un par un et signaler les scénarios non couverts | Modèle d’un autre fournisseur, accessible via l’interface unifiée d’APIYI |
| Vérificateur B | Description de la tâche + résumé des modifications | Vérifier en priorité le respect des contraintes et des conditions d’arrêt | Modèle d’un troisième fournisseur ; il suffit de changer le nom du modèle avec la même interface |
| Humain | Synthèse des avis | Traiter uniquement les désaccords entre vérificateurs et les questions de conception | Aucun |
Si vous êtes prêt à écrire un petit script pour enchaîner « résultat de l’exécution → envoi aux modèles de vérification → synthèse des avis », vous pourrez remplacer la plupart des copier-coller manuels. APIYI propose une interface unifiée compatible avec les principaux SDK : il suffit de changer le nom du modèle dans le script pour appeler celui d’un autre fournisseur. Cela simplifie justement l’étape d’intégration, souvent la plus pénible lorsqu’on introduit des Agents de différents fournisseurs. Attention toutefois : seul le transfert d’informations est automatisé ; la décision finale doit rester entre les mains d’un humain.
Quels problèmes le contexte de l’Agent peut-il résoudre, et lesquels exigent une validation humaine ?
Un contexte bien préparé permet de limiter les corrections, mais ne supprime pas toute intervention humaine. Le message d’origine met sur le même plan les « tâches qui dévient » et les « problèmes de conception ». Pourtant, ces deux types de problèmes sont différents : les premiers viennent souvent d’un manque d’information, tandis que les seconds demandent généralement de faire des choix.
| Type de problème | Le contexte peut-il le résoudre ? | Pourquoi ? | Rôle humain |
|---|---|---|---|
| Modifications hors périmètre | Globalement oui | Si les contraintes sont claires, l’Agent peut vérifier son travail | Vérifier ponctuellement la liste des modifications |
| Style ou formatage incohérent | Globalement oui | Des exemples suffisent à fournir un modèle à suivre | Vérifier à l’occasion |
| Couverture des tests incomplète | En grande partie | Il suffit de préciser les scénarios dans les critères d’acceptation | Vérifier que la liste des scénarios est complète |
| Arbitrages d’architecture et de conception | Difficilement | Ils impliquent de choisir entre plusieurs solutions raisonnables | Décider en amont et consigner le choix dans la description de la tâche |
| Intention produit et expérience utilisateur | Difficilement | Elles dépendent des objectifs métier et de la compréhension des utilisateurs | Les définir en amont et valider le résultat |
| Pertinence des critères d’acceptation eux-mêmes | Non | L’Agent peut vérifier le respect des critères, mais pas remettre en question leurs fondements | La responsabilité revient à l’humain |
Les problèmes de conception sont difficiles à confier entièrement à un Agent, car ils n’ont généralement pas de réponse unique. Par exemple, faut-il placer les codes d’erreur dans un module commun ou dans un module métier ? Les deux solutions peuvent fonctionner. Le choix dépend des évolutions prévues et des habitudes de maintenance de l’équipe : des éléments qui relèvent souvent du jugement humain et sont difficiles à consigner intégralement par écrit.
Une stratégie plus pragmatique consiste donc à faire intervenir l’humain plus tôt : prenez les décisions de conception avant le début de la tâche et inscrivez-les dans les contraintes. L’Agent pourra ensuite travailler sans surveillance constante. Une fois l’exécution terminée, il ne vous restera qu’à vérifier le tableau des critères d’acceptation et les points de désaccord entre les personnes chargées de la revue. Le rôle humain passe ainsi d’un « accompagnement permanent » à une intervention ciblée : « définir la direction au départ, puis valider le résultat à l’arrivée ».
Questions fréquentes (FAQ)
Q1 : Quels sont les critères d’acceptation d’un agent ?
Ce sont les conditions vérifiables une par une qui doivent être remplies pour considérer la tâche comme terminée. Par exemple : « Tous les tests indiqués passent » ou « Aucun fichier interdit de modification n’a été modifié ». Ils permettent à l’agent de vérifier son travail et à une personne d’évaluer rapidement le résultat, sans avoir à lire toute la sortie ligne par ligne.
Q2 : Faut-il donner le plus de contexte possible ?
Non. Des informations sans rapport avec la tâche peuvent diluer les points importants, voire amener l’agent à modifier des éléments auxquels il ne devrait pas toucher. Sélectionnez le contexte en fonction de la tâche : modules concernés, décisions déjà prises, tentatives infructueuses et terminologie nécessaire. Si vous hésitez sur l’utilité d’une information, vous pouvez utiliser APIYI apiyi.com pour appeler différents modèles et tester une version courte et une version complète de la description de tâche, puis voir laquelle donne les résultats les plus pertinents.
Q3 : Faut-il rédiger une description aussi complète pour chaque petite tâche ?
Non. Les contraintes générales et le contexte du projet peuvent figurer dans un fichier d’instructions au niveau du projet et être réutilisés durablement. Pour chaque tâche, il suffit alors d’ajouter l’objectif, les ressources de référence et les critères d’acceptation. Pour une petite modification réalisable en quelques minutes, une phrase décrivant l’objectif et deux ou trois critères d’acceptation suffisent généralement.
Q4 : À quels agents et types de tâches cette méthode s’applique-t-elle ?
Elle convient surtout aux agents de programmation et aux agents chargés de tâches avec des livrables précis : corriger un défaut, implémenter une interface, générer de la documentation ou organiser des données. Pour les tâches très exploratoires dont l’objectif reste à définir, il est difficile de rédiger des critères d’acceptation à l’avance. Mieux vaut d’abord laisser la personne et l’agent discuter de la direction à prendre avant de passer à l’exécution.
Q5 : Comment faire une revue croisée avec des modèles de différents fournisseurs sans multiplier les copier-coller ?
Vous pouvez écrire un petit script qui envoie le résultat et la description de la tâche à un modèle chargé de la revue, puis rassemble les commentaires. Grâce à l’interface unifiée d’APIYI apiyi.com, il suffit de changer le nom du modèle dans le script pour appeler ceux de différents fournisseurs, sans intégrer séparément le SDK et le compte de chacun. C’est pratique pour créer rapidement un prototype de flux « exécution + revue par plusieurs modèles ».
Q6 : Quelles sont les limites de cette méthode ?
D’abord, elle ne remplace pas le jugement en matière de conception : les choix d’architecture et les intentions produit restent à la charge des personnes. Ensuite, si les critères d’acceptation sont erronés, l’agent les respectera fidèlement malgré tout. Enfin, il manque actuellement des données publiques permettant de quantifier les différences d’efficacité entre les méthodes de préparation. Comparez-les donc à petite échelle sur vos propres tâches, en notant le nombre de corrections nécessaires comme point de référence.
Contexte de l’Agent et critères d’acceptation : points essentiels
- Les écarts viennent souvent d’un manque d’informations : l’absence d’objectif, de contraintes ou de documents de référence peut entraîner des reprises.
- Cinq éléments indispensables dans la description d’une tâche : objectif, contexte, contraintes, documents de référence et critères d’acceptation.
- Les critères d’acceptation doivent être vérifiables : si l’Agent ne peut pas les vérifier lui-même, ce ne sont que des souhaits.
- Définir des conditions d’arrêt : préciser quand l’Agent doit s’arrêter pour poser une question demande moins d’efforts que de corriger après coup.
- Prendre les décisions de conception en amont : les choix d’architecture et de produit reviennent d’abord aux humains, puis sont intégrés aux contraintes.
- Utiliser les mêmes critères pour les vérifications croisées : l’interface unifiée d’APIYI permet d’invoquer des modèles de différents fournisseurs pour comparer leurs évaluations.
Résumé
Si la supervision d’un Agent vous épuise, c’est souvent parce que les informations fournies au départ sont incomplètes. Vous devez alors suivre son travail en permanence et corriger sa trajectoire au fur et à mesure. Pour mieux préparer le terrain, retenez trois points :
- Rédiger la description de la tâche en cinq parties : objectif, contexte, contraintes, documents de référence et critères d’acceptation. L’Agent saura ainsi quoi faire, quel résultat atteindre et à quoi ne pas toucher.
- Formuler les critères d’acceptation comme des points vérifiables : demandez à l’Agent de rendre compte de chaque point. Vous n’aurez plus qu’à consulter le tableau de vérification et les problèmes restants.
- Distinguer ce qui peut être résolu par le contexte de ce qui exige une validation humaine : les choix de conception se font en amont, et les humains restent responsables des critères d’acceptation.
Dès votre prochaine tâche concrète, essayez de rédiger d’abord les critères d’acceptation, puis complétez les autres parties. Notez aussi le nombre d’interventions nécessaires en cours de route : cela vous donnera une base pour progresser. Si vous testez également la vérification croisée avec des modèles de différents fournisseurs, APIYI apiyi.com vous permet d’y accéder via une interface unifiée et de vérifier, sur des tâches réelles, quelle combinaison réduit le plus vos interventions.
📚 Références
- Discussion sur V2EX – Comment réduire les interventions humaines pour laisser un agent travailler de façon autonome et améliorer la qualité des livrables : à l’origine du sujet de cet article
- Lien :
v2ex.com/t/1254207 - Présentation : cette discussion aborde la fatigue liée à l’intervention humaine dans la boucle de travail d’un agent, le rôle du contexte et l’idée d’une révision croisée par des agents de différents fournisseurs
Auteur : équipe technique d’APIYI
Échanges techniques : contactez-nous depuis la page d’accueil d’APIYI, sur apiyi.com, pour partager vos expériences sur la rédaction des instructions de tâches pour les agents et la collaboration entre plusieurs modèles.
