« Qu’est-ce que le développement piloté par les spécifications ? La spécification comme source de vérité »

Le développement piloté par spécifications (Spec-Driven Development) est l’une de ces idées que les ingénieurs logiciels ont déjà adoptées par le passé, puis mises de côté lorsque l’effort cessait d’être rentable.

Ce qui a changé en 2025, c’est l’arrivée des agents de codage par IA, qui ont rendu l’absence d’intention explicite coûteuse. Les prompts sont éphémères. Les sessions d’agents sont réinitialisées. Le code change, mais le raisonnement qui l’accompagne disparaît. La spécification est l’artefact qui empêche cela.

La spécification devient la source de vérité

Pendant la majeure partie de l’histoire du développement logiciel, la spécification était soit un artefact de planification temporaire, soit une après-pensée. Les exigences vivaient dans les tickets, les décisions de conception dans les fils de discussion, et le code était la vérité de terrain. La documentation décrivait ce qui existait a posteriori.

Le développement piloté par spécifications inverse cette relation. La spécification devient l’artefact principal. Le code est ce qui est généré ou vérifié par rapport à la spécification, et non l’inverse.

Ce n’est pas une idée nouvelle. Les méthodes formelles, la conception par contrat et le développement piloté par les comportements (BDD) contiennent tous des versions de ce concept. Ce qui est nouveau, c’est la motivation pratique : les agents de codage par IA ont besoin d’un contexte explicite et durable pour produire une sortie correcte et cohérente. Les prompts sont trop éphémères. La spécification est le seul artefact capable de porter l’intention à travers les sessions d’agents, les membres de l’équipe et le temps.

Ce que signifie réellement le développement piloté par spécifications

Le développement piloté par spécifications, généralement abrégé en SDD, est un flux de travail où une spécification versionnée guide ou génère l’implémentation. La spécification est écrite et révisée avant que l’agent n’écrive du code. Elle capture :

• Ce qu’il faut construire – problème utilisateur, objectifs et non-objectifs
• À quoi ressemble un comportement correct – critères d’acceptation, cas limites, états d’erreur
• Comment le construire – décisions d’architecture, modèle de données, contrats d’API, contraintes de sécurité
• Comment le vérifier – stratégie de test, règles de validation, traçabilité vers les exigences

Ce dernier point est facile à écrire et facile à ignorer en pratique. Maintenir spécifications, tests et code synchronisés dans le développement par IA couvre à quoi ressemble réellement la traçabilité vers les exigences en tant que données : identifiants d’exigences, identifiants de décisions de conception et tests liés aux demandes de tirage (pull requests) qui les ont implémentés.

La spécification n’est pas un document unique. Elle est mise à jour lorsque la réalité diffère de la conception. Lorsque l’agent découvre quelque chose pendant l’implémentation que la spécification a mal formulé, la spécification est corrigée avant de continuer. La spécification reste honnête parce qu’elle est traitée comme du code.

Les travaux académiques récents formalisent ce cadre : les chercheurs décrivent le SDD comme le traitement des spécifications comme source de vérité et du code comme généré ou vérifié par rapport à elles. L’interprétation pratique est que la spécification est l’enregistrement durable et révisé de l’intention que tout outil humain ou IA peut lire et auquel on peut faire confiance.

Trois termes capturent différents points sur le spectre de l’utilisation de spécifications :

Spec-first (Spécification en premier) signifie écrire la spécification complète avant le début de toute implémentation. C’est l’interprétation la plus stricte et celle qui se rapproche le plus du modèle en cascade (waterfall) si elle n’est pas faite avec soin.

Spec-anchored (Ancrage par spécification) signifie maintenir une spécification synchronisée avec l’implémentation tout au long du cycle de vie de la fonctionnalité. La spécification est mise à jour au fur et à mesure que les décisions changent. C’est la version la plus pratique pour la plupart des équipes.

Spec-as-source (Spécification comme source) signifie générer ou valider l’implémentation à partir de la spécification, soit par des agents IA, soit par des outils qui vérifient le code par rapport aux contraintes de la spécification. C’est la direction vers laquelle se dirigent des outils comme GitHub Spec Kit et Kiro, chacun avec un compromis différent entre portabilité et guidage intégré à l’IDE. Les paquets de compétences comme Superpowers se situent plus près de l’extrémité “spec-anchored” – ils appliquent la discipline de révision automatiquement plutôt que de générer du code directement à partir de la spécification.

Pourquoi le SDD est important maintenant

La réponse honnête est que le SDD n’est pas convaincant pour un développeur solo qui construit un script d’une journée. La surcharge n’en vaut pas la peine.

Le SDD devient précieux lorsque trois conditions sont présentes : la fonctionnalité est assez grande pour s’étendre sur plusieurs sessions, l’agent doit prendre des décisions qui affectent l’architecture, et le travail sera révisé ou poursuivi par quelqu’un d’autre.

Les trois conditions sont de plus en plus courantes avec le développement assisté par IA.

Les LLM ont besoin de contexte, pas seulement de prompts. Un modèle qui reçoit un prompt vague prend des décisions vagues. Un modèle qui reçoit une spécification révisée avec des contraintes explicites, des non-objectifs et des critères d’acceptation prend de meilleures décisions et est plus facile à corriger lorsqu’il dévie. Cela se connecte à la façon dont fonctionnent la récupération et la représentation : donner à un agent une spécification versionnée est une forme de récupération structurée de l’intention du projet.

La génération de code est bon marché ; décider quoi construire reste difficile. Le goulot d’étranglement dans le développement assisté par IA n’est plus la frappe – c’est de savoir quoi construire et comment contraindre l’agent. Le SDD déplace l’effort là où cela compte : spécifier clairement l’intention avant que la génération ne commence.

Les prompts sont éphémères. L’agent ne se souvient pas de ce que vous lui avez dit dans la session précédente. Une spécification versionnée stockée dans le dépôt, si, se souvient. Chaque nouvelle session peut lire la même spécification et implémenter selon la même intention sans rétablir le contexte de zéro.

**Le Vibe coding est plus rapide pour les travaux jetables ; SDD vs Vibe Coding couvre quand ajouter des spécifications et quand continuer à prompter librement.

Artefacts principaux

Le SDD produit quatre types d’artefacts. Chacun réduit un type différent d’ambiguïté avant que l’agent ne touche au code :

• Spécification des exigences – problème, utilisateurs, objectifs, non-objectifs, critères d’acceptation
• Spécification de conception – architecture, modèle de données, contrats d’API, contraintes de sécurité pour cette fonctionnalité
• Plan de tâches – petites tranches d’implémentation avec dépendances et critères de validation
• Enregistrement de traçabilité – correspondance des critères d’acceptation aux tests, des décisions de conception aux fichiers, des tâches aux commits

Comment les produire et les réviser étape par étape – spécifier, planifier, tâches, implémenter, valider – est couvert dans Workflow de développement piloté par spécifications : des exigences au code. Une fonctionnalité simple peut couvrir les quatre domaines dans un fichier markdown court. L’habitude compte plus que le format.

En quoi le SDD diffère de la documentation

La confusion la plus courante est de traiter les artefacts SDD comme de la documentation. Ce n’est pas de la documentation au sens conventionnel.

La documentation décrit. Elle vous dit ce que le système fait, comment l’utiliser et ce qu’il contient. Elle est écrite a posteriori et mise à jour lorsque le système change.

Les spécifications contraignent. Une spécification dit à l’agent ce qu’il est autorisé à construire et ce qu’il n’est pas autorisé à faire. Elle est autoritaire avant le début de l’implémentation. Elle est validée après la fin de l’implémentation. Une spécification qui décrit ce qui a été réellement construit – plutôt que de contraindre ce qui devrait être construit – a déjà échoué à sa fonction.

Les spécifications exécutables guident la génération et la validation. Les meilleures spécifications SDD sont assez proches du lisible par machine pour qu’un agent puisse implémenter à partir d’elles et qu’une suite de tests puisse les vérifier. Des critères d’acceptation écrits comme “l’endpoint doit rejeter les requêtes non authentifiées avec une réponse 401” sont une spécification exécutable ; “l’endpoint est sécurisé” est de la documentation.

Les Enregistrements de Décision – ADR, PDR et DDR – sont complémentaires aux artefacts SDD mais servent un but différent. Les enregistrements de décision capturent pourquoi un choix a été fait et ce qui a été rejeté. Les spécifications SDD capturent quoi construire et comment le vérifier. Les deux doivent être dans le dépôt. Ensemble, ils donnent aux agents IA la vue d’ensemble : l’intention actuelle et le raisonnement qui l’accompagne.

En quoi le SDD diffère du TDD

Le développement piloté par les tests (TDD) et le développement piloté par les spécifications sont souvent confondus car tous deux produisent des artefacts explicites avant l’existence du code. La différence est le point de départ.

Le TDD commence par les tests. Vous écrivez un test qui échoue et qui décrit le comportement souhaité, puis vous écrivez le code minimum pour le faire passer. Le TDD est une boucle de rétroaction au niveau de l’unité. Il produit de bons tests mais ne répond pas à la question de savoir si vous construisez la bonne chose.

Le SDD commence par l’intention. Avant l’existence des tests, avant que l’architecture ne soit décidée, la spécification répond à : qui a ce problème, à quoi ressemble un comportement correct, qu’est-ce qui est explicitement hors périmètre. La spécification informe ensuite quels tests écrire, ce qui est pourquoi un bon SDD et un bon TDD sont complémentaires plutôt que concurrents.

Une façon pratique de le concevoir : le SDD pilote le TDD. Les critères d’acceptation dans la spécification deviennent les scénarios de test. La spécification de conception identifie les limites d’intégration qui ont besoin de tests de contrat. Le plan de tâches identifie quels comportements d’unité ont besoin d’une couverture de tests avant que l’agent ne les implémente.

En quoi le SDD diffère du BDD

Le développement piloté par les comportements (BDD) utilise des scénarios en langage naturel – typiquement au format Gherkin – pour décrire le comportement attendu du point de vue de l’utilisateur. Ces scénarios comblent le fossé entre l’intention métier et l’implémentation technique.

Le SDD est plus large. Il inclut les descriptions de comportement (qui peuvent utiliser un langage de type BDD ou une prose simple) mais couvre aussi les décisions d’architecture, les modèles de données, les contraintes de sécurité, la planification des tâches et la traçabilité. Le BDD peut être un format utile pour écrire les critères d’acceptation à l’intérieur d’une spécification des exigences SDD. La spécification est le conteneur ; les scénarios BDD sont une façon d’écrire ce qui s’y trouve.

La distinction est importante en pratique : les outils BDD se concentrent sur la faisabilité d’exécution des scénarios. La pratique SDD se concentre sur la durabilité de l’intention – à travers les outils, les sessions et les membres de l’équipe.

En quoi le SDD diffère des méthodes formelles

Les méthodes formelles utilisent la notation mathématique et la vérification automatique pour prouver les propriétés des systèmes logiciels. Elles sont extrêmement rigoureuses et extrêmement coûteuses pour la plupart des contextes de développement de production.

Le SDD n’exige pas de notation formelle. Un fichier markdown avec des critères d’acceptation et des décisions d’architecture est une spécification. Il contraint sans être mathématiquement formel. Le niveau de rigueur évolue avec l’enjeu : une spécification pour un service de facturation doit être plus précise et plus soigneusement révisée qu’une spécification pour une page de documentation.

La relation est un spectre :

• Spécification en prose informelle (SDD minimum viable)
• Markdown structuré avec critères d’acceptation et non-objectifs
• Spécification lisible par machine avec validation de schéma
• Tests de contrat dérivés directement de la spécification
• Spécification formelle avec preuve automatique

La plupart des équipes opèrent au milieu de ce spectre. L’objectif n’est pas la rigueur mathématique – c’est de rendre l’intention assez explicite pour qu’un agent IA puisse implémenter à partir d’elle et qu’un réviseur humain puisse vérifier le résultat.

Avantages du développement piloté par spécifications

Moins de dérive d’intention. La spécification est la référence. Lorsque l’agent dévie – et il le fera – le réviseur a quelque chose sur quoi comparer l’implémentation. Sans spécification, la dérive est invisible jusqu’à ce que quelque chose casse.

Meilleures sorties IA. Les agents donnés avec des contraintes explicites, des non-objectifs et des critères d’acceptation produisent des implémentations plus proches de l’intention et plus faciles à corriger lorsqu’ils ratent. La qualité du contexte détermine directement la qualité de la sortie.

Révision plus facile. Une demande de tirage (pull request) attachée à une spécification est plus facile à réviser qu’une demande de tirage qui oblige le réviseur à reconstruire l’intention à partir du code. La spécification est la liste de contrôle de révision.

Alignement de l’équipe. Lorsque plusieurs personnes ou agents travaillent sur la même fonctionnalité, la spécification est le contrat partagé. Sans elle, chaque contributeur optimise localement et les pièces peuvent ne pas s’ajuster.

Meilleure planification des tests. Les critères d’acceptation dans la spécification correspondent directement aux cas de test. La couverture de tests devient une question de couverture de spécification : chaque critère d’acceptation est-il couvert par au moins un test ?

Passage de relais durable. Lorsqu’une fonctionnalité change de mains – entre ingénieurs, entre sessions d’agents, entre sprints – la spécification est l’artefact de passage de relais. Elle capture ce qui a été décidé, ce qui était hors périmètre et ce qu’il reste à valider.

Coûts du développement piloté par spécifications

Effort initial. Écrire une bonne spécification avant d’écrire du code prend du temps. Pour les petites fonctionnalités, cette surcharge est réelle et parfois ne vaut pas la peine.

Fausse confiance. Une spécification qui existe mais n’est pas validée par rapport à l’implémentation donne un faux sentiment de correction. Les spécifications obsolètes sont parfois pires que l’absence de spécification : elles induisent en erreur les réviseurs et les agents qui les lisent.

Spécifications obsolètes. Les spécifications dérivent lorsque l’équipe les traite comme des artefacts de planification plutôt que comme des documents vivants. Mettre à jour la spécification lorsque l’implémentation diffère de la conception n’est pas optionnel – c’est ce qui distingue le SDD de la documentation qui s’accumule et pourrit.

Bureaucratie générée. Les agents IA peuvent générer rapidement des listes de tâches exhaustives et des spécifications verbeuses. Une spécification de 200 tâches générée en trente secondes n’est pas une spécification utile – c’est un générateur de bureaucratie. Un bon SDD exige un jugement sur ce qu’il faut spécifier et ce qu’il faut laisser implicite.

Verrouillage par les outils. Certains outils SDD sont dogmatiques quant au format, à la structure des fichiers et au flux de travail. Une spécification écrite dans un format propriétaire est plus difficile à transporter entre les outils qu’un fichier markdown avec des en-têtes clairs et des critères d’acceptation.

Conclusion

Le développement piloté par spécifications n’est pas une nouvelle méthodologie. C’est une ancienne discipline qui redevient pratique parce que le coût de l’intention implicite est maintenant visible dans le code généré par IA.

La discipline est simple : notez ce que vous intendez construire, révisé et versionné, avant que l’agent ne le construise. Gardez cet enregistrement honnête en le mettant à jour lorsque la réalité diffère. Utilisez-le comme référence pour la révision, les tests et le passage de relais.

La spécification n’est pas magique. Une spécification qui n’est pas validée devient le type de documentation le plus coûteux : celle qui induit en erreur avec confiance. Un bon SDD est la pratique de garder les spécifications honnêtes – assez petites pour être maintenues, assez précises pour contraindre, et assez durables pour survivre à toute session d’agent.

Le SDD se situe à l’intersection de la pratique de la documentation, de l’architecture de test et de la conception de code – tout couvert dans le cluster Architecture d’application en production aux côtés des enregistrements de décision, de la conception d’API et des modèles d’accès aux données.

Liens utiles

• Enregistrements de décision pour le développement logiciel piloté par IA – ADR, PDR et DDR qui complètent les spécifications SDD en capturant pourquoi les décisions ont été prises
• Développement piloté par spécifications vs Vibe Coding : Waterfall ? – quand ajouter des spécifications et quand continuer à prompter librement
• Qu’est-ce que le Vibe Coding – Signification, Outils, Avantages et Risques – le pilier du cluster Vibe coding
• Architecture d’application en production – la maison du cluster pour l’architecture, la documentation, les tests et les modèles d’intégration
• Tests unitaires en Go : Structure et bonnes pratiques – transformer les critères d’acceptation SDD en tests exécutables
• Tests unitaires en Python : Guide complet – pratiques d’écriture de tests qui correspondent aux critères d’acceptation SDD
• Modèles de conception Python pour une architecture propre – pratiques de structure de code que le SDD aide à préserver
• Récupération vs Représentation dans la gestion des connaissances – comment les spécifications explicites se rapportent au contexte et à la récupération IA
• Documentation GitHub Spec Kit – une boîte à outils SDD open source portable
• Superpowers Quickstart : Installation, Workflow et Essai – un paquet de compétences installable qui applique automatiquement la boucle brainstorm-plan-implement-validate
• Martin Fowler sur les outils de développement piloté par spécifications – analyse prudente de Kiro, Spec Kit et Tessl