Spec-driven development : l'IA réhabilite la spec

Pourquoi la spec revient sur la table

Un assistant de code, c'est une zone de saisie et pas grand-chose d'autre. Pas de menus, pas de structure imposée. Comment s'assurer que le code produit répond au besoin ? La réponse qui s'est imposée depuis 2025 : écrire une spec avant de laisser l'agent coder.

Ce mouvement porte un nom, le spec-driven development (SDD). Birgitta Böckeler, Distinguished Engineer chez Thoughtworks, en donne une définition opérationnelle : écrire une spec avant d'écrire du code avec l'IA, la spec devenant la source de vérité pour l'humain et pour l'agent (martinfowler.com).

GitHub, AWS avec Kiro, Tessl ou encore la méthode BMad proposent tous des outils pour ça. Le principe est simple : un prompt initial, quelques instructions, et le LLM génère des specs produit, un plan d'implémentation et une liste de tâches. Chaque document dépend du précédent. L'humain édite, l'agent code.

Trois niveaux de SDD, à ne pas confondre

Tous les outils qui se réclament du SDD ne visent pas la même chose. Böckeler distingue trois niveaux (martinfowler.com) :

• Spec-first : une spec soignée est écrite avant la tâche, puis utilisée dans le flux de développement assisté par IA.
• Spec-anchored : la spec est conservée après la tâche, pour faire évoluer et maintenir la fonctionnalité.
• Spec-as-source : la spec est le fichier principal dans le temps ; l'humain ne touche jamais au code.

Tous les outils sont au moins spec-first. Peu assument le spec-anchored, encore moins le spec-as-source. C'est un point à vérifier avant d'adopter un outil : que devient la spec dans six mois, quand le code aura bougé ?

Autre distinction utile : la spec n'est pas le memory bank. Le memory bank, ce sont les fichiers de contexte valables pour toutes les sessions (règles, description du produit, architecture). La spec, elle, ne concerne que la fonctionnalité en cours de création ou de modification.

Le piège : le Markdown qui enterre l'agilité

François Zaninotto, chez Marmelab, a testé le SDD et son verdict est tranchant : « Spec-Driven Development (SDD) revives the old idea of heavy documentation before coding — an echo of the Waterfall era » (marmelab.com).

Son exemple est parlant. Avec GitHub spec-kit, une fonctionnalité simple — afficher la date du jour dans une app de suivi de temps — a produit 8 fichiers et 1 300 lignes de texte. Avec Kiro, l'ajout d'un champ « referred by » à des contacts a généré trois documents : requirements, design, tasks.

Les problèmes qu'il liste :

• Context blindness : l'agent découvre le contexte par recherche textuelle et rate des fonctions existantes à mettre à jour.
• Markdown madness : trop de texte, surtout en phase de design ; on lit au lieu de penser.
• Bureaucratie systématique : répétitions, cas limites imaginaires, raffinements inutiles.
• Faux agile : les « user stories » générées n'en sont pas. « As a system administrator, I want the referred by relationship to be stored in the database » n'est pas une user story.
• Double revue de code : la spec technique contient déjà du code, qu'il faut relire avant de relire l'implémentation finale.
• Rendements décroissants : le SDD brille sur un projet neuf, mais décroche dès que la base de code grossit.

Zaninotto résume : « spending 80% of your time reading instead of thinking ». Le SDD, dans sa version lourde, refait l'erreur du Big Design Up Front.

À quoi ressemble une spec qui tient debout

Une spec utile n'est pas un document de 40 pages. C'est un artefact structuré, orienté comportement, écrit en langage naturel, qui exprime une fonctionnalité et guide l'agent (martinfowler.com). Trois éléments suffisent.

Le contrat de comportement

Ce que le module, la fonction ou l'endpoint doit faire. Préconditions, postconditions, invariants. Types d'entrée, de sortie, d'erreur. Pas d'ambiguïté.

Le catalogue des cas limites

Que se passe-t-il si l'entrée est nulle ? Vide ? De taille maximale ? Négative ? Unicode ? En concurrence ? La méthode VSDD propose de poser ces questions explicitement à l'agent pour qu'il soit exhaustif (gist.github.com).

Les critères d'acceptation

Au format GIVEN… WHEN… THEN…. C'est ce que Kiro produit dans son document de requirements, chaque requirement étant une user story avec ses critères (martinfowler.com). Ces critères servent deux fois : à l'agent pour générer le code, à l'équipe pour vérifier que le code fait ce qui était demandé.

Le point clé : la spec doit être vérifiable. Si vous ne pouvez pas écrire un test ou un critère d'acceptation qui la valide, elle est trop vague.

Relier spec, user stories et backlog

Une spec qui vit dans un fichier isolé ne sert à rien. Elle doit s'ancrer dans le backlog, au même endroit que les user stories et leurs critères d'acceptation.

Le framework AI SDLC Scaffold propose une structure de dossiers qui matérialise ce lien : un dossier 1-spec/ avec des sous-dossiers goals/, user-stories/, requirements/, assumptions/, constraints/, chacun avec son template (github.com). Chaque artefact a un identifiant (US-, REQ-, ASM-, CON-) et vit dans le dépôt, versionné avec le code.

Concrètement, dans un outil de gestion de projet agile :

1. Une user story dans le backlog avec sa priorité et ses points.
2. Ses critères d'acceptation au format GIVEN/WHEN/THEN, dans la description ou en checklist.
3. La spec courte rattachée à la story : contrat, cas limites, contraintes non fonctionnelles.
4. Le lien vers le code généré, pour garder la traçabilité.

Ce fonctionnement s'intègre naturellement dans un tableau Kanban avec colonnes personnalisables, checklists et journal d'activité. Par exemple, dans Ever Earlier, une user story peut porter ses critères d'acceptation en checklist et sa spec en pièce jointe ou en commentaire épinglé, ce qui évite de maintenir un dossier Markdown séparé qui se désynchronise du backlog.

L'important n'est pas l'outil. C'est que la spec reste vivante : mise à jour quand la story évolue, archivée quand elle est livrée, jamais laissée à pourrir dans un coin.

Une méthode en cinq étapes

Voici une méthode concrète pour des specs courtes qui génèrent du code correct.

1. Partir de l'intention, pas du code. Décrivez la fonctionnalité en trois phrases. Si vous ne pouvez pas, c'est que le besoin n'est pas clair.
2. Écrire la user story et ses critères d'acceptation. Format « En tant que… je veux… afin de… » pour la story, GIVEN/WHEN/THEN pour les critères. Trois à cinq critères maximum.
3. Ajouter le contrat de comportement et les cas limites. Une demi-page suffit. Listez explicitement les entrées dégénérées.
4. Faire générer le code par l'agent, puis relire. La spec guide, elle ne garantit rien. Böckeler cite GitHub : « Crucially, your role isn't just to steer. It's to verify. » (martinfowler.com)
5. Mettre à jour la spec après livraison. Si le code a divergé, la spec doit le refléter. Sinon, elle devient un mensonge documenté.

Un point de vigilance : les agents ne suivent pas toujours la spec. Zaninotto raconte qu'un agent a marqué la tâche « verify implementation » comme faite sans écrire un seul test unitaire, en rédigeant à la place des instructions de test manuel (marmelab.com). La vérification humaine reste non négociable.

Ce que le SDD ne résout pas

Le SDD n'est pas une baguette magique. Trois limites à garder en tête.

La qualité des données d'entraînement. Une étude de Penn State et Oregon State University, publiée dans Media Psychology, montre que la plupart des utilisateurs ne détectent pas un biais systématique dans les données d'entraînement d'un système d'IA, même quand il est visible (psu.edu). Sur 769 participants répartis en trois expériences, la majorité n'a pas remarqué que les visages heureux étaient majoritairement blancs et les visages tristes majoritairement noirs. Autrement dit : une spec bien écrite ne protège pas d'un modèle biaisé.

Le contexte existant. Le SDD brille sur un projet neuf. Sur une base de code mature, les specs ratent le contexte et ralentissent le développement. Zaninotto le dit sans détour : « For large existing codebases, SDD is mostly unusable. »

La maintenance de la spec. Qui met à jour la spec quand le code évolue ? Si la réponse est « personne », le SDD devient une couche de documentation morte. Böckeler note que la stratégie de maintenance est souvent laissée vague par les outils (martinfowler.com).

La conclusion raisonnable : garder le meilleur du SDD — la spec comme contrat vérifiable — sans en reprendre la lourdeur documentaire. Des specs courtes, ancrées dans le backlog, reliées aux user stories et à leurs critères d'acceptation. Le reste, c'est du Markdown qui ne sert personne.