Le Spec-Driven Development (SDD) : de la spécification au code avec l'IA

Si vous laissez un agent de code générer du logiciel à partir d'une simple phrase dans votre terminal, vous faites du vibe coding. C'est amusant pour les prototypes du week-end, mais c'est une catastrophe pour les projets d'entreprise. Vous obtenez un code qui semble fonctionner au premier regard, mais qui dissimule des régressions, des choix d'architecture incohérents et une dette technique que personne ne sait déboguer.

Pour que l'intelligence artificielle devienne un accélérateur fiable, nous devons lui imposer un cadre. C'est le principe du Spec-Driven Development (SDD) : la spécification n'est plus un document passif que l'on oublie dans un wiki, elle devient le contrat vivant qui guide l'implémentation et les tests de bout en bout.

Voici comment cette démarche structure le travail quotidien des développeurs et comment l'IA permet de l'automatiser.

Le principe du SDD : la spécification comme contrat

Le Spec-Driven Development inverse le rapport traditionnel entre la conception et l'écriture du code. Dans cette approche, la spécification formalisée (exigences métiers, critères d'acceptation, invariants du système) est l'artefact central. Elle est versionnée dans le même dépôt que le code et sert de référence unique.

GitHub le résume ainsi : "In this new world, maintaining software means evolving specifications. The lingua franca of development moves to a higher level, and code is the last-mile approach."

Cette méthodologie s'organise autour de trois niveaux de maturité, formalisés par Birgitta Böckeler (Thoughtworks) :

• Le niveau spec-first : On rédige une spécification claire avant d'écrire la moindre ligne de code, et on l'utilise pour guider l'outil de développement.
• Le niveau spec-anchored : La spécification est maintenue à jour après chaque livraison. Elle évolue au même rythme que le code pour rester la référence fonctionnelle du système.
• Le niveau spec-as-source : C'est l'objectif ultime de l'automatisation. L'humain n'édite que la spécification, et l'environnement de développement génère et compile automatiquement le code et les tests correspondants.

SDD, BDD et PDD : quelles différences ?

Il ne faut pas confondre le SDD avec des approches voisines :

• SDD vs BDD (Behavior-Driven Development) : Le BDD se concentre sur la description des comportements attendus à travers des scénarios de test (comme la syntaxe Given, When, Then). Le SDD est plus large : il englobe les exigences, les contraintes architecturales, le découpage des tâches et la validation globale. Le BDD est un excellent moyen d'exécuter la phase de test d'un projet SDD.
• SDD vs PDD (Prompt-Driven Development) : Le PDD consiste à interagir directement avec l'IA en ajustant les prompts au fil de l'eau. C'est une méthode itérative mais volatile, car le prompt est éphémère. Le SDD utilise les prompts comme un moyen d'exécution, mais garde la spécification écrite comme seule source de vérité durable.

Les fondamentaux de la spécification humaine

L'arrivée des agents de code ne dispense pas le développeur de réfléchir. Bien au contraire, le rôle de l'humain se déplace de l'écriture syntaxique vers la modélisation et la définition des règles.

Pour bien piloter un projet en SDD, vous devez maîtriser trois étapes fondamentales :

Clarifier le quoi avant le comment

Une bonne spécification décrit ce que le système doit garantir et non comment il doit le faire. Vous devez formaliser les critères d'acceptation précis : quels sont les cas nominaux ? Comment le système doit-il réagir face à des entrées invalides ? Quels sont les invariants métiers à protéger ?

Lever les hypothèses dès le départ

L'erreur la plus courante est de laisser l'agent de code deviner les exigences implicites. Avant de commencer à coder, listez explicitement vos hypothèses : la base de données ciblée, la gestion des sessions, ou les contraintes de performance. Si vous ne cadrez pas ces aspects, l'agent fera des choix par défaut qui risquent de casser votre architecture existante.

Le Spec-Kit de GitHub formalise cette pratique avec le concept de constitution : un fichier constitution.md versionnés dans le dépô (dans le dossier .specify/memory/), qui fixe les principes non-négociables du projet (standards de code, choix d'architecture, règles de sécurité, contraintes de test). Il est généré et mis à jour via la commande /speckit.constitution, et sert de référence que les phases suivantes du workflow doivent respecter.

Définir les frontières de sécurité

La spécification doit inclure des limites claires. Déterminez ce que l'agent a le droit de faire de manière autonome (créer des fichiers de tests, exécuter des scripts de build) et ce qui requiert une validation humaine explicite (modifier le schéma de la base de données, ajouter une dépendance externe).

L'application moderne du SDD avec l'IA

Désormais, la spécification est devenue un artefact opérationnel interprété par les environnements de développement. Le cycle de développement s'organise autour d'un workflow structuré et validé par l'humain à chaque étape.

Le cycle Specify, Plan, Tasks, Implement

Le Spec-Kit de GitHub (dépôt github/spec-kit) et des outils comme Kiro (l'IDE/CLI agentique d'AWS) structurent le travail en plusieurs phases séquentielles. Le principe est un workflow en grille : on ne passe à la phase suivante qu'après validation humaine de la phase courante.

• Constitution (Les principes) : avant même la première spécification, un fichier constitution.md fixe les règles non négociables du projet — qualité de code, standards de test, contraintes de performance et de sécurité.
• Specify (Les exigences) : l'intention fonctionnelle traduite en exigences métiers et critères d'acceptation vérifiables. On documente le contexte, les cas d'usage et les contraintes.
• Clarify (La clarification) : une passe de questions structurées qui lève les zones d'ambiguïté avant de passer à la conception technique — une étape que Spec-Kit recommande explicitement pour éviter les reprises coûteuses en aval.
• Plan (La conception technique) : la traduction des exigences en choix techniques (modèles de données, contrats d'API, architecture des composants, choix de bibliothèques).
• Tasks (Le plan d'action) : le découpage du design en tâches individuelles et exécutables, chacune traçable et associée à un critère de validation.
• Implement (L'exécution) : l'agent exécute les tâches une par une, en restant ancré aux contraintes définies dans les phases précédentes.

Ce découpage résout un problème concret de l'IA générative : la fenêtre de contexte. En décomposant un projet en tâches atomiques et ciblées, chaque appel à l'agent reste focalisé, ce qui réduit les erreurs d'hallucination et les dérives architecturales.

Spec-Kit (GitHub) et le sdd-skill (Spillwave)

Le Spec-Kit est publié par GitHub sous forme de dépôt open-source (github/spec-kit). Il est agnostique de l'agent IA : il fonctionne indifféremment avec des dizaines d'agents harness, dont GitHub Copilot, Claude Code, Antigravity CLI ou Cursor. Il définit la méthodologie et les templates, les outils IA l'exécutent.

Spillwave a développé par-dessus le Spec-Kit un skill Claude Code (sdd-skill), qui guide directement les phases du workflow Spec-Kit à l'intérieur de Claude Code. C'est une couche d'automatisation et de guidage, pas un remplacement de la méthodologie.

La CLI specify permet d'initialiser et de piloter un projet SDD depuis le terminal :

Kiro, l'IDE agentique d'AWS

Kiro est un environnement de développement créé par AWS qui intègre le SDD nativement. Chaque spécification suit un workflow à trois phases : Requirements (les user stories et critères d'acceptation), Design (l'architecture technique et les diagrammes de séquence), puis Tasks (le plan d'implémentation détaillé, découpé en tâches traçables individuellement). Kiro propose deux variantes pour la première phase : Requirements-First pour partir des besoins, ou Design-First pour partir directement de l'architecture. Il y a aussi un mode Quick Plan qui génère les trois artefacts sans porte de validation intermédiaire, pour les fonctionnalités déjà bien comprises. Enfin, les Bugfix Specs permettent de diagnostiquer et corriger un bug avec précision, via un fichier bugfix.md qui documente le comportement actuel, le comportement attendu, et ce qui ne doit surtout pas changer, afin d'éviter toute régression.

Kiro sait aussi exécuter les tâches indépendantes d'une spécification en parallèle : il construit un graphe de dépendances à partir de tasks.md, regroupe les tâches sans dépendance mutuelle qui s'exécutent simultanément dans des contextes isolés, puis enchaîne les batchs suivantes une fois les précédentes terminées. Sur des spécifications comportant au moins quatre tâches indépendantes, ce mécanisme peut réduire le temps d'exécution jusqu'à 4 fois, sans configuration supplémentaire.

Exemple concret : créer une API de vote

Prenons l'exemple de la création d'une API REST simple pour gérer des sondages.

Étape A : Requirements (requirements.md)

On définit l'objectif fonctionnel : permettre la création d'un sondage avec plusieurs options, enregistrer des votes et consulter les résultats.

Les exigences de validation sont explicites :

• Un sondage doit avoir au minimum deux options de réponse.
• La question ne doit pas être vide.
• Si le sondage demandé n'existe pas, l'API doit renvoyer une erreur explicite.

Étape B : Design (design.md)

Le design technique traduit ces exigences pour notre pile technologique (FastAPI en Python) :

• Les sondages sont représentés par un modèle de données avec un identifiant unique, une question et une liste d'options.
• Un endpoint POST /polls accepte la question et les options, effectue les validations et retourne le sondage créé.
• Un stockage en mémoire est retenu pour cette version.

Étape C : Tasks (tasks.md)

Le plan d'action décrit les étapes d'implémentation, sous forme de tâches discrètes et traçables, chacune avec un statut suivi en temps réel. L'une de ces tâches consiste à écrire les tests de conformité avant le code de l'endpoint, pour valider les exigences dès leur implémentation :

Une fois les tâches générées, l'agent les exécute une par une pour faire passer les tests. Si le code dévie du design ou des exigences, les tests échouent immédiatement, forçant l'agent à corriger sa trajectoire.

Conclusion

Le Spec-Driven Development n'est pas une contrainte supplémentaire sur le développeur : c'est ce qui permet de travailler avec des agents en autonomie sans perdre le contrôle de l'architecture. En formalisant vos exigences dans des spécifications vivantes et versionnées, vous délimitez un périmètre sécurisé dans lequel l'IA peut accélérer l'exécution sans dériver. Vous continuez à prendre toutes les décisions importantes, l'agent les applique.

Sources et références officielles

• GitHub Spec-Kit (dépôt officiel) : github/spec-kit
• Skill Claude Code Spec-Kit (Spillwave Solutions) : SpillwaveSolutions/sdd-skill
• Documentation Kiro (IDE AWS) : kiro.dev/docs
• Skill SDD (Addy Osmani) : addyosmani/agent-skills
• Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (Birgitta Böckeler, Thoughtworks) : martinfowler.com