Workflow 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 classe après le lancement. L’objectif n’est pas de produire un vaste 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 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 parcourt 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 en développement piloté par les spécifications est de traiter la spécification comme une paperasse. Une équipe rédige un long document d’exigences, le stocke dans un wiki, puis code à partir de mémoire et de fils de discussion. La spécification existe, mais elle ne conduit à rien. C’est du théâtre de documentation, et c’est pire que l’absence de spécification car cela crée une fausse confiance.

Un flux de travail SDD fonctionnel produit une chaîne d’artefacts, chacun 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 contre 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 – pas après que trois mille lignes de dérive soient atterries dans main.

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, ou avec un éditeur de texte brut et un réviseur discipliné. Ce qui compte, c’est la séquence et les portes d’examen, pas la marque de l’outil.

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 fin. Elle évite délibérément comment le construire. Le moment où votre spécification d’exigences dit « utiliser des ensembles triés Redis », vous avez cessé de spécifier et avez 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 langue claire. Nommez les utilisateurs affectés et la situation qui rend le problème douloureux. Un bon énoncé de problème permet à un réviseur 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 taux d’API :

Les consommateurs d’API du niveau gratuit peuvent envoyer des requites illimitées, ce qui provoque des pics de coûts et des impacts de voisinage 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 pas explicitement. 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 suffisamment précis pour que chacun se traduise par 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. Elles sont la phase de spécification qui fait son travail. Résolvez-les avant d’écrire le plan de conception, ou vous paierez pour l’ambiguïté dans le rétravail d’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 champ]
- [Explicitement hors champ]

## 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 appartiennent, 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 des contraintes existantes de votre projet – choix de pile, 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 des API 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’index et les règles de compatibilité ascendante. 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 la sémantique de livraison. Incluez les étapes de migration et les notes de restauration 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 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 relie aux 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 fichiers de test que vous vous attendez à 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écomposer les tâches d’implémentation

La phase de tâche 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 différence énorme, vous obtenez une séquence de changements cibles qui chacun remontent à 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 explicitement les dépendances. 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 révision

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 révision humaine. Le réviseur confirme que la différence 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 taux

**Dépend de :** Tâche 1 (schéma), Tâche 2 (référentiel)
**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 révision :** Confirmer que le middleware s'exécute après l'authentification, avant le gestionnaire

Garez-vous aux 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é 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 différences révisables.

Appliquer les contraintes de la pile de spécification

L’agent d’implémentation doit 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 refactorisez pas les modules non liés, ne changez pas les signatures d’API publiques en dehors de cette fonctionnalité, n’introduisez pas 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 limite manquait aux critères d’acceptation. Lorsque cela se produit, mettez à jour la spécification avant de continuer. Corrigez les exigences ou le plan, obtenez une révision 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 vie. 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 livré.

Vérifications automatisées

Exécutez la suite complète de tests, lint et vérifications de type sur CI. Connectez-les à votre pipeline en utilisant des modèles de la cheat sheet GitHub Actions si vous avez besoin d’un point de départ pratique. Les vérifications automatisées attrapent les régressions. Elles n’attrapent pas les mauvaises fonctionnalités construites correctement, c’est pourquoi la révision des critères d’acceptation compte toujours.

Critères d’acceptation et révision manuelle

Parcourez chaque critère d’acceptation de la spécification d’exigences. Marquez chacun comme satisfait, échoué ou reporté avec justification. La révision manuelle attrape 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érence 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érence sont un signal – soit le plan était incomplet, soit l’agent a erré. Les deux méritent attention avant la fusion.

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

Les agents IA sont des accélérateurs sur chaque phase, pas des remplacements pour la révision. Le modèle productif est brouillon, révision, raffinage, puis procéder. 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 qu’aucun code n’existe. Demandez à un agent d’implémenter une tranche de tâche à la fois, avec vous approuvant chaque différence 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 attraper les mauvais objectifs, l’architecture unsafe et le dépassement de champ subtil. Le flux de travail échoue lorsque l’un ou l’autre côté 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 matière d’outils par intention. Les guides d’exécution spécifiques aux outils – configuration d’éditeur, commandes slash, configuration d’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 un spike 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 de cinq phases – Développement piloté par les spécifications vs Vibe Coding explique quand une structure plus légère suffit.

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.

Des non-objectifs manquants. Sans non-objectifs, les agents étendent le champ par défaut. Ils ajoutent des couches de 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 uniquement après l’implémentation ont tendance à confirmer ce qui a été construit, pas ce qui était intentionnel. Le plan doit nommer quels critères d’acceptation se traduisent dans quels types de tests avant que le premier fichier de production ne change.

Sauter la révision 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 un calendrier. Fusionnez les éléments redondants, divisez les surdimensionnés et supprimez les tâches qui ne se traduisent 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 dépôt 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 pour 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 révision :

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

Liste de vérification 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
- [ ] Aucun changement architectural non documenté
- [ ] Spécification mise à jour si l'implémentation a différé

Conclusion

Le développement piloté par les spécifications n’est pas question d’écrire plus de documents. C’est une question de traverser spécifier, planifier, tâches, implémenter et valider avec une porte de révision à chaque étape. Chaque phase devrait laisser l’acteur suivant – humain ou agent – avec moins 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 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 différences révisables plus petites et un enregistrement durable d’intention qui survit aux réinitialisations de session et aux transferts d’équipe.

Lorsque la chaîne devient de la paperasse, coupez le champ – pas la révision. 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 – boîte à 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