Cycle de développement par spécifications, des exigences au code

Le développement piloté par spécifications (Spec-Driven Development) fonctionne lorsque la spécification est un flux de travail, et non un document que l’on classe après la réunion de lancement. L’objectif n’est pas de produire un document de exigences produit volumineux.

L’objectif est de progresser à travers une suite d’artifacts révisables qui réduisent chacun l’ambiguïté avant que quiconque — humain ou agent IA — ne modifie le code de production.

Si vous ne savez pas ce qu’est le SDD d’un point de vue conceptuel, commencez par Qu’est-ce que le développement piloté par spécifications ? pour les définitions, les comparaisons avec les approches TDD et BDD, et le plaidoyer en faveur du traitement de la spécification comme source de vérité. Cet article du cluster de documentation Architecture applicative est le guide opérationnel. Il détaille les cinq phases, montre ce que chaque artifact doit contenir, explique où s’insèrent les agents IA et fournit des modèles réutilisables que vous pouvez copier dans votre dépôt dès aujourd’hui.

Le SDD est un flux de travail, pas un document

Le mode d’échec le plus courant dans le développement piloté par spécifications est de traiter la spécification comme une paperasse. Une équipe rédige un long document de exigences, le stocke dans un wiki, puis code à partir de sa mémoire et de fils de discussion. La spécification existe, mais elle ne pilote rien. C’est du théâtre documentaire, et c’est pire qu’une absence de spécification car cela crée une fausse confiance.

Un flux de travail SDD fonctionnel produit une chaîne d’artifacts, chacun étant révisé avant le début de la phase suivante. Les exigences réduisent l’ambiguïté produit. La conception réduit l’ambiguïté technique. Les tâches réduisent l’ambiguïté d’exécution. L’implémentation produit du code par rapport à une cible connue. La validation prouve que la chaîne a tenu. Lorsqu’une phase révèle une erreur, vous corrigez l’artifact et relancez depuis ce point — pas après que trois mille lignes de dérive sont atterries dans la branche principale.

Le flux de travail est indépendant des outils. Vous pouvez l’exécuter avec des fichiers markdown dans Git, avec GitHub Spec Kit, avec un CLI centré sur le changement plus léger comme OpenSpec, avec des plans Cursor, avec un package de compétences imposé comme Superpowers, ou avec un simple éditeur de texte et un réviseur discipliné. Ce qui compte, c’est la séquence et les points de contrôle, pas la marque de l’outil.

Phase 1 — Spécifier les exigences

La phase de spécification répond à la question de quel problème vous résolvez et à quoi ressemble l’état « terminé ». Elle évite délibérément comment le construire. Le moment où votre spécification de exigences dit « utiliser des triés de triés de Redis », vous avez cessé de spécifier et avez commencé à concevoir dans le mauvais document. Gardez l’implémentation hors des exigences. Placez-le dans le plan.

Énoncé du problème et utilisateurs

Commencez par un paragraphe qui énonce le problème en langage clair. Nommez les utilisateurs affectés et la situation qui rend le problème douloureux. Un bon énoncé du problème permet à un réviseur qui n’était pas dans la réunion de planification de décider si une solution proposée adresse réellement la douleur.

Exemple pour une fonctionnalité de limitation de débit d’API :

Les consommateurs d’API sur l’offre gratuite peuvent envoyer un nombre illimité de requêtes, ce qui provoque des pics de coûts et une impact « voisin bruyant » sur les locataires payants. Les opérateurs de la plateforme ont besoin d’une limite par clé exécutable sans intervention manuelle.

Objectifs, non-objectifs et critères d’acceptation

Les objectifs décrivent les résultats que vous livrerez. Les non-objectifs décrivent les travaux adjacents tentants que vous refuserez explicitement. Ensemble, ils encadrent la créativité de l’agent, ce qui est essentiel lorsque les outils IA « aident » autrement en étendant la portée.

Les critères d’acceptation doivent être assez précis pour que chacun corresponde à au moins un test. « Le point de terminaison est sécurisé » n’est pas un critère d’acceptation. « Les requêtes non authentifiées reçoivent HTTP 401 » l’est. Si vous ne pouvez pas écrire un critère concret, l’exigence est toujours trop vague pour être implémentée.

Questions ouvertes

Listez chaque décision qui n’est pas encore réglée. Les questions floues ne sont pas un signe d’échec. Elles sont la preuve que la phase de spécification fait son travail. Résolvez-les avant d’écrire le plan de conception, sinon vous paierez l’ambiguïté en retravail d’implémentation.

Un modèle minimal de exigences :

## Problème
[Un paragraphe : qui souffre, pourquoi, et ce qui déclenche la douleur.]

## Utilisateurs
- [Rôle utilisateur principal]
- [Rôle utilisateur secondaire]

## Objectifs
1. [Résultat mesurable]
2. [Résultat mesurable]

## Non-objectifs
- [Explicitement hors périmètre]
- [Explicitement hors périmètre]

## Critères d'acceptation
- [ ] [Comportement vérifiable]
- [ ] [Comportement vérifiable]

## Questions ouvertes
- [ ] [Question qui bloque la planification]

Phase 2 — Planifier la conception

La phase de planification traduit l’intention en décisions techniques. C’est là que les triés de triés de Redis ont leur place, ainsi que les limites de modules, les modifications de schéma, les contrats API, les étapes de migration, les contraintes de sécurité et la stratégie de test. Le plan est dérivé de la spécification des exigences et des contraintes existantes de votre projet — choix de la pile technique, registre de décisions, et conventions stockées dans des fichiers comme AGENTS.md ou une constitution du projet.

Architecture et modules affectés

Nommez les modules, services ou paquets qui seront modifiés et résumez le modèle d’intégration. Si la fonctionnalité franchit une limite de service, documentez le contrat des deux côtés. Les agents hallucinent des API lorsque les contrats sont implicites. Les rendre explicites dans le plan prévient les points de terminaison inventés et les formes de réponse erronées.

Modèle de données, contrats API et migrations

Documentez les modifications de schéma, les nouvelles tables ou champs, les exigences d’indexation et les règles de rétrocompatibilité. Pour les API HTTP, écrivez la méthode, le chemin, la forme de la requête, la forme de la réponse et les codes d’erreur. Pour les événements, écrivez les noms de sujets, les schémas de charge utile et les sémantiques de livraison. Incluez les étapes de migration et les notes de retour arrière lorsque le modèle de données change.

Sécurité, observabilité et stratégie de test

Les contraintes de sécurité appartiennent au plan, et non en après-pensée lors de la revue de code. Notez les exigences d’authentification, les règles d’autorisation, les limites de validation des entrées et les données qui ne doivent pas apparaître dans les journaux. L’observabilité doit couvrir les métriques, journaux ou traces nécessaires pour confirmer que la fonctionnalité fonctionne en production.

La stratégie de test revient aux critères d’acceptation. Identifiez quels critères nécessitent des tests unitaires, quels critères nécessitent des tests d’intégration et quels critères nécessitent une vérification manuelle. Si vous utilisez le test unitaire en Go ou le test unitaire en Python, nommez les paquets et fichiers de test que vous prévoyez d’ajouter. Un plan sans stratégie de test est un plan qui sera livré avec des lacunes que vous découvrirez en production.

Phase 3 — Découper les tâches d’implémentation

La phase de tâches décompose le plan en tranches assez petites pour être implémentées, révisées et validées indépendamment. C’est ce qui rend le développement assisté par agent révisable. Au lieu d’un diff immense, vous obtenez une séquence de modifications ciblées qui correspondent chacune à une exigence nommée.

Dimensionnement des tâches et dépendances

Une bonne touche un ensemble borné de fichiers, s’achève en une session agent et se termine par une étape de validation. Les tâches doivent déclarer explicitement leurs dépendances. Les tâches de migration s’exécutent avant le code qui lit le nouveau schéma. Les modifications de bibliothèques partagées s’exécutent avant les consommateurs. Les modifications du middleware d’authentification s’exécutent avant les points de terminaison qui dépendent du nouveau comportement.

Fichiers, validation et points de contrôle

Chaque tâche doit lister les fichiers susceptibles de changer, les critères d’acceptation qu’elle satisfait et comment valider l’achèvement. La validation peut être une commande de test, un exemple curl, ou une vérification manuelle décrite en étapes copiables. Chaque tâche se termine à un point de contrôle de revue humaine. Le réviseur confirme que le diff correspond à la description de la tâche avant que la tâche suivante ne commence.

Une entrée de tâche minimale :

### Tâche 3 — Ajouter le middleware de limitation de débit

**Dépend de :** Tâche 1 (schéma), Tâche 2 (dépôt)
**Fichiers :** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfait :** AC-2 (429 au-delà de la limite), AC-3 (en-têtes de limite dans la réponse)
**Valider :** `go test ./middleware/...` passe ; curl au-delà de la limite renvoie 429 avec Retry-After
**Point de contrôle :** Confirmer que le middleware s'exécute après l'authentification, avant le gestionnaire

Gardez à l’œil les explosions de tâches générées. Les agents IA peuvent produire des plans de cinquante tâches en quelques secondes. La plupart de ces tâches seront redondantes ou trop granulaires pour être révisées efficacement. Une liste de tâches utile pour une fonctionnalité de taille moyenne en contient souvent cinq à quinze, pas cinquante.

Phase 4 — Implémenter une tâche à la fois

L’implémentation est délibérément étroite. Choisissez une tâche, donnez à l’agent seulement le contexte dont il a besoin pour cette tâche, et arrêtez lorsque la validation passe. Les réinitialisations de contexte entre les tâches sont une fonctionnalité, pas un bug. Elles empêchent les suppositions antérieures de polluer les travaux ultérieurs et gardent les diffs révisables.

Appliquer les contraintes de la pile de spécifications

L’agent d’implémentation devrait lire la spécification des exigences, le plan de conception, la description de la tâche actuelle et les contraintes au niveau du projet. Les contraintes sont la section à plus haut rendement que la plupart des équipes ignorent. Elles disent à l’agent ce qu’il ne doit pas faire — ne pas refacter des modules non liés, ne pas modifier les signatures d’API publiques en dehors de cette fonctionnalité, ne pas introduire de nouvelles dépendances sans mettre à jour le plan.

Mettre à jour le plan lorsque la réalité diffère

L’implémentation révélera des surprises. Une bibliothèque ne prend pas en charge le comportement supposé. Une migration prend plus de temps que prévu. Un cas limite manquait aux critères d’acceptation. Lorsque cela arrive, mettez à jour la spécification avant de continuer. Corrigez les exigences ou le plan, obtenez une revue rapide, puis reprenez l’implémentation par rapport à l’artifact corrigé. Un code qui diverge silencieusement de la spécification est la façon dont la dérive devient permanente.

Phase 5 — Valider par rapport à la spécification

La validation est là que le SDD gagne son prix. Sans elle, la spécification est un exercice de planification. Avec elle, la spécification est un contrat que vous pouvez vérifier par rapport au code livré.

Vérifications automatiques

Exécutez la suite de tests complète, le lint et les vérifications de types sur CI. Intégrez-les dans votre pipeline en utilisant les motifs de l’aide-mémoire GitHub Actions si vous avez besoin d’un point de départ pratique. Les vérifications automatiques détectent les régressions. Elles ne détectent pas les mauvaises fonctionnalités construites correctement, ce pourquoi la revue des critères d’acceptation reste importante.

Critères d’acceptation et revue manuelle

Parcourez chaque critère d’acceptation de la spécification des exigences. Marquez chacun comme satisfait, échoué ou différé avec justification. La revue manuelle détecte les problèmes d’UX, les lacunes de sécurité et les mauvais comportements que les tests ont manqués parce qu’ils étaient écrits pour correspondre à une spécification défectueuse.

Diff spécification-vers-code

L’étape de validation finale compare l’implémentation par rapport au plan de conception. Les fichiers modifiés correspondaient-ils aux fichiers prévus par le plan ? Les décisions d’architecture dans le code correspondaient-elles aux décisions enregistrées ? Les fichiers inattendus dans le diff sont un signal — soit le plan était incomplet, soit l’agent a dévié. Les deux méritent une attention avant la fusion. Garder les spécifications, tests et code synchronisés dans le développement IA transforme cette revue de diff ponctuelle en une table de traçabilité répetable et un ensemble de vérifications CI, de sorte que la dérive soit détectée sur chaque PR et non seulement lorsque quelqu’un se souvient de regarder.

Où s’insèrent les agents IA dans le flux de travail

Les agents IA sont des accélérateurs sur chaque phase, pas des remplacements pour la revue. Le modèle productif est : brouillon, revue, raffinement, puis progression. Demandez à un agent de brouillonner la spécification des exigences à partir d’une description du problème, puis éditez l’intention jusqu’à ce que les objectifs, non-objectifs et critères d’acceptation soient corrects. Demandez à un agent de brouillonner le plan de conception à partir des exigences approuvées, puis révérez les décisions d’architecture avant qu’aucun code n’existe. Demandez à un agent d’implémenter une tranche de tâche à la fois, avec votre approbation de chaque diff avant que la tâche suivante ne commence.

Les agents sont particulièrement utiles pour produire des brouillons et des tests de base. Les humains sont particulièrement utiles pour détecter les mauvais objectifs, l’architecture non sécurisée et l’expansion de portée subtile. Le flux de travail échoue si l’un des deux côtés est ignoré — si les agents implémentent sans spécifications, ou si les humains écrivent des spécifications sans jamais les valider par rapport au code.

Cet article sur le flux de travail reste volontairement indépendant des outils. Les guides d’exécution spécifiques aux outils — configuration de l’éditeur, commandes en barre oblique, configuration de l’agent — appartiennent au cluster Outils de développement IA. Le pilier du processus vit ici sous les pratiques de documentation parce que les artifacts comptent plus que le fournisseur.

Erreurs courantes qui tuent le développement piloté par spécifications

Grosses spécifications avant toute validation. Un document de exigences de trente pages écrit avant un prototype ou une pointe est de la paperasse en cascade, pas du SDD. Écrivez la spécification minimale qui élimine l’ambiguïté pour la phase suivante, puis validez les suppositions tôt. Chaque fonctionnalité n’a pas besoin de la boucle complète des cinq phases — Développement piloté par spécifications vs Vibe Coding explique quand une structure plus légère suffit.

Critères d’acceptation vagues. Les adjectifs comme « rapide », « propre » et « convivial » ne sont pas des critères d’acceptation. Remplacez-les par un comportement mesurable. Si vous ne pouvez pas le tester, vous ne pouvez pas l’implémenter de manière fiable — surtout avec un agent IA.

Non-objectifs manquants. Sans non-objectifs, les agents étendent la portée par défaut. Ils ajoutent des couches de cache, refactent les modules voisins et introduisent des dépendances que vous n’avez pas demandées. Les non-objectifs sont la façon de dire non à l’avance.

Pas de plan de test dans la phase de conception. Les tests écrits seulement après l’implémentation tendent à confirmer ce qui a été construit, et non ce qui était prévu. Le plan devrait nommer quels critères d’acceptation correspondent à quels types de tests avant que le premier fichier de production ne change.

Sauter la revue aux frontières de phase. La spécification révisée avant le plan. Le plan révisé avant les tâches. Les tâches révisées avant l’implémentation. Chaque point de contrôle est bon marché. Corriger la dérive après une grande fusion est coûteux.

Laisser exploser les tâches générées. Traitez une liste de tâches générée par IA de cinquante éléments comme un premier brouillon, pas comme un calendrier. Fusionnez les éléments redondants, divisez ceux trop volumineux et supprimez les tâches qui ne correspondent pas à une exigence.

Supprimer les investigations rejetées au lieu d’enregistrer pourquoi. Lorsque la revue de la phase 2 conclut qu’une direction ne vaut pas la peine d’être construite, le réflexe est de supprimer la spécification et de passer à autre chose. Cela efface le raisonnement, et la même idée resurgit au trimestre suivant, investiguée à partir de zéro par quiconque — humain ou agent — qui la frappe à nouveau. Enregistrer le rejet avec le même rigueur qu’une décision acceptée est bon marché en comparaison ; Propositions rejetées OpenSpec : une convention de mémoire de décision détaille une façon concrète de le faire, y compris l’instruction qui fait chercher à un agent les décisions antérieures avant de re-proposer.

Le SDD fonctionne lorsque chaque phase réduit l’ambiguïté. Il échoue lorsqu’il crée de la paperasse.

Modèles réutilisables

Copiez-les dans votre dépôt et adaptez-les. Stockez les spécifications à côté de la branche fonctionnalité, révérez-les dans les pull requests et gardez-les sous contrôle de version afin que les agents et les humains lisent la même source.

Modèle de exigences

# Fonctionnalité — [nom]

## Problème
## Utilisateurs
## Objectifs
## Non-objectifs
## Critères d'acceptation
## Questions ouvertes

Modèle de conception

# Conception — [nom de la fonctionnalité]

## Résumé
## Modules affectés
## Modifications du modèle de données
## Contrats API
## Migrations
## Sécurité
## Observabilité
## Stratégie de test
## Risques et mitigations

Modèle de liste des tâches

# Tâches — [nom de la fonctionnalité]

## Tâche 1 — [titre]
Dépend de :
Fichiers :
Satisfait :
Valider :
Point de contrôle :

## Tâche 2 — [titre]
...

Liste de contrôle de validation

# Validation — [nom de la fonctionnalité]

## Automatisé
- [ ] Tous les tests passent
- [ ] Lint propre
- [ ] Vérification des types propre

## Critères d'acceptation
- [ ] AC-1 —
- [ ] AC-2 —

## Spécification-vers-code
- [ ] Les fichiers modifiés correspondent au plan
- [ ] Pas de modifications architecturales non documentées
- [ ] Spécification mise à jour si l'implémentation différait

Conclusion

Le développement piloté par spécifications ne consiste pas à écrire plus de documents. Il consiste à progresser à travers spécifier, planifier, tacher, implémenter et valider avec un point de contrôle à chaque étape. Chaque phase devrait laisser l’acteur suivant — humain ou agent — avec moins de tâtonnements que la phase précédente.

Commencez petit. Exécutez le flux de travail complet sur une fonctionnalité de taille moyenne. Gardez les artifacts en markdown dans le dépôt. Mettez à jour la spécification lorsque la réalité diverge. Validez avant la fusion. Lorsque la chaîne fonctionne, vous obtenez moins de dérive, des diffs révisables plus petits, et un enregistrement durable de l’intention qui survit aux réinitialisations de session et aux passages de main d’équipe.

Lorsque la chaîne devient de la paperasse, coupez la portée — pas la revue. Une spécification de deux pages qui a été validée bat une spécification de trente pages que personne n’a lue.

Liens utiles

• Documentation GitHub Spec Kit — boîte à outils open source qui implémente une boucle similaire de spécifier-planifier-tâcher-implémenter
• Démarrage rapide OpenSpec : installation, flux de travail et pièges courants — un CLI centré sur le changement plus léger qui exécute cette même boucle comme explorer-proposer-appliquer-archiver
• Propositions rejetées OpenSpec : une convention de mémoire de décision — enregistrer une décision de phase 2 rejetée afin qu’elle ne soit pas ré-investiguée à partir de zéro
• Démarrage rapide Superpowers : installation, flux de travail et essai — un package de compétences installable qui automatise cette même boucle des cinq phases avec des points de contrôle obligatoires
• Martin Fowler sur les outils de développement piloté par spécifications — analyse de Kiro, Spec Kit et Tessl