Flux de travail de développement dirigé par les spécifications : des exigences au code

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

L’objectif est de progresser à travers une série d’artefacts révisables, où chacun réduit 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 conceptuellement, commencez par Qu’est-ce que le développement spécifié par spécification ? pour les définitions, les comparaisons avec les approches TDD et BDD, et les arguments en faveur du traitement de la spécification comme source de vérité. Cet article du cluster de documentation Architecture d’application est le guide opérationnel. Il détaille les cinq phases, montre ce que chaque artefact 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 de défaillance le plus courant dans le développement spécifié par spécification est de traiter la spécification comme une formalité administrative. Une équipe rédige un long document de requirements, le stocke dans un wiki, puis code à partir de la mémoire et des fils de discussion. La spécification existe, mais elle ne pilote rien. C’est du théâtre documentaire, et c’est pire que l’absence de spécification car elle crée une fausse confiance.

Un flux de travail SDD fonctionnel produit une chaîne d’artefacts, chacun étant révisé avant le début de la phase suivante. Les requirements 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’artefact et relancez à partir de ce point — et non après que trois mille lignes de dérive aient atterri sur la branche principale.

Le flux de travail est neutre en matière d’outils. Vous pouvez l’exécuter avec des fichiers Markdown dans Git, avec GitHub Spec Kit, 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 de révision, et non la marque des outils.

Phase 1 — Spécifier les requirements

La phase de spécification répond à la question : quel problème résolvez-vous et à quoi ressemble l’état « terminé » ? Elle évite délibérément la question de la façon de le construire. Dès que votre spécification de requirements dit « utiliser des ensembles triés Redis », vous avez cessé de spécifier et commencé à concevoir dans le mauvais document. Gardez l’implémentation hors des requirements. Placez-la dans le plan.

Énoncé du problème et utilisateurs

Commencez par un paragraphe qui énonce le problème en langage simple. Nommez les utilisateurs concernés et la situation qui rend le problème pénible. Un bon énoncé de problème permet à un réviseur qui n’était pas présent à la réunion de planification de déterminer 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 le forfait gratuit peuvent envoyer un nombre illimité de requêtes, ce qui provoque des pics de coûts et un impact de type « voisin bruyant » sur les locataires payants. Les opérateurs de 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 ne ferez pas explicitement. Ensemble, ils bornent la créativité de l’agent, ce qui est essentiel lorsque les outils IA « aident » autrement en étendant le périmètre.

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

Questions ouvertes

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

Un modèle minimal de requirements :

## Problème
[Un paragraphe : qui souffre, pourquoi, et quel est le déclencheur de 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 ici que les ensembles triés Redis ont leur place, ainsi que les limites de modules, les changements de schéma, les contrats d’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 de requirements et des contraintes existantes de votre projet — choix de pile, registres de décision et conventions stockées dans des fichiers comme AGENTS.md ou une constitution de projet.

Architecture et modules affectés

Nommez les modules, services ou paquets qui changeront et résumez le motif d’intégration. Si la fonctionnalité traverse 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 d’accès inventés et les formes de réponse erronées.

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

Documentez les changements 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 dans 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 renvoie 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 lesquels 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, revues et validées indépendamment. C’est ce qui rend le développement assisté par agent révisable. Au lieu d’une énorme différence (diff), vous obtenez une séquence de modifications ciblées qui renvoient chacune à une requirement nommée.

Dimensionnement des tâches et dépendances

Une bonne touche un ensemble borné de fichiers, s’achève en une session d’agent et se termine par une étape de vérification. 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 d’accès qui dépendent du nouveau comportement.

Fichiers, validation et points de contrôle de revue

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 :** CA-2 (429 au-delà de la limite), CA-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 de revue :** 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 revues efficacement. Une liste de tâches utile pour une fonctionnalité de taille moyenne comporte souvent cinq à quinze éléments, et non 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 uniquement le contexte dont il a besoin pour cette tâche, et arrêtez-vous lorsque la validation passe. Les réinitialisations de contexte entre les tâches sont une fonctionnalité, pas un bug. Elles empêchent les hypothèses antérieures de polluer le travail ultérieur et gardent les diffs révisables.

Appliquer les contraintes de la pile de spécifications

L’agent d’implémentation doit lire la spécification de requirements, 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 refactoriser des modules non liés, ne pas changer les signatures d’API publiques hors 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 fera surface 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 se produit, mettez à jour la spécification avant de continuer. Corrigez les requirements ou le plan, obtenez une revue rapide, puis reprenez l’implémentation par rapport à l’artefact corrigé. Le 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 se paie. 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 automatisées

Exécutez la suite de tests complète, le lint et les vérifications de types sur CI. Intégrez-les à votre pipeline en utilisant les motifs de la fiche triche GitHub Actions si vous avez besoin d’un point de départ pratique. Les vérifications automatisées détectent les régressions. Elles ne détectent pas les mauvaises fonctionnalités construites correctement, c’est 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 de requirements. Marquez chacun comme satisfait, échoué ou différé avec justification. La revue manuelle détecte les problèmes d’expérience utilisateur, les failles de sécurité et les comportements erronés que les tests ont manqués parce qu’ils ont été écrits pour correspondre à une spécification défectueuse.

Diff spécification-vers-code

L’étape finale de validation compare l’implémentation au plan de conception. Les fichiers modifiés correspondaient-ils aux fichiers prédits par le plan ? Les décisions d’architecture dans le code correspondaient-elles aux décisions enregistrées ? Des fichiers inattendus dans le diff sont un signal — soit le plan était incomplet, soit l’agent s’est égaré. Les deux méritent attention avant la fusion. Garder les spécifications, les tests et le code synchronisés dans le développement IA transforme cette revue de diff ponctuelle en une table de traçabilité réutilisable et un ensemble de vérifications CI, afin que la dérive soit détectée à 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 à chaque phase, pas des remplaçants pour la revue. Le motif productif est : brouillon, revue, raffinement, puis progression. Demandez à un agent de rédiger la spécification de requirements à partir d’une description de problème, puis éditez l’intention jusqu’à ce que les objectifs, non-objectifs et critères d’acceptation soient corrects. Demandez à un agent de rédiger le plan de conception à partir des requirements approuvées, puis réviser les décisions d’architecture avant qu’aucun code n’existe. Demandez à un agent d’implémenter une tranche de tâche à la fois, en approuvant 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ûre et l’extension subtile du périmètre. Le flux de travail échoue lorsque l’un des deux côtés est ignoré — lorsque les agents implémentent sans spécifications, ou lorsque les humains écrivent des spécifications sans jamais les valider par rapport au code.

Cet article sur le flux de travail reste neutre en matière d’outils délibérément. Les guides d’exécution spécifiques aux outils — configuration de l’éditeur, commandes slash, configuration de l’agent — appartiennent au cluster Outils de développement IA. Le pilier du processus vit ici sous les pratiques de documentation car les artefacts comptent plus que le fournisseur.

Erreurs courantes qui tuent le développement spécifié par spécification

Énormes spécifications avant toute validation. Un document de requirements de trente pages écrit avant un prototype ou une exploration est une paperasse en cascade, pas du SDD. Écrivez la spécification minimale qui retire l’ambiguïté pour la phase suivante, puis validez les hypothèses tôt. Chaque fonctionnalité n’a pas besoin de la boucle complète des cinq phases — Développement spécifié par spécification 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 le périmètre par défaut. Ils ajoutent des couches de mise en cache, refactorisent des 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 doit nommer quels critères d’acceptation correspondent à quels types de tests avant que le premier fichier de production ne change.

Ignorer la revue aux frontières de phase. La spécification revue avant le plan. Le plan revu avant les tâches. Les tâches revues avant l’implémentation. Chaque point de contrôle est peu coûteux. Corriger la dérive après une grande fusion est coûteux.

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

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 de fonctionnalité, révélez-les dans les demandes de tirage (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 requirements

# 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
## Changements de modèle de données
## Contrats d'API
## Migrations
## Sécurité
## Observabilité
## Stratégie de test
## Risques et atténuations

Modèle de liste de tâches

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

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

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

Liste de contrôle de validation

# Validation -- [nom de la fonctionnalité]

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

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

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

Conclusion

Le développement spécifié par spécification 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 de revue à chaque étape. Chaque phase devrait laisser à l’acteur suivant — humain ou agent — moins de conjectures que la phase précédente.

Commencez petit. Exécutez le flux de travail complet sur une fonctionnalité de taille moyenne. Gardez les artefacts 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 transitions d’équipe.

Lorsque la chaîne devient de la paperasse, réduisez le périmètre — 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 spécifier-planifier-tâches-implémenter
• Superpowers Quickstart : 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 de revue obligatoires
• Martin Fowler sur les outils de développement spécifié par spécification — analyse de Kiro, Spec Kit et Tessl