Spec-driven development : pourquoi l'avenir du développement logiciel est déclaratif

Dans la plupart des projets logiciels, le code finit par devenir la seule vérité fiable. Les décisions prises au départ se diluent, les règles métier s’éparpillent entre les tickets, les fils Slack et la mémoire des anciens, et chacun avance avec sa propre interprétation du produit. Tant que l’équipe est petite et le produit jeune, ça tient. Puis le produit évolue, l’équipe grandit, et les symptômes s’installent : comportements inattendus, régressions, journées entières perdues à redécouvrir des évidences que quelqu’un avait déjà tranchées deux ans plus tôt.

Le spec-driven development (SDD) attaque ce problème par un renversement simple : la spécification devient la source de vérité du projet. On décrit ce que le système doit garantir avant d’écrire le code, et ces garanties guident l’architecture, l’implémentation et les tests. La spec cesse d’être le document qu’on oublie dans un coin de Notion pour devenir un artefact opérationnel, consulté et modifié tous les jours. L’idée n’a rien de neuf, mais malheureusement, maintenir une spécification à jour a toujours coûté trop cher entre la pression du delivery et la complexité des systèmes, la doc finissait obsolète, et on revenait au code comme référence unique, même illisible. Ce qui est neuf, c’est que l’idée devient enfin tenable grâce à l’IA.

Le marché ne s’y trompe pas : en septembre 2025, GitHub publie un petit outil open source qui tient dans un CLI et quelques templates Markdown. Dix mois plus tard, Spec Kit dépasse les 106 000 étoiles sur GitHub. Pour situer : Kubernetes, douze ans d’existence, en compte 123 000. Un outil dont le seul rôle est de vous faire écrire des spécifications avant de laisser une IA coder.

Initialement, je pensais écrire cet article comme un mémo interne pour les équipes techs d’Actelo et Polara Studio. Finalement, ce mémo a dérivé en article de blog à part entière, à destination des équipes produit également 😄 (désolé les PMs, c’est un peu tech quand même! Sautez des parties 😉).

Le sujet me tient d’autant plus à cœur qu’on a payé pour apprendre, chez Polara Studio. Il y a quelques années, on a construit notre propre framework JS déclaratif sur mesure (feu BOLD, petit framework parti trop tôt), porté notamment par notre brillantissime Jason Pindat. L’intuition était la bonne : décrire l’état voulu de l’application et laisser le framework produire le comportement. Mais le projet est devenu trop complexe à maintenir, parce que le rêve d’un état déclaratif pilotant du code impératif se heurtait aux limites du code lui-même. On sentait la bonne direction, il nous manquait le compilateur.

À l’époque, on ne pouvait pas faire autrement ; maintenant qu’une IA sait transformer une intention en code, si. Et vous retrouverez ce motif partout dans cet article : tout ce que l’informatique a produit où l’on avait un besoin de clarté et fiabilité extrême ces quinze dernières années est passé au déclaratif (l’infrastructure => Terraform & consor, les schémas de données backend et base de données, les APIs REST => Graphs, …).

Reste à comprendre ce que ça change en vrai, et surtout comment le mettre en place dans une équipe sans se planter.

Le spec-driven development, c’est quoi ?

Une définition simple

Le spec-driven development (SDD) est une méthode de développement logiciel dans laquelle la spécification, rédigée en langage naturel structuré et versionnée comme du code, devient la source de vérité du produit. Le code est généré à partir de cette spec par des agents IA, puis vérifié par des humains et des tests. Quand le produit doit évoluer, on ne modifie pas d’abord le code : on modifie la spec, et le code est mis à jour pour s’y conformer.

Derrière cette définition, il existe en réalité trois niveaux d’ambition, bien décrits par Birgitta Böckeler dans son analyse publiée sur martinfowler.com. Il y a le spec-first, où la spec sert à générer le code puis part à la poubelle, comme un brouillon de prompt amélioré. Il y a le spec-anchored, où la spec vit à côté du code et se maintient à chaque évolution. Et il y a le spec-as-source, où le code n’est plus qu’un artefact compilé qu’on ne touche presque jamais, position défendue par Tessl. Dans les faits, les équipes qui pratiquent sérieusement se situent presque toutes sur le deuxième niveau, et c’est logique : personne ne régénère de zéro une application qui traîne des années de legacy. Mais ne vous trompez pas de cible pour autant : le spec-as-source est l’avenir, et c’est vers lui qu’il faut tendre chaque fois que c’est possible. La bonne stratégie n’est pas d’attendre de pouvoir y basculer toute votre grosse app d’un coup, elle n’y passera jamais entière ; c’est d’y faire entrer des sous-briques bien découpées, et surtout chaque nouvelle feature, qui peuvent vivre en spec-as-source dès leur naissance pendant que le reste du produit reste en spec-anchored.

Pourquoi maintenant ? Le retour de balancier du vibe coding

Pour comprendre d’où sort le SDD, il faut revenir à février 2025, quand Andrej Karpathy invente l’expression « vibe coding » : on décrit vaguement ce qu’on veut, on accepte tout ce que l’IA propose, on oublie que le code existe. C’est grisant, et pour un prototype du dimanche, ça marche. La grande tare du vibe coding est ailleurs : la perte complète d’ownership. Personne ne possède plus vraiment ce produit, au sens où personne n’est capable d’en répondre. Le jour où un client signale un comportement bizarre, où il faut certifier une règle de calcul, ou simplement faire évoluer une feature sans casser le reste, il n’y a plus ni auteur ni intention à interroger : juste du code que personne n’a écrit, que personne n’a relu, et dont la seule explication disponible s’est évaporée avec la conversation qui l’a produit.

Ce qui nous intéresse ici, c’est la nature du problème. Le vibe coding est fondamentalement impératif : vous donnez des ordres, un par un, dans une conversation. « Ajoute un bouton export. Non, pas là. Mets-le dans la barre d’actions. Attention, tu viens de casser le filtre par date. » Chaque instruction ne vaut que dans le contexte du moment, et ce contexte s’évapore à la fin de la session. Le produit qui en résulte est la somme de centaines de décisions dont aucune n’est écrite nulle part.

En juin 2025, Sean Grove, ingénieur chez OpenAI, donne une conférence restée célèbre, « The New Code », où il retourne le problème : le code ne représenterait que 10 à 20 % de la valeur produite par un développeur. Le reste, c’est de la communication structurée : comprendre le besoin, arbitrer, définir le comportement attendu. Sa formule a fait mouche : le code est une « projection avec perte » de la spécification. Quand vous vibe-codez, vous produisez la projection et vous jetez l’original. Le SDD propose l’inverse : conserver l’original, et régénérer la projection à volonté.

Les outils qui structurent la pratique

Trois acteurs ont installé le sujet en quelques mois, avec des philosophies assez différentes.

GitHub Spec Kit, open source, s’intègre à une trentaine d’agents (Claude Code, Copilot, Cursor, Gemini CLI…). Son workflow tient en cinq commandes : /constitution pose les principes immuables du projet, /specify rédige la spec fonctionnelle, /plan la traduit en plan technique, /tasks découpe en tâches, /implement exécute. Amazon Kiro, l’IDE spec-driven d’AWS passé en disponibilité générale en novembre 2025, génère systématiquement trois fichiers avant d’écrire la moindre ligne : requirements.md, design.md et tasks.md. Détail que j’adore : les exigences y sont rédigées au format EARS, une syntaxe de spécification née chez Rolls-Royce pour les réacteurs d’avion. On ne va pas emprunter une syntaxe à l’aéronautique par hasard : c’est un aveu que la spec devient une pièce critique du système, au même titre qu’une exigence de réacteur. Tessl, enfin, la startup de Guy Podjarny (fondateur de Snyk), a levé 125 millions de dollars sur une conviction radicale : la spec est le seul artefact qu’on maintient, le code se régénère. Leur Spec Registry propose déjà plus de 10 000 specs de librairies pour éviter aux agents d’halluciner des API.

Le point commun de ces trois outils : aucun ne vous demande d’écrire du code. Ils vous demandent d’écrire ce que le produit doit faire, dans des fichiers texte versionnés. Tous les trois ont d’ailleurs choisi le Markdown comme format, ce qui rend la migration de l’un à l’autre assez indolore.

L’infrastructure a déjà vécu exactement cette bascule

Le déclaratif a gagné partout où l’erreur coûte cher

Si vous voulez savoir où va le développement logiciel, regardez où l’infrastructure était il y a dix ans. C’est un domaine qui a résolu avant tout le monde le problème qu’on se pose aujourd’hui, pour une raison simple : quand l’infra tombe, tout tombe. La criticité ne laissait pas le choix.

Rappel express pour les non-initiés. En programmation déclarative, on décrit le résultat attendu, pas les étapes pour y parvenir. Appliqué à l’infrastructure, ça donne Terraform : au lieu d’un script qui exécute « crée un serveur, puis ouvre le port 443, puis attache le disque », vous écrivez un fichier qui affirme « il existe un serveur avec le port 443 ouvert et ce disque attaché ». Le moteur compare cet état désiré à l’état réel et calcule lui-même les opérations nécessaires. Kubernetes pousse la logique au bout : chaque objet a un champ spec (ce que vous voulez) et un champ status (ce qui existe), et des boucles de réconciliation ramènent en permanence le second vers le premier. Notez au passage le nom du champ : dans Kubernetes, l’état désiré s’appelle déjà une spec.

Ce modèle a des propriétés que l’impératif ne peut structurellement pas offrir. Rejouer la même description dix fois produit dix fois le même résultat, et toute divergence entre le décrit et le réel devient visible et corrigeable : c’est la fameuse détection de drift. Ajoutez que l’état complet du système tient dans des fichiers versionnés, revus en pull request, et vous avez le principe du GitOps formalisé par la CNCF : état désiré déclaratif, versionné dans Git, réconcilié en continu par des agents.

Selon la CNCF, 82 % des organisations interrogées font tourner Kubernetes en production en 2025, et 77 % ont adopté les principes GitOps. Plus personne ne clique dans une console pour configurer la prod d’un système sérieux. Et pour avoir co-fondé Log’in Line, notre société sœur d’infogérance cloud, je sais de quoi je parle : ceux qui ont connu le serveur mystère que personne n’ose redémarrer savent pourquoi.

Regardez bien : vos briques les plus critiques sont déjà déclaratives

Un argument m’a définitivement convaincu que le SDD n’est pas une mode : dans le développement applicatif lui-même, les endroits où on a le moins le droit à l’erreur sont déjà passés au déclaratif depuis longtemps. On ne s’en rend plus compte tellement c’est acquis.

Le schéma de votre base de données ? Déclaratif. SQL lui-même est un langage déclaratif : vous décrivez les données que vous voulez, le moteur choisit le plan d’exécution. Un ORM moderne comme Prisma présente son fichier de schéma comme la « single source of truth » du modèle de données, et en dérive les migrations. Vos API ? Le contrat OpenAPI ou le schéma GraphQL décrivent des types et des opérations, et le succès de GraphQL vient précisément de là : un contrat déclaratif partagé entre front et back, dont on dérive validation, documentation et typage. Selon le State of the API Report de Postman, 82 % des organisations se disent désormais « API-first » : le contrat d’abord, l’implémentation ensuite. Votre UI ? React a gagné la guerre des frameworks en imposant l’UI déclarative : vous décrivez à quoi doit ressembler l’interface pour un état donné, et la bibliothèque réconcilie le DOM. Le terme officiel de React pour ce mécanisme est, là encore, « reconciliation ».

Faites l’exercice sur votre propre stack : le modèle de données, le contrat d’API, l’interface et l’infrastructure sont très probablement déjà déclaratifs chez vous aussi. La seule grande zone du logiciel restée impérative, c’est la logique métier, le cœur du produit. Non qu’elle soit moins importante, au contraire : il n’existait simplement aucun compilateur capable de la prendre en entrée, jusqu’ici.

Une vieille idée qui attendait son compilateur

L’idée de générer le logiciel depuis sa description a déjà échoué au moins deux fois, et il faut le dire à ceux qui découvrent le sujet. Le Model-Driven Architecture de l’OMG, lancé en 2001, promettait de générer le code depuis des modèles UML : les modèles se sont révélés plus pénibles à écrire que le code, et les générateurs trop rigides pour la vraie vie. Le BDD façon Gherkin promettait des specs exécutables lisibles par le métier : en pratique, les scénarios sont devenus des artefacts techniques de plus, avec leur glue code à maintenir. À chaque fois, le même mur : le langage de description était soit trop pauvre pour exprimer le réel, soit aussi coûteux que le code qu’il prétendait remplacer. Notre framework BOLD, dont je vous parlais en introduction, a buté exactement là, et on était en bonne compagnie.

Ce qui a changé, c’est le compilateur. Un LLM accepte comme entrée le langage dans lequel vous pensez déjà votre produit : le français, l’anglais, structurés en Markdown. Le coût d’écriture de la description s’est effondré, et sa richesse expressive a explosé. En contrepartie, on a perdu une propriété qui était non négociable pour un compilateur : le déterminisme. La même spec ne produit pas deux fois le même code. C’est le talon d’Achille du SDD, et c’est exactement pour ça que les tests et la CI restent votre filet de sécurité déterministe. Gardez ce point en tête, on va le retrouver dans les pièges.

Les avantages concrets : ce que le déclaratif change au quotidien

Des cycles d’itération écrasés, des PM enfin autonomes

Commençons par l’avantage qui change la structure même d’une organisation produit. Dans le modèle classique, une idée de fonctionnalité traverse : rédaction d’un ticket, priorisation, sprint, développement, questions-réponses entre le dev et le PM, revue, recette. Trois semaines si tout va bien. En spec-driven, si les ingénieurs ont bien posé les garde-fous techniques (on va voir comment juste après), le PM écrit la spec produit, l’agent propose le code conforme aux contraintes, et l’ingénieur revoit. Le cycle se compte en heures. Le gain vient moins de la vitesse de frappe de l’IA que de la disparition des allers-retours de traduction entre l’intention et l’implémentation.

On a monté ce fonctionnement cet hiver sur un de nos outils internes, celui qui gère le staffing des équipes, pour le tester en conditions réelles avant d’en parler aux clients. Trois semaines après la mise en place, la majorité des pull requests ne touchaient plus que le dossier specs/, et une bonne partie venait de profils non-développeurs. La feature la plus rapide, une règle d’alerte sur les fins de mission, est passée de l’idée en réunion du lundi matin à la prod le lundi après-midi. Poussé au bout, ce modèle signifie que pour une agence comme la nôtre, le client lui-même pourrait éditer la spec produit de son application et ouvrir une pull request. L’équipe garde la revue, les garde-fous techniques restent intouchables, mais la boucle de feedback client devient quasi instantanée. Et le product management y récupère du temps de décision, au lieu de le brûler en rédaction de tickets.

Sortir de l’impératif : l’IA retrouve ses petits

Deuxième avantage, plus subtil, et à mon sens le plus sous-estimé. Quand vous travaillez à l’impératif avec un agent, chaque demande de modification vous oblige à re-décrire précisément le contexte : de quel écran on parle, de quel comportement existant, de ce qu’il ne faut surtout pas toucher. Si vous êtes vague, l’agent improvise, et il écrase volontiers un comportement que vous aviez péniblement mis au point trois sessions plus tôt, parce que rien, nulle part, ne lui disait que ce comportement était voulu. En déclaratif, vous ouvrez le fichier de spec, vous allez à la section concernée, vous modifiez trois lignes. L’agent repère le changement d’un simple git diff, il voit tout ce qui entoure ces trois lignes, et il sait que le reste est un état désiré à préserver. Il retrouve ses petits.

Il y a un symptôme que tous ceux qui bossent avec des agents reconnaîtront, développeurs comme PM : le réflexe de faire par exemple un claude --resume sur une vieille conversation pour retrouver le contexte d’une feature, parce que toutes les décisions prises vivent dans cet historique de chat et nulle part ailleurs. Le jour où la conversation est perdue, compactée ou simplement introuvable, le contexte est mort. En SDD, ce problème disparaît par construction : le contexte vit dans le dépôt, pas dans l’historique de conversation. Une nouvelle session, humaine ou pas, repart de l’état complet des décisions. C’est du context engineering résolu structurellement plutôt qu’à la main, pour reprendre le terme théorisé notamment par les équipes d’Anthropic.

Les effets secondaires sont nombreux. Un git blame sur une spec vous dit qui a décidé quoi, quand, et le message de commit vous dit pourquoi : vous tracez désormais les décisions elles-mêmes. Deux personnes peuvent travailler sur la même feature en parallèle et gérer le conflit proprement au merge des specs, là où deux sessions de prompts concurrentes se marchent dessus sans même le savoir. Et l’onboarding change de nature : un nouveau développeur, ou un nouvel agent, lit le dossier de specs et dispose de tout le contexte que, dans une équipe classique, on acquiert en six mois de réunions et d’archéologie de Slack.

Changer de techno sans réécrire le produit

Celui-ci est le plus spectaculaire sur le papier. Si la spec est la source de vérité et le code une projection, alors la stack technique devient un paramètre de compilation. Votre produit est décrit en langage naturel ; le faire exister en Next.js plutôt qu’en Rails, migrer de MongoDB vers PostgreSQL, c’est régénérer la projection vers une nouvelle cible, en réutilisant l’intégralité du travail d’analyse accumulé. Comparez avec aujourd’hui : une migration de stack est un projet de réécriture où l’essentiel de l’effort consiste à faire de l’archéologie, c’est-à-dire retrouver dans le code les règles métier que plus personne ne connaît. C’est très exactement la raison pour laquelle tant de logiciels vivent avec une dette technique paralysante : le coût de reconstitution de l’intention dépasse le coût de tout le reste.

Un bémol tout de suite : en juillet 2026, personne ne régénère un SaaS de 300 000 lignes d’un claquement de doigts, et quiconque vous vend ça vous ment. Mais la direction est la bonne, et l’asymétrie stratégique est réelle. Mon obsession de conseil, ceux qui me lisent le savent, c’est le coût de réversibilité des décisions : le choix d’une stack était une décision quasi irréversible, elle devient progressivement réversible. Ça change la manière d’arbitrer un choix technique au lancement d’un produit.

Une documentation qui ne peut plus mentir

La documentation logicielle a un défaut congénital : elle décrit le produit tel qu’il était le jour où quelqu’un a eu le courage de l’écrire. Ensuite le produit bouge et pas elle. Tout le monde le sait, personne ne la maintient, et elle finit par faire plus de mal que de bien puisqu’elle affirme des choses fausses avec assurance.

En SDD, la documentation devient un artefact dérivé, exactement comme le code. Même source, deux projections : l’une en TypeScript pour la machine, l’autre en français pour les humains. À chaque évolution de la spec, la doc utilisateur, la doc API et les notes de version se régénèrent. Elle ne peut plus diverger, puisqu’elle n’a plus d’existence indépendante. Les équipes support et les auditeurs de conformité apprécieront. Et j’ajoute un bénéfice moins évident : ça vaut aussi pour les agents. Une doc générée depuis la spec, c’est du contexte propre et à jour pour la prochaine session d’IA qui travaillera sur le produit.

La revue d’intention plutôt que la revue de diff

Dernier avantage, qui répond à une angoisse très actuelle : comment reviewer sérieusement 2 000 lignes générées en dix minutes ? On ne peut pas, et tout le monde fait semblant. La revue de code ne répond de toute façon qu’à une question, « ce code est-il correct ? ». La revue de spec répond à la question qui compte : « est-on en train de résoudre le bon problème, de la bonne manière ? ». Un diff de spec de trente lignes en français se lit en cinq minutes, se discute en commentaires de PR avec le PM, le designer, voire le client. Le diff de code, lui, reste vérifié par ce qui a toujours été fait pour ça : les tests, le typage et la CI.

Comment l’implémenter concrètement dans votre organisation

Tout ce qui précède est la théorie séduisante. Reste la vraie difficulté : installer ce fonctionnement dans une équipe sans finir noyé sous le Markdown, ce qui arrive plus souvent qu’on ne le dit.

Une spec métier n’est pas une spec technique

Une spec produit décrit un comportement observable : « un utilisateur invité ne peut pas exporter les données ; quand un export dépasse 10 000 lignes, il part en tâche de fond et l’utilisateur est notifié par email ». Elle ne dit rien, et ne doit rien dire, de la file de messages, du choix de l’ORM ou de la stratégie d’indexation. Ces décisions relèvent de la spec technique, et c’est là que vos ingénieurs doivent driver, sans négociation possible.

Sans cette séparation, l’agent prend toutes les décisions techniques implicitement, au fil de l’eau, et vous récoltez une architecture accidentelle : le pire des deux mondes, du code généré vite avec des fondations que personne n’a choisies. Les specs techniques sont vos garde-fous : le style d’architecture, le modèle de données, les invariants de sécurité, les budgets de performance, les conventions de code, les librairies autorisées. Ce sont elles qui rendent les PM autonomes en sécurité. C’est le même contrat social que l’infra a inventé avec les plateformes internes : les développeurs déploient en self-service précisément parce que l’équipe plateforme a défini le cadre dans lequel le self-service est sans danger.

En pratique, la frontière entre les deux specs est parfois floue, et c’est normal. Une limite de 10 000 lignes d’export, c’est du produit ou de la technique ? Les deux, et la bonne réponse est que la spec produit exprime la contrainte d’expérience (« l’utilisateur ne doit jamais attendre plus de dix secondes ») et la spec technique le mécanisme (« au-delà de N lignes, job asynchrone »). Quand vous hésitez sur l’endroit où écrire quelque chose, demandez-vous qui doit avoir le droit de le changer. C’est le meilleur critère de rangement que je connaisse.

Git comme table de travail commune

Où vivent les specs ? La réponse fait consensus dans toutes les équipes qui pratiquent : dans le dépôt Git, à côté du code, et surtout pas dans Notion ou Confluence. La raison est mécanique. Une spec dans Notion est un document ; une spec dans Git est un objet de collaboration outillé : elle se branche, se diffe, se revoit en pull request, se fusionne, s’annote commit par commit. Et elle voyage avec le code : le commit qui change la spec est celui qui change l’implémentation, l’historique raconte une seule histoire cohérente.

Ça implique quelque chose d’inhabituel et d’assez enthousiasmant : les PM font des pull requests. Une évolution produit devient une branche qui modifie specs/produit/exports.md, revue par un ingénieur qui vérifie la faisabilité et les cas limites, pendant que le PM revoit les PR de specs techniques qui impactent l’expérience. La revue croisée devient le lieu où produit et ingénierie négocient réellement, par écrit, avec un historique. Oui, il faudra former vos PM à Git. Bonne nouvelle : Git sans code, c’est trois commandes et une interface web, et l’investissement est rentabilisé la première semaine.

Les rôles bougent, et le taste devient la compétence reine

Dans ce fonctionnement, le PM écrit et maintient l’état désiré du produit ; l’ingénieur conçoit les garde-fous, revoit les diffs de specs et de code, et garde la main sur tout ce qui est irréversible : architecture, données, sécurité. Karpathy résume bien le basculement : la génération n’est plus le goulot d’étranglement, c’est la vérification. Le métier d’ingénieur glisse de l’écriture vers l’édition, au sens éditorial du terme.

Et c’est là qu’intervient le mot que je trouve le plus juste pour décrire la compétence de 2026 : le taste, le goût. Quand produire ne coûte plus rien, n’importe qui peut générer des features à la chaîne. Ce qui redevient rare, c’est de savoir lesquelles ne pas générer, de sentir qu’une spec est trop bavarde, ou qu’une API générée est correcte mais moche et vous coûtera cher dans deux ans. Le taste ne se délègue pas à l’agent, précisément parce que l’agent dit oui à tout ; le travail d’une spec consiste au contraire à exclure, à trancher. La qualité d’un produit spec-driven suit donc de très près la qualité du jugement des gens qui écrivent et relisent les specs. À l’embauche, je pèserais aujourd’hui ce critère plus lourd que la maîtrise de n’importe quel framework.

Et je ne suis pas le seul à radoter là-dessus. En février 2026, le sujet a occupé la tech mondiale pendant une bonne semaine, résumée avec gourmandise par Business Insider. Paul Graham a rallumé la mèche en ressortant son essai « Taste for Makers », écrit en 2002 et qui vieillit remarquablement bien, avec une phrase devenue virale : quand n’importe qui peut fabriquer n’importe quoi, le vrai différenciateur, c’est ce que vous choisissez de fabriquer. Greg Brockman, président d’OpenAI, a suivi d’un lapidaire « taste is a new core skill », et Dane Knecht, CTO de Cloudflare, en a fait son pari de l’année : en 2026, le taste est le différenciateur en ingénierie. Tout le monde n’est pas d’accord, et l’objection mérite d’être entendue : Nan Yu, head of product de Linear, rétorque que vous n’avez probablement pas meilleur goût que l’IA, et que si un modèle peut s’entraîner sur le goût, il peut l’apprendre. Peut-être. Mais même ce jour-là, il restera à décider quel goût on donne au modèle et sur quels critères on le juge.

Les pièges documentés, et comment les éviter

Le SDD a ses détracteurs, ils sont sérieux, et les ignorer serait une faute. La critique la plus reprise vient de François Zaninotto, dont l’article « The Waterfall Strikes Back » a fait un joli feu de joie sur Hacker News fin 2025. Son cas d’école : un développeur utilise Spec Kit pour afficher la date du jour dans une application, et se retrouve avec 8 fichiers et 1 300 lignes de Markdown. Un autre benchmark, mené par le CTO de Scott Logic sur une vraie feature, aboutit à 2 577 lignes de Markdown générées et 3 h 30 de revue, contre 25 minutes en approche itérative classique pour un meilleur résultat. Les critiques convergent vers quelques pièges bien identifiés, et on en a touché plusieurs du doigt nous-mêmes.

Le premier est le waterfall 2.0 : si vous figez toute la spec avant de générer quoi que ce soit, vous avez réinventé le cycle en V avec un compilateur stochastique au milieu. La parade tient en un mot, l’itération. Des specs par capacité métier, des boucles courtes ; la boucle spec → code prend des minutes, rien ne vous oblige à spécifier six mois de roadmap avant de commencer. On itère toujours, simplement sur la spec plutôt que dans un fil de conversation.

Le deuxième est la sur-spécification. D’abord celle des petites choses : afficher une date ne mérite pas 1 300 lignes de cérémonie. Le SDD se rentabilise sur la logique métier durable d’un produit qui va vivre des années, pas sur un prototype jetable ni sur un correctif de CSS. Ayez le droit, culturellement, de dire « ça, on le fait sans spec » ; un prototype du week-end se vibe-code très bien. Mais il y a une sur-spécification plus subtile, celle du niveau de détail. Traitez la qualité du modèle comme vous traiteriez celle d’un humain : si je demande à un très bon PM ou à un très bon ingénieur « fais-moi un système d’authentification », je ne m’attends pas à devoir préciser qu’il faut un système de « mot de passe oublié ». Plus le modèle est bon, plus il faut résister à l’envie de tout écrire. Une spec qui verrouille chaque détail vous prive de ses recommandations et de ses ajouts, parfois bien meilleurs que ce que vous auriez imaginé et spécifié vous-même. La bonne spec fixe les invariants et les comportements qui comptent, et laisse de l’espace au reste.

Vient ensuite le faux sentiment de sécurité. Dans le benchmark de Scott Logic, l’agent avait coché la tâche « vérifier l’implémentation » sans avoir écrit le moindre test. Ça ne nous est pas arrivé qu’aux autres : sur notre outil de staffing, le premier cycle a livré un rapport d’exécution impeccable et zéro test sur un critère d’acceptation entier. Une spec détaillée produit une illusion de rigueur qui endort la vigilance, et le non-déterminisme des LLM ne pardonne pas cette somnolence : vos critères d’acceptation doivent se matérialiser en tests exécutables, et un humain doit vérifier que ces tests existent vraiment.

Le dernier est le plus sournois : la spec qui pourrit. Le drift entre spec et code est l’équivalent du drift d’infrastructure, sauf que rien ne vous alerte. Si la spec diverge, elle redevient de la documentation morte et tout l’édifice s’effondre. La parade est surtout organisationnelle : la spec est modifiée dans la même PR que le code, sans exception, et votre boucle de travail doit rendre la mise à jour de la spec plus facile que son contournement. C’est précisément l’objet du cas pratique qui suit.

Cas pratique : votre mini-framework spec-driven en local

Voici un dispositif minimal, sans outil à installer, que vous pouvez monter en vingt minutes avec Claude Code ou n’importe quel agent capable de lire des fichiers et de lancer git. C’est volontairement artisanal : le but est de comprendre la mécanique de l’intérieur avant, éventuellement, d’adopter un outil comme Spec Kit ou Kiro.

L’arborescence :

mon-produit/
├── CLAUDE.md              ← le contrat de travail de l'agent
├── specs/
│   ├── produit/           ← specs métier, maintenues par les PM
│   │   ├── exports.md
│   │   └── facturation.md
│   └── technique/         ← garde-fous, maintenus par les ingénieurs
│       ├── architecture.md
│       └── conventions.md
├── src/                   ← le code, artefact généré
└── docs/                  ← la documentation, artefact dérivé

Et le CLAUDE.md, qui contient le mini-framework. C’est lui qui transforme un agent générique en moteur de réconciliation :

# Fonctionnement spec-driven de ce projet

## Sources de vérité
- `specs/produit/` décrit le comportement attendu du produit. Autorité : PM.
- `specs/technique/` décrit l'architecture, les conventions et les
  invariants (sécurité, perf, stack). Autorité : ingénieurs.
- `src/` et `docs/` sont des artefacts DÉRIVÉS des specs.
  Ils ne sont jamais modifiés directement sans mise à jour de spec.

## Règles
1. En cas de conflit entre une spec produit et une spec technique,
   la spec technique gagne. Signale le conflit au lieu de l'arbitrer.
2. Si une demande n'est couverte par aucune spec, ne code pas :
   propose d'abord le diff de spec correspondant.
3. Chaque critère d'acceptation d'une spec produit doit avoir
   un test automatisé correspondant. Pas de test, pas de feature.
4. Après chaque implémentation, régénère les sections de `docs/`
   impactées par les specs modifiées.

## Commande « mets à jour le produit »
Quand on te dit « mets à jour le produit » :
1. Lance `git diff HEAD -- specs/` (et `git log` si besoin) pour
   identifier tout changement de specs depuis le dernier commit.
2. Liste les changements détectés et leur impact prévu sur `src/`
   et `docs/`, et présente ce plan avant d'agir.
3. Applique les changements dans `src/`, en préservant tout
   comportement couvert par une spec non modifiée.
4. Écris ou adapte les tests correspondant aux critères modifiés.
5. Régénère les parties de `docs/` concernées.
6. Termine par un rapport : specs traitées, fichiers modifiés,
   tests ajoutés, points d'ambiguïté à trancher par un humain.

La boucle de travail est simple. Le PM (ou vous) éditez specs/produit/exports.md pour changer une règle métier. Vous dites « mets à jour le produit ». L’agent fait son git diff, voit que trois lignes ont changé dans la section exports, présente son plan, implémente, teste, régénère la doc, et vous rend un rapport. Vous relisez, vous commitez le tout : spec, code, tests et doc dans le même commit. L’état désiré et l’état réel se réconcilient à chaque cycle, exactement comme un terraform apply.

La règle n° 2 mérite un mot, c’est la plus importante des quatre : quand on demande quelque chose qui n’est couvert par aucune spec, l’agent refuse de coder et propose d’abord un diff de spec. C’est elle qui empêche le système de retomber dans l’impératif par la petite porte, un prompt pressé à la fois, et qui garde la spec plus facile à maintenir qu’à contourner.

Testez sur un vrai petit projet, un outil interne ou un module isolé de votre produit par exemple. Deux ou trois cycles suffisent pour ressentir la différence avec le prompt-par-prompt, en particulier la première fois que vous modifiez une spec écrite trois semaines plus tôt et que l’agent retrouve tout le contexte sans une ligne d’explication.

Alors, on s’y met ?

L’histoire récente de l’informatique montre un motif constant : dès qu’un domaine devient critique, il passe au déclaratif, parce que décrire un état désiré et laisser un moteur réconcilier est plus fiable que d’empiler des ordres. L’infra l’a fait avec Terraform et Kubernetes, les données avec SQL et les schémas, les API avec OpenAPI et GraphQL, l’UI avec React. La logique métier était la dernière zone impérative, faute de compilateur capable de comprendre une intention humaine. Ce compilateur existe désormais, imparfait et non déterministe, mais réel, et le SDD est simplement la discipline qui l’exploite proprement : specs versionnées comme source de vérité, garde-fous techniques posés par les ingénieurs, tests comme juge de paix, et un « taste » humain qui tranche.

Je ne vous pousse pas à tout miser dessus dès demain, et méfiez-vous de quiconque vous le vend ainsi. Commencez petit, sur un périmètre qui va durer, avec des specs courtes et des boucles rapides. Mais commencez, parce que la direction ne fait plus beaucoup de doute : dans cinq ans, réécrire l’intention de votre produit à chaque session d’IA paraîtra aussi baroque que configurer un serveur de prod à la main dans une console.

Chez Polara Studio, on construit des SaaS sur mesure depuis dix ans, et on intègre ces pratiques dans notre façon de travailler en agence de développement logiciel, avec ce que ça implique de garde-fous, de revue et de bon sens d’ingénieur. Si vous voulez explorer ce que le spec-driven peut changer pour votre produit ou votre prochain MVP, venez en discuter avec nous.