Écrire un PRD qu'un agent IA peut exécuter
Ce qu'une équipe complète en discutant doit aussi être accessible à l'agent : décisions, questions ouvertes, limites et critères d'acceptation.
Un PRD écrit pour une équipe s'appuie souvent sur du contexte commun. Les devs ont vu passer le sujet en réunion, ils savent quel module on évite de toucher, ils connaissent le client dont il est question. Quand une phrase reste floue, ils peuvent aller chercher la réponse auprès de la bonne personne. Ça ne marche pas à tous les coups, mais cette possibilité fait partie du fonctionnement de l'équipe.
Quand le premier lecteur du PRD est un agent de codage, il faut regarder ces blancs autrement. L'agent n'était pas à la réunion. Il connaît ton legacy par ce qu'il lit dans le dépôt et dans les documents que tu lui donnes. Selon ses instructions et ses réglages, il peut demander une précision, examiner le code ou choisir une réponse plausible. Une décision produit peut alors apparaître dans l'implémentation avant d'avoir été discutée.
Le travail du PM consiste à rendre ces choix visibles : ce qui est décidé, ce qui reste ouvert et ce qu'on peut vérifier avant de considérer la tâche comme terminée.
Repérer les décisions cachées dans les phrases ordinaires
« On pourrait », « idéalement », « à terme », « à évaluer » sont fréquents dans un PRD. Ces expressions peuvent désigner une piste, une exigence ou un sujet repoussé. L'agent n'a pas de raison de leur donner exactement le sens que leur donne l'équipe.
Prends cet exemple fictif, pour l'export des commandes d'une boutique en ligne :
Les clients peuvent exporter leur historique en CSV. Idéalement, on conserve les commandes annulées pour garder une trace complète.
La phrase laisse plusieurs décisions ouvertes. L'export porte-t-il sur toutes les commandes ou seulement celles du client connecté ? Les commandes annulées sont-elles une exigence ou une option ? La trace complète sert-elle le client ou un besoin interne ?
Le code devra produire un résultat. Si ces questions ne sont pas remontées, les réponses se retrouveront dans un filtre, une requête ou une colonne du CSV. On les découvrira peut-être à la revue de la pull request, à condition de savoir les y chercher.
La documentation de Claude Code conseille de préciser le contexte et de donner un moyen de vérifier le travail. Ce sont de bons points de départ. Ils ne garantissent pas que l'agent comprendra chaque intention ni qu'il demandera toujours avant de choisir.
Sortir le contexte des têtes, sans tout mettre dans le PRD
Chaque section du PRD mérite une question simple : qu'est-ce qu'un lecteur extérieur au projet aurait besoin de savoir pour agir correctement ?
| Sujet | Contexte souvent partagé oralement | Ce qu'il faut rendre accessible à l'agent |
|---|---|---|
| Problème | Le client et l'historique sont connus | Qui rencontre le problème, dans quelle situation, avec quelles conséquences |
| Périmètre | « On ne touche pas à ce module » | Les comportements exclus et, dans la tâche technique, les composants concernés |
| Résultat attendu | Le besoin se précise en discutant | Les comportements observables et les exemples qui les illustrent |
| Cas limites | Ils remontent à la relecture ou à la démo | Les cas connus et la réponse attendue ; les inconnues restent signalées |
| Contraintes | Le legacy et les dépendances sont connus | Les règles métier et les références techniques à suivre |
| Questions ouvertes | On sait à qui demander | Qui tranche, ce qui bloque et ce qu'on peut faire en attendant |
| Fin du travail | La recette est organisée dans l'équipe | Les contrôles à exécuter et la validation humaine encore nécessaire |
Cette matière existe dans les tickets, les échanges et les habitudes de l'équipe. L'écrire sert aussi aux humains qui arriveront après. Mais le PRD n'a pas à devenir une copie du dépôt ni un inventaire de toutes les exceptions imaginables. Garde les décisions produit dans le document de référence et relie les conventions techniques à leur source.
Deux dérives restent possibles. Le PRD-vitrine accumule les détails pour donner une impression de sérieux et rend les décisions importantes difficiles à trouver. Le PRD-fossile décrit trop tôt une solution que personne n'ose plus remettre en cause. Un document plus explicite doit surtout mieux distinguer ce qu'on sait de ce qu'on suppose.
Donner un statut aux questions ouvertes
Pour notre export fictif, une version exploitable pourrait être :
- Périmètre décidé : un client connecté peut exporter ses propres commandes, une ligne de données par commande. Les commandes annulées sont exclues.
- Question bloquante : les montants attendus sont-ils hors taxes ou toutes taxes comprises ? Le PM tranche. Tant que cette réponse manque, ne choisis pas une convention de montant. Signale le blocage ; tu peux poursuivre les parties indépendantes, mais l'export ne peut pas être déclaré prêt.
- Choix délégué : pour ce premier export, le séparateur par défaut est le point-virgule. Si une incompatibilité avec le composant existant impose de le changer, propose l'écart et signale-le dans la pull request.
Les statuts évitent de traiter tous les blancs de la même façon. Une règle sur les montants engage le sens métier du fichier. Un séparateur peut être délégué si ses conséquences et les outils cibles sont connus. Le PM choisit le degré d'autonomie en fonction de ce que le choix peut changer pour les utilisateurs.
Écrire « demande au PM » ne suffit pas si l'agent travaille sans personne pour lui répondre. Il faut aussi dire où il s'arrête, ce qu'il peut continuer et comment il laisse l'état du travail. Une question ouverte n'est pas une autorisation de décider.
Transformer le comportement attendu en exemples vérifiables
Les objectifs de conversion, de rétention ou de délai de traitement restent utiles : ils disent pourquoi on investit. Mais on ne peut pas vérifier leur atteinte avant la mise en service. Pour accepter l'implémentation, il faut des critères plus proches du comportement attendu.
La documentation de Claude Code recommande de donner des tests ou d'autres contrôles que l'agent peut lancer. Pour le PM, la première étape consiste à écrire des exemples assez précis pour être transformés en vérifications. Une phrase concrète suffit ; le format Given/When/Then est facultatif.
Pour poursuivre l'exemple fictif, supposons que le PM ait tranché la convention de montant. Les autres comportements peuvent alors se préciser ainsi :
| Situation | Résultat attendu |
|---|---|
| Le client A a deux commandes livrées et une annulée ; le client B a une commande livrée | L'export de A contient deux lignes de données, plus une ligne d'en-tête ; aucune commande de B ni commande annulée |
| A n'a aucune commande exportable | Le fichier contient la seule ligne d'en-tête, avec les mêmes colonnes |
| Un libellé contient un point-virgule, un guillemet et un retour à la ligne | Après lecture par un parseur CSV compatible avec la convention retenue, le libellé est restitué à l'identique dans un seul champ |
| La session du client a expiré | L'export est refusé et aucune donnée de commande n'est renvoyée |
Le premier cas vérifie à la fois une règle métier et la séparation entre comptes. Le troisième évite un faux succès : un fichier peut s'ouvrir et pourtant décaler silencieusement les colonnes.
Le PM précise le résultat attendu. Un dev choisit avec lui comment le vérifier dans le produit : test de la règle de sélection, test de l'API, lecture du CSV généré et essai depuis l'interface. Lancer seulement les tests unitaires ne prouve pas que le bouton télécharge le bon fichier.
Ces exemples ne couvrent pas tout. Selon le contexte, il faudra aussi examiner un historique volumineux, le format des dates ou les outils dans lesquels le client ouvre le CSV. On ajoute un cas parce qu'il répond à un risque identifié, plutôt que pour allonger la liste.
Séparer le PRD de la tâche d'implémentation
Le PM porte le problème, les choix de périmètre, les comportements et les critères d'acceptation. Les devs ou le tech lead apportent les interfaces concernées, les composants à réutiliser, les conventions du dépôt et les pièges connus. L'agent peut aider à retrouver ces éléments, puis un humain vérifie les références qui engagent l'implémentation.
Pour notre export, le PRD peut rester centré sur le besoin et les règles. La tâche donnée à l'agent ajoute les liens vers le composant d'export existant, la règle d'autorisation à réutiliser et les commandes de vérification du projet. Inutile d'exiger du PM qu'il invente des noms de fichiers qu'il ne connaît pas.
Addy Osmani propose de découper les specs pour agents en tranches ciblées. Chaque tâche doit garder assez de contexte pour comprendre le résultat attendu, sans emporter tout le dossier de conception. Dans notre exemple, isoler la règle de sélection peut aider ; séparer l'interface de toute vérification des droits laisserait un trou important entre les morceaux.
La tranche renvoie à une version identifiée du PRD. Si une règle change pendant le travail, mets à jour la source et indique quelles tâches sont affectées. Une copie raccourcie qui conserve une ancienne décision devient vite une deuxième vérité.
Relire avant de lancer, puis vérifier ce qui a été fait
Le guide de prompts d'Anthropic suggère de faire lire la consigne à un collègue qui dispose de peu de contexte. Les questions qu'il pose révèlent une partie des blancs. Tu peux aussi demander à l'agent de reformuler les règles et de lister les ambiguïtés avant d'implémenter. Cette préparation aide à les voir ; elle ne garantit pas qu'il les aura toutes trouvées.
Avant de lancer la tâche, vérifie surtout que les décisions sont distinguées des pistes, que chaque question ouverte a un responsable et une conduite à tenir, et que les comportements importants ont des exemples.
À la fin, demande les contrôles réellement exécutés, leurs résultats et les éléments qui n'ont pas pu être vérifiés. Compare cela aux critères du PRD. Un test qui passe prouve que les cas testés passent ; la lecture du diff sert aussi à repérer une règle inventée, une valeur codée en dur ou un changement hors périmètre. La recette complète ce que les tests ne couvrent pas.
Garder le droit d'apprendre avant de spécifier
Un PRD précis ne rend pas le problème pertinent. Si l'incertitude porte encore sur l'utilité d'un export, on peut commencer par produire un fichier à la main et regarder ce que le client en fait. Détailler tout de suite l'automatisation figerait une solution avant d'avoir compris le besoin.
Les comportements des agents évoluent aussi avec les outils, les modèles et les instructions du projet. Cet article propose une manière de préparer et de relire le travail, illustrée par un cas fictif ; il ne rapporte pas un essai comparatif.
Le temps passé à décider reste souvent invisible dans une démo. Le PRD permet d'en garder la trace et d'éviter que ces décisions arrivent pour la première fois au milieu du code. Pour chaque blanc, demande-toi qui le comblait auparavant, et qui aura la main cette fois-ci.
Sources
- Anthropic, Best practices for Claude Code, consulté en octobre 2026.
- Anthropic, Prompting best practices, consulté en octobre 2026.
- Addy Osmani, How to write a good spec for AI agents, 13 janvier 2026.
À lire ensuite
Recevoir la newsletter
Des tutos, des essais et des retours bruts sur ce que je construis. Le lien pour te désabonner est en bas de chaque édition.
L’inscription se termine sur Substack, dans un nouvel onglet.