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

Le développement piloté par les spécifications fonctionne lorsque la spécification est un flux de travail, et non un document que l’on archive après le lancement. L’objectif n’est pas de produire un volumineux document de exigences produit.

L’objectif est de traverser une séquence d’artefacts révisables, chacun réduisant 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 (Spec-Driven Development) conceptuellement, commencez par Qu’est-ce que le développement piloté par les spécifications ? pour les définitions, les comparaisons avec le TDD et le BDD, et le cas pour traiter la spécification comme source de vérité. Cet article du cluster de documentation Architecture d’application est le guide opérationnel. Il passe en revue 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 référentiel 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 les spécifications est de traiter la spécification comme une simple paperasse. Une équipe rédige un long document d’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 dirige rien. C’est du théâtre de documentation, et c’est pire qu’aucune spécification car cela 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 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’artefact et relancez à partir de ce point — et non après que trois mille lignes de code dérivé sont arrivées dans la branche principale.

Le flux de travail est neutre en ce qui concerne les outils. Vous pouvez l’exécuter avec des fichiers Markdown dans Git, avec GitHub Spec Kit, avec des plans Cursor, ou avec un éditeur de texte brut et un relecteur discipliné. Ce qui compte, c’est la séquence et les portes d’examen, pas la marque des outils.

Phase 1 – Spécifier les exigences

La phase de spécification répond à la question du problème que vous résolvez et de ce à quoi ressemble la réussite. Elle évite délibérément comment le construire. L’instant où votre spécification d’exigences dit “utiliser les ensembles triés Redis”, vous avez cessé de spécifier et commencé à concevoir dans le mauvais document. Gardez l’implémentation hors des exigences. Mettez-la dans le plan.

Énoncé du problème et utilisateurs

Commencez par un paragraphe qui énonce le problème en langage clair. Nommez les utilisateurs concernés et la situation qui rend le problème douloureux. Un bon énoncé du problème permet à un relecteur qui n’était pas à 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 du niveau gratuit peuvent envoyer des requites illimitées, ce qui provoque des pics de coûts et un impact de 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 le travail adjacent tentant que vous ne ferez explicitement pas. Ensemble, ils bornent la créativité de l’agent, ce qui est essentiel lorsque les outils IA “aident” autrement à étendre la portée.

Les critères d’acceptation doivent être assez précis pour que chacun se mappe à 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 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. C’est la phase de spécification qui fait son travail. Résolvez-les avant d’écrire le plan de conception, sinon vous paierez pour l’ambiguïté dans le travail de réimplémentation.

Un modèle d’exigences minimal :

## 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 ici que les ensembles triés Redis ont leur place, ainsi que les limites des modules, les changements 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 d’exigences plus les contraintes existantes de votre projet — choix de stack, enregistrements 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 packages qui changeront et résumez le modèle d’intégration. Si la fonctionnalité traverse une limite de service, documentez le contrat des deux côtés. Les agents hallucinent les APIs lorsque les contrats sont implicites. Les rendre explicites dans le plan empêche les points de terminaison inventés et les formes de réponse incorrectes.

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

Documentez les changements de schéma, les nouvelles tables ou champs, les exigences d’indexation et les règles de compatibilité ascendante. Pour les APIs 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 restauration en 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, pas comme après-pensée dans la revue de code. Notez les exigences d’authentification, les règles d’autorisation, les limites de validation d’entrée et les données qui ne doivent pas apparaître dans les journaux. L’observabilité doit couvrir les métriques, les journaux ou les traces nécessaires pour confirmer que la fonctionnalité fonctionne en production.

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

Phase 3 – Décomposer les tâches d’implémentation

La phase de tâches décompose le plan en tranches suffisamment 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’une énorme diff, vous obtenez une séquence de changements ciblés qui se mapent chacun à une exigence nommée.

Dimensionnement des tâches et dépendances

Une bonne tâche touche un ensemble borné de fichiers, se complète en une session d’agent et se termine par une étape de vérification. Les tâches doivent déclarer leurs dépendances explicitement. Les tâches de migration s’exécutent avant le code qui lit le nouveau schéma. Les changements de bibliothèque partagée s’exécutent avant les consommateurs. Les changements de middleware d’authentification s’exécutent avant les points de terminaison qui dépendent du nouveau comportement.

Fichiers, validation et points de contrôle de revue

Chaque tâche devrait 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-collables. Chaque tâche se termine à un point de contrôle de revue humaine. Le relecteur confirme que la 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 retourne 429 avec Retry-After
**Point de contrôle de revue :** Confirmer que le middleware s'exécute après l'authentification, avant le gestionnaire

Méfiez-vous des 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 a souvent cinq à quinze éléments, 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 uniquement 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 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 implémentant devrait lire la spécification d’exigences, le plan de conception, la description de la tâche actuelle et les contraintes au niveau du projet. Les contraintes sont la section au ROI le plus élevé que la plupart des équipes sautent. Elles disent à l’agent ce qu’il ne doit pas faire — ne pas refactoriser les modules non liés, ne pas changer les signatures 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 fera surface des surprises. Une bibliothèque ne supporte pas le comportement supposé. Une migration prend plus de temps que prévu. Un cas extrême manquait des critères d’acceptation. Lorsque cela se produit, mettez à jour la spécification avant de continuer. Corrigez les exigences ou le plan, obtenez une revue rapide, puis reprenez l’implémentation contre l’artefact corrigé. Le code qui diverge silencieusement de la spécification est ainsi que la dérive devient permanente.

Phase 5 – Valider contre la spécification

La validation est là où le SDD gagne sa valeur. Sans elle, la spécification est un exercice de planification. Avec elle, la spécification est un contrat que vous pouvez vérifier contre le code déployé.

Vérifications automatisées

Exécutez la suite complète de tests, le lint et les vérifications de type sur CI. Intégrez-les dans votre pipeline en utilisant les motifs du guide de référence GitHub Actions si vous avez besoin d’un point de départ pratique. Les vérifications automatisées capturent les régressions. Elles ne capturent 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 d’exigences. Marquez chacun comme satisfait, échoué ou différé avec justification. La revue manuelle capture les problèmes UX, les lacunes de sécurité et les comportements incorrects que les tests ont manqués parce que les tests étaient écrits pour correspondre à une spécification défectueuse.

Diff spécification-code

L’étape finale de validation compare l’implémentation contre le plan de conception. Les fichiers qui ont changé correspondent-ils aux fichiers que le plan a prédits ? Les décisions architecturales dans le code correspondent-elles aux décisions enregistrées ? Les fichiers inattendus dans la diff sont un signal — soit le plan était incomplet, soit l’agent s’est égaré. Les deux méritent attention avant la fusion. Maintenir les spécifications, les tests et le code synchronisés dans le développement IA transforme cette revue de diff ponctuelle en un tableau de traçabilité répétable et un ensemble de vérifications CI, afin que la dérive soit capturée sur chaque PR plutôt que seulement lorsque quelqu’un se souvient de regarder.

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

Les agents IA sont des accélérateurs à chaque phase, pas des remplacements pour la revue. Le modèle productif est brouillon, revue, raffinement, puis poursuivre. Demandez à un agent de rédiger la spécification d’exigences à 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 exigences approuvées, puis révisez les décisions d’architecture avant que du code n’existe. Demandez à un agent d’implémenter une tranche de tâche à la fois, avec vous approuvant chaque diff avant que la tâche suivante ne commence.

Les agents sont particulièrement utiles pour produire des premiers brouillons et des tests boilerplate. Les humains sont particulièrement utiles pour capturer les mauvais objectifs, l’architecture non sécurisée et le dépassement de périmètre subtil. Le flux de travail échoue lorsque l’un des côtés est sauté — lorsque les agents implémentent sans spécifications, ou lorsque les humains écrivent des spécifications sans jamais les valider contre le code.

Cet article de flux de travail reste neutre en ce qui concerne les outils par intention. 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 processus vit ici sous les pratiques de documentation parce que les artefacts comptent plus que le vendeur.

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

Des spécifications énormes avant toute validation. Un document d’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 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 piloté par les spécifications vs Vibe Coding explique quand une structure plus légère est suffisante.

Des 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.

Absence de non-objectifs. Sans non-objectifs, les agents étendent le périmètre par défaut. Ils ajoutent des couches de mise en cache, refactorisent les modules voisins et introduisent des dépendances que vous n’avez pas demandées. Les non-objectifs sont comment dire non à l’avance.

Aucun plan de test dans la phase de conception. Les tests écrits seulement après l’implémentation ont tendance à confirmer ce qui a été construit, pas ce qui était intentionné. Le plan devrait nommer quels critères d’acceptation se mapent à quels types de tests avant que le premier fichier de production ne change.

Sauter la revue aux limites 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 porte est bon marché. 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 premier brouillon, pas comme un calendrier. Fusionnez les éléments redondants, divisez les éléments surdimensionnés et supprimez les tâches qui ne se mapent pas à une exigence.

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 référentiel et adaptez-les. Stockez les spécifications à côté de la branche de fonctionnalité, révisez-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 d’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
## Changements de modèle de données
## Contrats 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 type propre

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

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

Conclusion

Le développement piloté par les spécifications ne consiste pas à écrire plus de documents. Il consiste à traverser spécifier, planifier, tâche, implémenter et valider avec une porte d’examen à chaque étape. Chaque phase devrait laisser l’acteur suivant — humain ou agent — avec moins de travail de devinettes 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 référentiel. 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 transferts 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 vaut mieux qu’une spécification de trente pages que personne n’a lue.

Liens utiles

• Documentation GitHub Spec Kit – kit d’outils open-source qui implémente une boucle similaire spécifier-planifier-tâches-implémenter
• Martin Fowler sur les outils de développement piloté par les spécifications – analyse de Kiro, Spec Kit et Tessl