Écrire une spec qu’un agent IA de code peut exécuter
Une spec pour agent IA dit quoi construire, pourquoi et comment le vérifier. Sections, découpage, contrôle du travail de l’agent et modèle SPEC.md gratuit.
Guide rédigé par Alex Dionisio, Senior Product Manager. Mis à jour le 13 novembre 2026.
En bref
Une spec pour agent IA est un document court qui dit à un agent de code (Claude Code, Cursor, Codex…) quoi construire, pourquoi, dans quelles limites et comment prouver que c’est fini. Elle diffère d’un PRD par son grain : une tâche précise, des critères d’acceptation testables et un périmètre explicite. Sans elle, l’agent comble les trous par des suppositions plausibles. Avec elle, vous vérifiez le résultat contre un texte écrit.
Qu’est-ce qu’une spec pour agent IA ?
Une spec pour agent IA est un fichier, souvent nommé SPEC.md, qui décrit une fonctionnalité avec assez de précision pour que l’agent de code la construise sans deviner : objectif, contexte, périmètre, critères d’acceptation testables, contraintes et cas limites. C’est aussi la référence contre laquelle vous relisez son travail.
Un agent IA de code lit votre dépôt, modifie des fichiers, lance des commandes et enchaîne les étapes seul jusqu’à juger la tâche terminée. Il exécute ce que vous avez écrit, pas ce que vous pensiez lui avoir demandé. La spec sert à réduire l’écart entre les deux.
Concrètement, une spec pour agent occupe une ou deux pages de Markdown, posée dans le dépôt ou collée dans la session. Elle s’adresse à un lecteur qui ne connaît ni vos utilisateurs, ni vos réunions, ni l’historique des décisions, et qui ne posera pas toujours la question quand une information manque.
On parle de spec-driven development quand cette spec devient le point de départ du travail : on écrit d’abord quoi construire et pourquoi, puis on en tire un plan, des tâches et enfin le code. Le kit open source Spec Kit de GitHub outille cette démarche. La documentation de Claude Code en propose une version légère : faire rédiger un SPEC.md, puis lancer la construction depuis ce fichier dans une nouvelle session.
Spec, PRD ou user story : quelle différence ?
Un PRD pose le cadre d’une initiative (problème, public visé, objectifs), une user story exprime le besoin d’un utilisateur, et une spec pour agent décrit une tâche précise avec ses limites et sa preuve de fin. La spec pour agent est plus étroite et plus explicite que les deux autres.
Les trois documents ne s’opposent pas, ils s’emboîtent. Le PRD répond à « pourquoi cette initiative ? ». La user story répond à « qui a besoin de quoi, et pour quoi faire ? ». La spec pour agent répond à « qu’est-ce qui doit être vrai dans le produit à la fin de cette tâche, et comment le constater ? ».
- Le lecteur : le PRD s’adresse à l’équipe et aux décideurs, la user story à l’équipe qui en discutera, la spec pour agent à un exécutant qui n’assistera à aucune discussion.
- Le grain : un PRD couvre souvent plusieurs semaines de travail ; une spec pour agent couvre une tâche dont on peut relire le résultat d’une traite.
- L’implicite : une user story laisse volontairement des détails à la conversation. Une spec pour agent doit les écrire, parce que cette conversation n’aura pas lieu ou sera très courte.
- La preuve : la spec pour agent se termine par des critères que l’agent peut exécuter ou constater, pas par une intention générale.
Gardez donc votre PRD et vos user stories : la spec pour agent en extrait le morceau à construire et la complète avec les informations absentes du code. La leçon PRD, spec ou ticket : quel niveau choisir aide à fixer le bon niveau de détail selon la décision à prendre.
Pourquoi un agent IA de code a-t-il besoin d’une spec ?
Un agent IA de code a besoin d’une spec parce que seul l’écrit lui parvient : le code du dépôt, ses fichiers d’instructions et votre message. Les décisions prises en réunion, les priorités et les cas connus de l’équipe lui échappent, et il remplit ces vides par des choix plausibles mais parfois faux.
- Le contexte manquant. Un agent récent lit très bien un dépôt : structure, conventions, tests existants. Il lui manque en revanche tout ce qui n’y figure pas : la règle métier décidée la semaine dernière, le client qui a un cas particulier, la raison d’un choix. La même consigne figure dans la documentation de Claude Code : réserver l’écrit à ce qu’une lecture du code ne révélera jamais.
- L’ambiguïté. Face à une consigne floue, un collègue pose une question. Un agent avance souvent avec l’interprétation la plus probable. Le résultat fonctionne, a l’air fini, et ne fait pas ce que vous vouliez. Le mécanisme ressemble à une hallucination de LLM : une réponse vraisemblable à la place d’une information absente.
- La fenêtre de contexte. Tout ce que l’agent a en tête pendant une session tient dans sa fenêtre de contexte : instructions, fichiers lus, sorties de commandes, échanges. Un contexte encombré de tentatives ratées donne de moins bonnes réponses, alors qu’une session qui démarre d’une spec écrite part d’un contexte propre. Ce que vous avez expliqué dans une session précédente n’existe plus pour l’agent s’il n’est écrit nulle part.
La spec ne sert donc pas à « parler à l’IA » avec des formules spéciales. Elle met par écrit les décisions qui ne sont pas dans le code. Pour l’installation et la prise en main de l’outil lui-même, voir le guide Claude Code pour Product Manager.
Que doit contenir une spec pour agent IA ?
Une bonne spec pour agent IA contient sept blocs : l’objectif, le contexte utile, le périmètre et le hors périmètre, des critères d’acceptation testables, les contraintes, des exemples concrets et les cas limites. Chaque bloc répond à une question que l’agent trancherait sinon tout seul.
- Objectif : le problème résolu et le résultat attendu, en deux ou trois phrases. Le « pourquoi » aide l’agent à arbitrer les petits choix dans le bon sens.
- Contexte : ce que l’agent ignore forcément. Utilisateurs concernés, règles métier, décisions déjà prises, écran ou fichier de départ s’il est connu.
- Périmètre et hors périmètre : ce qui doit changer, et surtout ce qui doit rester intact. Une ligne « ne pas toucher au module de paiement » évite bien des modifications surprises.
- Critères d’acceptation : des critères d’acceptation vérifiables, idéalement sous la forme Étant donné / Quand / Alors (Given/When/Then) : une situation, une action, un résultat observable. « Rapide » ou « intuitif » ne se vérifient pas ; « la liste s’affiche en moins d’une seconde avec 500 éléments » se vérifie.
- Contraintes : les exigences non fonctionnelles (performance, sécurité, accessibilité, données personnelles) et les contraintes techniques imposées, comme une bibliothèque existante à réutiliser ou l’interdiction d’ajouter une dépendance.
- Exemples : une entrée et la sortie attendue, le texte exact d’un message d’erreur, la maquette de l’écran. Un exemple lève plus d’ambiguïté qu’un paragraphe d’explication.
- Cas limites : donnée vide, valeur extrême, doublon, action interrompue, droits insuffisants. Ce sont les situations que l’agent gère le moins bien quand personne ne les a écrites.
Terminez par une définition de terminé : la commande de vérification à lancer, ce qui doit passer, et ce que l’agent doit vous montrer comme preuve. Si la fonctionnalité produit elle-même une réponse d’IA, le format de cette réponse fait partie de la spec : le cours Sorties structurées montre comment l’écrire comme un contrat.
Comment découper une fonctionnalité pour un agent ?
Découpez une fonctionnalité en tâches qu’un agent peut terminer et dont vous pouvez relire le résultat d’une traite : une tâche, un comportement observable, une liste de critères. Une tâche dont vous ignorez comment la vérifier est trop grosse ou encore floue.
Une spec unique pour « refaire l’onboarding » produit une modification énorme, difficile à relire, où les erreurs se cachent. Mieux vaut une spec de fonctionnalité qui garde la vue d’ensemble, puis une série de tâches courtes qui y renvoient.
- Découpez par comportement visible, pas par couche technique. « L’utilisateur peut passer l’étape 2 » se teste ; « créer le modèle de données » ne dit pas quand c’est fini.
- Ordonnez par dépendance : les fondations d’abord, les variantes et les finitions ensuite.
- Une tâche, une session : repartir d’un contexte propre pour chaque tâche évite que l’agent mélange les consignes.
- Isolez ce qui est risqué : migration de données, paiement, droits d’accès. Ces tâches méritent leur propre spec et une relecture plus attentive.
Un test simple : pouvez-vous lister les critères d’acceptation de la tâche sans écrire « etc. » ? Si oui, elle est prête pour l’agent.
Comment vérifier le travail d’un agent IA de code ?
Vérifiez le travail d’un agent IA de code à deux moments : avant qu’il code, en relisant son plan contre la spec, puis après, en exigeant une preuve pour chaque critère d’acceptation (tests lancés, sorties, captures). Un agent qui annonce « c’est terminé » n’a encore rien prouvé.
- Relisez le plan. Dans Claude Code, le mode plan fait explorer le dépôt et proposer des changements sans modifier le code avant votre validation. Cherchez les critères oubliés, les fichiers hors périmètre et les suppositions non dites.
- Donnez-lui un contrôle à lancer. Un test, un build ou un script qui renvoie réussite ou échec permet à l’agent de corriger seul avant de vous rendre la main. Sans contrôle, c’est vous qui jouez le rôle de la suite de tests.
- Demandez les preuves. La commande lancée et sa sortie, ou la capture d’écran, critère par critère. Lire une sortie de test va plus vite que tout refaire soi-même.
- Faites relire contre la spec. Un relecteur neuf, humain ou sous-agent, compare les changements au SPEC.md : chaque exigence est-elle couverte, chaque cas limite testé ? Anthropic recommande, dans ses bonnes pratiques pour Claude Code, de lui faire ignorer le style, pour ne remonter que les écarts qui comptent.
- Essayez vous-même le parcours. Ouvrez l’écran, tentez un cas limite. Quelques minutes d’usage réel attrapent ce que les tests n’avaient pas prévu.
La leçon consacrée à relire le plan proposé par l’agent détaille cette relecture pour un PM qui ne lit pas le code. Côté outil, le cours Claude Code : contexte, plan et revue met en place permissions, garde-fous et revue sur votre dépôt.
Quelles erreurs éviter dans une spec pour agent ?
Les erreurs les plus fréquentes dans une spec pour agent sont les critères invérifiables, l’oubli du hors périmètre, la solution imposée sans le problème, les cas limites absents et la spec trop longue qui noie l’essentiel. Chacune laisse l’agent décider à votre place.
- Des critères qui ne se vérifient pas : « simple », « robuste », « comme d’habitude ». Remplacez chaque adjectif par un résultat observable.
- Pas de hors périmètre : l’agent améliore au passage un composant voisin, renomme des fichiers, ajoute une dépendance. Listez ce qui reste intouchable.
- La solution sans le problème : « ajoute un export CSV » sans dire que le besoin est de partager un rapport avec la direction. L’agent livre l’export, pas forcément ce qui résout le problème.
- Trop de texte : une spec de dix pages qui réexplique l’architecture du dépôt. L’agent lit déjà le code ; gardez la place pour les informations absentes du dépôt.
- Des consignes en majuscules : « TOUJOURS », « IMPORTANT ». D’après les bonnes pratiques publiées par Anthropic, les modèles actuels suivent une consigne formulée simplement ; une règle qui ne souffre aucune exception relève d’un contrôle automatique, pas de capitales.
- La spec écrite après coup : rédigée pour documenter ce que l’agent a déjà fait, elle ne guide plus rien et ne permet plus de vérifier.
Comment faire vivre une spec après la livraison ?
Faites vivre une spec en la versionnant avec le code, dans le même dépôt, et en la mettant à jour chaque fois qu’une décision ou un cas découvert change le comportement attendu. Une spec qui ne décrit plus le produit induit l’équipe et les agents en erreur.
Une spec pour agent n’est pas jetable. Quand l’agent révèle un cas non prévu, il ne suffit pas de corriger le code : ajoutez le cas à la spec, pour que la prochaine session, ou le prochain agent, parte de la bonne version.
- Versionnez-la avec Git, dans un dossier dédié ou à côté de la fonctionnalité, pour que chaque changement de comportement laisse une trace.
- Notez les décisions en bas du fichier : date, choix, raison. C’est l’information qui se perd le plus vite.
- Sortez les règles durables : les conventions valables pour tout le dépôt vont dans le fichier d’instructions de l’agent (CLAUDE.md pour Claude Code, AGENTS.md pour Codex, Cursor et d’autres outils), pas dans chaque spec.
- Supprimez ce qui est devenu faux plutôt que d’empiler des exceptions.
Pour appliquer toute la méthode à une fonctionnalité de votre produit, de l’intention au fichier versionné dans le dépôt, la formation Écrire des specs pour développeurs et agents IA vous accompagne étape par étape.
Modèle gratuit : SPEC.md
Copiez ce fichier dans votre dépôt, remplissez une copie par tâche et donnez-la à votre agent avant de lui demander un plan. Supprimez les lignes qui ne s’appliquent pas.
Télécharger SPEC.md# Spec : [nom de la fonctionnalité]
Statut : brouillon | prête | livrée
Dernière mise à jour : [date]
## Objectif
[Quel problème, pour quels utilisateurs, quel résultat attendu. 2 à 3 phrases.]
## Contexte
- Utilisateurs concernés : ...
- Règles métier à respecter : ...
- Décisions déjà prises : ...
- Point de départ (écran, fichier), si connu : ...
## Périmètre
- [Ce qui doit changer]
## Hors périmètre
- [Fichiers, écrans ou comportements à laisser intacts]
- Pas de nouvelle dépendance sans accord.
## Critères d’acceptation
1. Étant donné [situation], quand [action], alors [résultat observable].
2. Étant donné ..., quand ..., alors ...
3. ...
## Contraintes
- Performance : ...
- Sécurité et données personnelles : ...
- Accessibilité : ...
- Technique : [bibliothèque à réutiliser, compatibilité à garder]
## Exemples
- Entrée : ... → résultat attendu : ...
- Message d’erreur exact : « ... »
## Cas limites
- Donnée vide : ...
- Valeur extrême : ...
- Action interrompue ou répétée : ...
- Droits insuffisants : ...
## Définition de terminé
- [ ] Chaque critère d’acceptation a un test qui passe
- [ ] Commande de vérification : [ex. npm test]
- [ ] Preuves fournies : commande lancée, sortie, captures
- [ ] Aucun fichier hors périmètre modifié
## Décisions
- [date] : [décision], parce que [raison]
Passer à la pratique
La formation « Écrire des specs que les développeurs et les agents IA comprennent » vous guide pas à pas, sur votre propre produit, jusqu’au livrable.
Voir la formationQuestions fréquentes
Faut-il savoir coder pour écrire une spec pour agent IA ?
Non. Une spec décrit un comportement attendu, des règles et des preuves, pas du code. Savoir lire une sortie de test aide à vérifier, mais l’essentiel du travail est un travail produit : clarifier l’intention, les limites et les critères.
Quelle longueur pour une spec destinée à un agent de code ?
Une à deux pages par tâche suffisent le plus souvent. Si la spec déborde largement, la tâche est sans doute à découper, ou la spec réexplique des choses que l’agent trouvera dans le code.
Peut-on demander à l’IA d’écrire la spec ?
Oui, comme point de départ. La documentation de Claude Code suggère de demander à l’agent de vous interviewer jusqu’à pouvoir rédiger un SPEC.md, puis de construire dans une nouvelle session. Relisez quand même chaque critère : l’agent ne connaît vos décisions que si vous les lui donnez.
La même spec fonctionne-t-elle avec Claude Code, Cursor et Codex ?
Oui, si elle est écrite en Markdown simple, sans syntaxe propre à un outil. Ce qui varie selon l’outil, c’est le fichier d’instructions permanent et la manière de demander un plan ou de lancer les vérifications.
Spécifier un agent de code, est-ce la même chose que spécifier un agent IA dans mon produit ?
Non. Ici, l’agent est l’exécutant qui écrit le code. Spécifier un agent embarqué dans votre produit (ses outils, sa boucle, ses validations humaines) est un autre exercice, traité dans la formation agents IA et tool calling.