Workflow Spec-Driven Development : du besoin au code

Le workflow officiel de Spec Kit distingue quatre artefacts successifs — Specification, plan, tâches et implémentation — chacun servant de contexte au suivant (documentation officielle du cycle Spec-Driven Development). Si votre équipe demande directement à un agent de codage de transformer une idée en fonctionnalité complète, la solution la plus rapide consiste donc à séparer le travail en deux pistes : la piste des spécifications pour les décisions et les critères d’acceptation, puis la piste du code pour les changements vérifiables.

Symptôme : les tickets restent ambigus, l’agent modifie trop de fichiers et la revue découvre tardivement des comportements non prévus. Solution : associer chaque exigence à une Specification, chaque tâche à des fichiers et commandes de vérification, puis bloquer le passage à l’étape suivante tant qu’un humain n’a pas validé le bon artefact.

Cette méthode s’adresse aux équipes qui veulent intégrer Spec-Driven Development dans un dépôt déjà actif, aux responsables qui doivent faire relire du code généré par une IA et aux développeurs qui souhaitent laisser un AI Coding Agent travailler à distance tout en conservant une trace exploitable de chaque décision.

La double piste comme principe d’architecture

Une équipe ne doit pas confondre « écrire davantage de documentation » avec Spec-Driven Development. La différence tient à la relation entre les artefacts. La Specification ne décrit pas seulement une intention destinée à être oubliée après le démarrage du développement : elle devient une référence que le plan, les tâches, les tests et la revue doivent pouvoir citer.

La piste des spécifications contient notamment :

• le problème à résoudre et les utilisateurs concernés ;
• les comportements attendus ;
• les données manipulées ;
• les interfaces et événements visibles ;
• les cas d’erreur ;
• les critères d’acceptation ;
• les contraintes métier ou réglementaires ;
• les décisions encore non confirmées.

La piste du code contient, elle, les branches, les commits, les fichiers modifiés, les résultats de tests et les commentaires de revue. Les deux pistes doivent être reliées par un identifiant de fonctionnalité, une version de Specification ou un identifiant de tâche. Sans cette relation, vous obtenez deux documents parallèles : l’un décrit ce qui devait être construit, l’autre montre ce qui a réellement été modifié, sans mécanisme fiable pour comparer les deux.

Le modèle officiel de Spec Kit présente justement la Specification comme l’artefact central, puis fait dériver le plan et l’implémentation de cette base (description du modèle Spec-Driven). Pour une équipe existante, il est toutefois préférable de l’adapter à vos règles de dépôt plutôt que de remplacer immédiatement tous vos tickets, branches et outils de livraison.

La revue des besoins avant la Specification

Avant de demander à un agent de produire une Specification, vous devez transformer la demande initiale en résultat observable. « Améliorer l’espace client » n’est pas une exigence exploitable. « Permettre à un utilisateur authentifié de télécharger ses factures au format PDF depuis la page de paiement, avec un message explicite en cas d’échec » est déjà plus proche d’un comportement testable.

La revue doit produire quatre éléments :

1. Le résultat recherché, formulé du point de vue de l’utilisateur ou du système.
2. Le périmètre inclus, avec les écrans, interfaces ou composants concernés.
3. Le périmètre exclu, afin d’empêcher l’agent d’ajouter spontanément une fonction voisine.
4. Les risques et inconnues, séparant ce qui est décidé de ce qui doit encore être confirmé.

Une demande ne devrait passer à la Specification que si deux personnes peuvent déterminer, en lisant le texte, si le résultat est atteint. Si l’équipe discute encore du comportement attendu, la bonne action n’est pas de lancer l’agent, mais de renvoyer la demande en clarification.

Comment transformer une demande en Specification exploitable ? Commencez par écrire les scénarios nominaux, puis ajoutez les erreurs, les permissions, les limites de données et les critères d’acceptation. Chaque scénario doit être associé à un identifiant stable, par exemple REQ-014, qui sera repris dans le plan, les tâches et la description de la demande de fusion. L’important n’est pas le nom du fichier, mais la possibilité de retrouver le chemin entre le besoin et le changement de code.

Une Specification utile peut suivre cette structure :

La frontière entre Specification et conception technique

En quoi la Specification diffère-t-elle d’une conception technique ? La Specification répond d’abord à la question « quel comportement doit être garanti ? ». La conception technique répond à « comment le dépôt va-t-il produire ce comportement ? ». Cette distinction évite de figer trop tôt une solution et permet à l’équipe de changer de bibliothèque ou de composant sans réécrire les objectifs métier.

Par exemple, la Specification peut exiger qu’un export de données soit relançable sans créer de doublon et qu’un utilisateur obtienne un statut clair lorsque la génération échoue. Le plan technique devra alors déterminer s’il faut une file de messages, une clé d’idempotence, une table de suivi ou un mécanisme différent. La Specification ne doit pas imposer une technologie sans raison ; le plan doit, en revanche, expliciter les conséquences de la solution choisie.

Votre plan technique doit couvrir au minimum :

• les modules et fichiers susceptibles d’être touchés ;
• les dépendances ajoutées, supprimées ou mises à jour ;
• les changements de schéma et leur stratégie de migration ;
• les effets sur la compatibilité descendante ;
• les tests unitaires, d’intégration et de parcours ;
• les données nécessaires à la validation ;
• les opérations de retour arrière.

La différence est particulièrement importante pour les projets audio, vidéo ou de design. Une Specification peut décrire le rendu attendu d’un aperçu, la synchronisation entre une piste audio et une animation ou l’export d’un format précis. Le plan devra ensuite traiter les codecs, les bibliothèques natives, l’accélération matérielle et les contraintes de fichiers, sans faire passer ces choix techniques pour des exigences utilisateur.

Lorsqu’une modification touche l’authentification, la facturation, les migrations de données ou une interface publique, imposez une validation humaine avant la génération des tâches. La documentation des workflows de Spec Kit décrit des étapes de type « gate » qui suspendent le processus jusqu’à une approbation explicite (référence officielle des workflows et points de contrôle). C’est une protection de gouvernance, pas une garantie automatique de sécurité : chaque commande exécutée par l’agent doit encore être examinée dans son contexte.

La préparation du dépôt et du flux Git

L’intégration dans un dépôt existant doit commencer par une cartographie, pas par l’installation d’un nouvel outil. Identifiez la branche de référence, les commandes de test, les règles de revue, les dossiers générés, les secrets accessibles et les fichiers qui ne doivent jamais être modifiés par l’agent.

Vous pouvez ensuite adopter un flux de travail aussi simple que celui-ci :

1. Créer une branche de fonctionnalité portant l’identifiant de la Specification.
2. Ajouter ou mettre à jour les artefacts de spécification dans un dossier versionné.
3. Faire relire la Specification avant de générer le plan.
4. Faire relire le plan avant de générer les tâches.
5. Exécuter les tâches sur une branche isolée.
6. Ouvrir une demande de fusion contenant le résumé des différences, les tests et les éléments non résolus.
7. Mettre à jour la Specification si le comportement accepté a changé.

Comment raccorder Spec-Driven Development à un flux Git existant ? Ne créez pas une branche distincte pour chaque artefact si cela ralentit les revues. Dans un petit dépôt, vous pouvez versionner la Specification et le plan dans la même branche de préparation, puis produire une branche d’implémentation après approbation. Dans un dépôt plus réglementé, la Specification peut être fusionnée séparément afin de devenir la référence approuvée avant toute modification de code.

Le point essentiel est d’éviter le mélange entre une décision approuvée et une hypothèse de l’agent. Les fichiers de spécification doivent donc distinguer explicitement :

• les faits métier confirmés ;
• les contraintes techniques imposées ;
• les choix proposés par l’agent ;
• les questions en attente de réponse.

Les extensions et les règles de projet peuvent également être enregistrées dans une configuration dédiée ; la documentation de référence indique notamment l’usage de .specify/extensions.yml pour déclarer des extensions et des actions avant ou après certaines étapes (configuration officielle des extensions). Dans votre dépôt, faites relire ces hooks comme du code : une action automatique qui crée un commit ou lance une commande possède des droits réels sur l’environnement d’exécution.

Le découpage des tâches pour l’agent

Un AI Coding Agent ne doit pas recevoir « implémentez toute la fonctionnalité » comme unité de travail. Une tâche correcte possède une frontière, un résultat et une méthode de vérification. Elle doit aussi indiquer ce que l’agent ne doit pas modifier.

Chaque tâche devrait contenir :

• l’identifiant de la Specification concernée ;
• l’objectif local ;
• les fichiers ou composants ciblés ;
• les dépendances nécessaires ;
• la commande de test ;
• le résultat attendu ;
• la condition d’arrêt ;
• les risques connus ou les décisions à ne pas prendre seul.

Quelle taille donner à une tâche exécutée par l’agent ? Choisissez la plus petite unité qui produit un changement vérifiable sans exiger de conserver toute la fonctionnalité en mémoire. Une tâche peut créer un contrat d’interface, ajouter une migration, implémenter un service ou écrire un test de parcours. Elle devient trop grande lorsqu’elle mélange plusieurs couches, plusieurs décisions non approuvées ou des tests qui ne peuvent être exécutés qu’après une longue série de changements.

La documentation officielle sur les fonctionnalités complexes recommande de limiter l’implémentation à une série de tâches ou à une phase, puis de reprendre l’exécution à partir des tâches déjà marquées comme terminées (guide officiel de gestion des fonctionnalités complexes). Cette approche est préférable à une longue session sans point d’arrêt, notamment lorsque l’agent travaille sur une machine distante ou lorsqu’une réduction de contexte risque de lui faire perdre les hypothèses de départ.

Pour les tâches longues, utilisez des points de contrôle : état du dépôt, sortie des tests, résumé des décisions et liste des fichiers modifiés. Si l’exécution échoue, l’agent doit reprendre depuis le dernier état vérifiable, et non tenter de « réparer » une session dont les hypothèses ne sont plus fiables.

La revue conjointe du code et de la Specification

Une revue de code classique vérifie la lisibilité, la complexité, la sécurité et les tests. Dans un workflow Spec-Driven Development, elle doit également répondre à deux questions supplémentaires : le code réalise-t-il les comportements approuvés, et a-t-il introduit un comportement qui n’était pas demandé ?

Demandez à l’agent de produire un rapport contenant :

• un résumé des différences ;
• la correspondance entre tâches et fichiers ;
• les commandes exécutées et leur résultat ;
• les critères d’acceptation couverts ;
• les scénarios d’erreur vérifiés ;
• les éléments non résolus ;
• les écarts éventuels entre le plan et l’implémentation.

Le responsable de la revue doit ensuite contrôler les chemins souvent oubliés : permissions insuffisantes, données absentes, répétition d’une requête, interruption réseau, incompatibilité de version, annulation d’une opération et comportement après migration. Une implémentation peut passer les tests nominaux tout en restant non conforme à la Specification sur ces cas.

Les outils de revue de demandes de fusion permettent de commenter les différences, les fichiers et les dépendances avant l’intégration (documentation officielle sur la revue des demandes de fusion). Utilisez cette capacité pour commenter l’écart précis — par exemple « le scénario REQ-014 prévoit un refus pour ce rôle, mais cette branche retourne un succès » — plutôt qu’une remarque vague sur la qualité du code.

Le rôle de l’agent s’arrête lorsque le changement est explicable et testable. Il ne doit pas décider seul de supprimer une exigence, d’étendre le périmètre ou de remplacer une contrainte métier par une solution plus simple à coder. Ces décisions doivent retourner sur la piste des spécifications.

La livraison continue et le retour vers la Specification

La livraison ne termine pas le cycle. Si un défaut révèle que le comportement attendu était mal défini, corrigez d’abord la Specification ou ajoutez un scénario manquant, puis générez une nouvelle tâche. Modifier uniquement le code crée une divergence qui réapparaîtra lors d’une prochaine intervention de l’agent.

Avant la fusion, vérifiez l’alignement entre :

• la version approuvée de la Specification ;
• le plan technique réellement suivi ;
• les tâches terminées ;
• les tests associés ;
• la différence de code ;
• la décision de revue.

Après la mise en production, classez chaque retour dans l’une de ces catégories : défaut d’implémentation, exigence incomplète, nouvelle demande ou contrainte technique apparue. Seuls les deux premiers cas peuvent parfois être traités immédiatement ; une nouvelle demande doit produire une évolution clairement identifiée de la Specification.

Pour automatiser le cycle, vous pouvez utiliser des workflows enchaînant les commandes, les vérifications et les approbations humaines. La documentation officielle décrit notamment des étapes de commande, de script, de condition, de boucle et de point de contrôle (référence des types d’étapes de workflow). Cependant, les commandes qui exécutent des scripts locaux doivent être traitées avec prudence : les paramètres interpolés ne constituent pas, à eux seuls, une isolation de sécurité.

Les conditions de choix pour votre équipe

Utilisez ces branches de décision avant de déployer le processus :

• Si vos demandes comportent des critères d’acceptation vérifiables et que votre dépôt possède déjà des tests exécutables, choisissez une adoption progressive sur une ou deux fonctionnalités ; sinon, commencez par normaliser la revue des besoins.
• Si la fonctionnalité touche des données sensibles, une migration ou une interface publique, choisissez une approbation humaine entre Specification, plan et tâches ; sinon, vous pouvez automatiser davantage l’enchaînement.
• Si l’agent perd régulièrement le contexte ou modifie trop de fichiers, choisissez des lots de tâches plus petits et des points de contrôle ; sinon, conservez des lots regroupant une même couche technique.
• Si votre dépôt applique déjà un flux de branches et de demandes de fusion, choisissez de relier les artefacts existants par identifiants ; sinon, créez d’abord une convention minimale de versionnement.
• Si l’exécution doit rester traçable à distance, choisissez un environnement offrant isolation du dépôt, conservation des journaux, restauration par instantané et accès sécurisé aux réviseurs ; sinon, gardez l’agent sur un poste contrôlé jusqu’à ce que ces garanties soient disponibles.

Le workflow Spec-Driven Development devient ainsi un système de passage de responsabilité : la revue approuve l’intention, le plan traduit les conséquences techniques, les tâches bornent l’exécution, puis la revue compare le résultat avec la Specification.

Un poste local ou une machine virtuelle standard peut convenir pour des tâches courtes, mais ces solutions montrent vite leurs limites lorsque l’agent travaille longtemps : session interrompue, environnement partagé, restauration incomplète, journaux difficiles à conserver et accès graphique peu pratique pour les projets audio, vidéo ou design. Les solutions cloud génériques ajoutent parfois une isolation insuffisante du dépôt et une revue distante moins confortable. Pour une équipe qui doit seulement tester ce mode de travail ou exécuter temporairement un agent dans un environnement Mac isolé, louer une machine auprès de kvmboot peut offrir un cadre plus cohérent, à condition de vérifier avant le démarrage la conservation des journaux, l’accès des réviseurs et la récupération de l’état de travail. Vous pouvez consulter le centre d’aide de kvmboot puis examiner les options de location Mac disponibles selon la durée et le niveau d’isolation nécessaires.