Écrire des specs que les développeurs et les agents IA comprennent
Écrire une spec qu’un développeur et un agent de code peuvent exécuter sans deviner, puis vérifier que ce qui est livré correspond à l’intention.
Écrire une spec qu'un développeur et un agent de code IA peuvent exécuter sans deviner, puis vérifier que ce qui est livré correspond à l'intention. Vous apprenez à choisir le bon niveau de spec, à séparer l'intention de la solution, à écrire des critères Given/When/Then vérifiables, à couvrir cas limites et exigences non fonctionnelles, à préparer le contexte d'un agent, à relire son plan et à garder la spec vivante. Vous repartez avec la spec d'une fonctionnalité de votre produit et son fichier d'intention versionné.
Ce que vous saurez faire
- Choisir le niveau de spec adapté à la décision à prendre (PRD, spec de fonctionnalité, ticket) et savoir ce que chacun doit contenir.
- Formuler l'intention d'une fonctionnalité (problème, résultat visé, contraintes, non-objectifs) séparément de la solution, pour laisser la bonne marge à l'équipe et à l'agent.
- Écrire des critères d'acceptation Given/When/Then vérifiables, déclaratifs et sans ambiguïté, y compris sous forme de tableaux d'exemples.
- Identifier les cas limites et les exigences non fonctionnelles (performance, sécurité, accessibilité, données personnelles) et les rendre testables.
- Rédiger une spec et un fichier d'intention exploitables par un agent de code (contexte, contraintes, fichiers concernés, hors périmètre, définition de terminé vérifiable).
- Relire le plan d'un agent de code contre la spec, repérer les écarts avant qu'il code, puis vérifier les preuves de ce qui a été livré.
- Garder une spec vivante (versions, décisions, mises à jour quand le code révèle un cas) et repérer les anti-patterns qui la rendent inutile.
Prérequis
- Avoir déjà écrit une spec, un PRD, une user story ou un ticket, même imparfaits
- Travailler avec une équipe de développement, ou utiliser soi-même un agent de code (Claude Code, Codex, Cursor…), ou s'y préparer
- Cours recommandé avant celui-ci, non bloquant : « Concevoir et valider une expérience produit avec l'IA » (sa leçon « Passer la main à l'équipe de développement » donne la spec d'une page que ce cours approfondit).
- Ce cours n'apprend pas à configurer un agent de code : il apprend à écrire ce que l'agent et l'équipe vont lire.
Programme
Que vais-je écrire dans ce cours, et dans quel ordre ?
- Présentation du cours3 étapes
Objectif · À la fin de cette présentation, vous saurez ce que vous allez produire (la spec d'une fonctionnalité de votre produit et son fichier d'intention) et dans quel ordre les quatre modules vous y conduisent.
À quoi sert une spec, à quel niveau l'écrire, et comment dire ce qu'on veut sans imposer comment le faire ?
Objectif · À la fin de cette leçon, vous serez capable de dire ce qu'une spec doit permettre (comprendre, décider, vérifier) et de choisir le bon niveau (PRD, spec de fonctionnalité, ticket) selon la décision à prendre et le lecteur, humain ou agent.
- L'intention avant la solution7 étapes
Objectif · À la fin de cette leçon, vous serez capable de réécrire une demande formulée comme une solution en une intention complète (problème, résultat visé, contraintes, non-objectifs), et de décider quelles parties de la solution fixer et lesquelles laisser ouvertes.
Comment écrire des critères qu'on peut vérifier, et ne pas oublier ce qui arrive quand tout ne se passe pas comme prévu ?
Objectif · À la fin de cette leçon, vous serez capable d'écrire des scénarios Given/When/Then vérifiables et déclaratifs (contexte minimal, un seul événement, résultats observables), de les nommer par ce qui les distingue et de regrouper des variantes dans un tableau d'exemples.
Objectif · À la fin de cette leçon, vous serez capable de trouver méthodiquement les cas limites d'une fonctionnalité avec une grille de questions, et d'écrire ses exigences non fonctionnelles (performance, fiabilité, sécurité, accessibilité, données personnelles) sous une forme chiffrée et testable.
Que faut-il écrire pour qu'un agent de code IA construise la bonne chose, et comment le vérifier avant et après ?
Objectif · À la fin de cette leçon, vous serez capable de transformer une spec en consigne autonome pour un agent de code : contexte, fichiers et interfaces concernés, contraintes, hors périmètre et définition de terminé avec une étape de vérification qu'il peut exécuter.
Objectif · À la fin de cette leçon, vous serez capable d'écrire le fichier d'intention versionné d'une fonctionnalité et de répartir les informations entre ce fichier, la spec et le fichier d'instructions du dépôt (CLAUDE.md ou AGENTS.md).
Objectif · À la fin de cette leçon, vous serez capable de relire le plan qu'un agent de code propose avant d'écrire le code, de repérer les écarts avec la spec (critère oublié, hors périmètre touché, supposition non dite) et de vérifier ensuite les preuves de ce qui a été livré.
Comment garder la spec juste pendant et après la construction, et livrer la vôtre ?
Objectif · À la fin de cette leçon, vous serez capable de tenir une spec à jour pendant et après la construction (versions, journal des décisions, mise à jour quand le code révèle un cas), de repérer la dérive entre spec et produit, et de reconnaître les anti-patterns qui rendent une spec inutile.
Objectif · À la fin de cet atelier, vous aurez produit la spec d'une fonctionnalité de votre produit (intention, critères Given/When/Then, cas limites, exigences non fonctionnelles, définition de terminé) et son fichier d'intention versionné, avec le kit et le plan pour les utiliser avec votre équipe et vos agents de code.