Guide complet du Spec-Driven Development : comment piloter un AI Coding Agent avec une spécification logicielle

L’AI Coding Agent modifie des fichiers hors périmètre, oublie une contrainte importante et revient avec un code difficile à valider.

La solution la plus fiable consiste à appliquer le Spec-Driven Development comme une chaîne de preuves : contraintes du projet, Specification vérifiable, plan d’implémentation, tâches indépendantes, puis validation reliée à chaque exigence.

Cette méthode convient aux développeurs individuels qui corrigent sans cesse les mêmes erreurs, aux responsables techniques qui veulent introduire l’IA dans une équipe et aux organisations qui doivent pouvoir expliquer pourquoi un changement généré a été accepté.

Pourquoi le Spec-Driven Development réduit-il les retours inutiles ?

Un AI Coding Agent n’échoue pas uniquement parce qu’il produit une mauvaise ligne de code. Il échoue souvent parce que le contexte transmis est incomplet, contradictoire ou trop large. Une demande comme « ajoutez une authentification simple » laisse ouvertes plusieurs décisions : méthode de connexion, durée de session, gestion des erreurs, stockage des secrets, droits par rôle, comportement hors ligne et stratégie de test.

Dans un développement classique, ces choix peuvent être clarifiés oralement entre plusieurs personnes. Avec un agent, ils doivent être transformés en artefacts consultables. Le rôle du Spec-Driven Development n’est donc pas de produire une longue documentation avant toute action, mais d’établir une progression où chaque document limite l’interprétation du suivant.

Les principaux problèmes traités sont les suivants :

• Dérive de contexte : après plusieurs échanges, l’agent ne distingue plus toujours les exigences initiales des décisions provisoires prises pendant la conversation.
• Modification hors périmètre : une tâche fonctionnelle peut conduire à des changements dans la configuration, les dépendances ou l’architecture sans autorisation explicite.
• Coût de validation : si l’exigence n’est pas observable, l’équipe doit relire tout le code pour déterminer si la demande est réellement satisfaite.
• Conflit entre conventions : une règle locale peut contredire une consigne générale, notamment dans un dépôt monolithique ou une architecture en plusieurs applications.
• Retour arrière imprécis : lorsqu’un test échoue, il devient difficile de savoir s’il faut corriger le code, revoir la conception ou modifier la demande.

Les instructions persistantes peuvent limiter une partie de ces risques. GitHub documente notamment les instructions générales dans .github/copilot-instructions.md, les instructions propres à certains chemins dans .github/instructions et d’autres fichiers d’instructions destinés aux agents. Ces fichiers ne remplacent toutefois pas une Specification fonctionnelle : ils définissent surtout le cadre permanent dans lequel les tâches doivent être réalisées. Voir la documentation officielle de GitHub sur les instructions personnalisées.

Première étape : établir les contraintes qui ne doivent pas bouger

La première production attendue n’est pas du code, mais une courte constitution technique du projet. Elle doit rester suffisamment stable pour éviter de répéter les mêmes règles à chaque demande.

Cette constitution peut contenir :

• la pile technique réellement utilisée ;
• les commandes d’installation, de test, de vérification et de construction ;
• l’organisation des répertoires ;
• les conventions de nommage et de formatage ;
• les zones que l’agent peut modifier ;
• les fichiers ou répertoires interdits à la modification ;
• la politique de gestion des secrets ;
• les limites d’accès aux services externes ;
• les exigences de compatibilité ;
• la définition générale de « terminé ».

Une contrainte utile doit être opérationnelle. « Le code doit être propre » ne permet pas de décider. « Toute nouvelle route doit posséder un test d’erreur et ne doit pas accéder directement aux secrets d’environnement depuis le contrôleur » est plus exploitable, car l’agent et le relecteur peuvent rechercher des éléments concrets.

Les instructions doivent aussi expliquer les raisons des règles lorsque cela influence les choix futurs. La documentation de VS Code recommande des instructions courtes, autonomes et adaptées à leur portée ; elle distingue notamment les instructions toujours actives des règles propres à certains fichiers ou répertoires. Consulter les recommandations officielles de VS Code.

Attention : une règle permanente ne doit pas contenir une décision propre à une seule fonctionnalité. La durée de conservation d’un jeton peut appartenir à la Specification d’authentification, tandis que l’interdiction de placer un secret dans le dépôt appartient aux contraintes générales du projet.

À ce stade, l’équipe doit pouvoir répondre à trois questions :

1. Quels fichiers l’agent a-t-il le droit de toucher ?
2. Quelles commandes permettent de vérifier une modification ?
3. Quelles décisions sont non négociables, même si une autre solution semble plus rapide ?

Comment commencer un Spec-Driven Development sans écrire un document inutilisable ?

La meilleure entrée consiste à choisir une fonctionnalité limitée et à rédiger une première Specification qui décrit un comportement observable. Il n’est pas nécessaire de documenter toute l’application avant de tester la méthode.

Une Specification exploitable doit décrire au minimum :

• l’objectif utilisateur ;
• les acteurs concernés ;
• le scénario nominal ;
• les entrées attendues ;
• les sorties visibles ;
• les erreurs et cas limites ;
• les règles d’autorisation ;
• les effets sur les données ;
• les contraintes de compatibilité ;
• les critères d’acceptation.

Il est préférable de formuler les exigences sous forme de comportement. Par exemple :

Lorsqu’un utilisateur valide un formulaire audio contenant un fichier accepté, l’application affiche un état de traitement, conserve l’identifiant de la tâche et permet de consulter le résultat sans soumettre deux fois le même fichier.

Cette formulation laisse encore plusieurs points à préciser, mais elle donne déjà une trajectoire de test. Pour une fonction de montage vidéo, la Specification peut préciser les formats acceptés, l’existence d’un aperçu, le comportement lorsqu’un fichier source est absent et la conservation du projet après fermeture de l’interface. Pour un outil de design, elle peut décrire les dimensions autorisées, les calques attendus et la manière dont une erreur est signalée.

Jusqu’où détailler une Specification pour qu’un agent puisse l’exécuter ?

Une Specification est suffisamment détaillée lorsque deux développeurs raisonnables peuvent produire des solutions différentes dans leur structure interne, mais identiques sur les comportements vérifiables. Elle est trop vague si l’agent doit inventer une règle métier ; elle est trop prescriptive si elle impose chaque nom de fonction sans nécessité.

Chaque exigence importante devrait pouvoir être associée à au moins un des éléments suivants :

• un test automatisé ;
• une commande de vérification ;
• un exemple d’entrée et de sortie ;
• une règle statique ;
• une vérification manuelle ;
• une preuve enregistrée dans la demande de fusion.

La Specification ne doit pas contenir de chiffres de performance inventés pour donner une apparence de précision. Si la rapidité est essentielle, il faut d’abord définir la mesure, l’environnement, la charge et le seuil accepté. Sans ces éléments, une promesse comme « la réponse doit être instantanée » ne constitue pas un critère de validation.

Pour structurer les demandes d’équipe, un formulaire de problème peut imposer des champs tels que le comportement actuel, le comportement attendu, les étapes de reproduction et l’environnement. GitHub documente cette approche avec les formulaires YAML, qui permettent également de définir des champs obligatoires, des libellés et des valeurs par défaut. Voir la syntaxe officielle des formulaires GitHub.

Deuxième étape : transformer la Specification en conception puis en tâches

Une fois la Specification stabilisée, l’AI Coding Agent ne devrait pas modifier immédiatement le dépôt. Il doit d’abord proposer une conception : composants touchés, flux de données, dépendances, risques, stratégie de migration et méthode de test.

La conception répond à la question « comment cette exigence peut-elle entrer dans l’architecture existante ? ». Elle ne doit pas répéter toute la Specification. Son rôle est de rendre visibles les conséquences techniques qui ne sont pas forcément exprimées dans le besoin initial.

Le découpage en tâches doit ensuite respecter quatre règles :

• une tâche possède un résultat identifiable ;
• sa portée est limitée à un nombre raisonnable de composants ;
• elle peut être vérifiée sans attendre toute la fonctionnalité ;
• elle indique les dépendances qui doivent être terminées auparavant.

Une tâche comme « construire tout le système de synchronisation » est trop large. Une séquence plus sûre pourrait commencer par le modèle de données, continuer avec l’écriture d’un état local, ajouter l’interface de reprise, puis traiter les erreurs réseau et enfin intégrer les contrôles de bout en bout.

Le modèle officiel de GitHub Spec Kit illustre cette logique sous la forme Spec → Plan → Tasks → Implement. Chaque phase produit un artefact Markdown qui alimente la suivante, afin de transmettre à l’agent un contexte structuré plutôt qu’une succession d’instructions improvisées. Consulter la présentation officielle de GitHub Spec Kit.

Artefact	Question traitée	Condition de sortie	Preuve attendue
Contraintes du projet	Quelles limites s’appliquent à tout changement ?	Les règles stables sont écrites et sans contradiction connue	Fichier versionné et relu
Specification	Quel comportement doit être obtenu ?	Les exigences sont observables et les cas d’erreur décrits	Scénarios d’acceptation
Plan	Quelle conception respecte les contraintes ?	Les fichiers, dépendances et risques sont identifiés	Plan technique approuvé
Tâches	Quelle modification indépendante faut-il réaliser ?	Chaque tâche possède une portée et une validation	Liste de tâches traçable
Implémentation	Quel code change maintenant ?	La tâche est réalisée sans élargissement de périmètre	Différence, tests et journal de commande
Acceptation	La demande initiale est-elle satisfaite ?	Toutes les exigences sont reliées à une preuve	Rapport de validation

Pour les fonctionnalités particulièrement vastes, il faut éviter de remettre toute l’initiative à un seul cycle. La documentation de Spec Kit recommande alors une « spécification de spécifications » : une feuille de route décompose l’objectif en sous-fonctionnalités, chacune possédant son propre fichier de spécification, plan et liste de tâches. Lire le concept officiel de « Spec of Specs ».

Comment un AI Coding Agent doit-il découper les tâches selon la Specification ?

Le découpage devient fiable lorsque l’agent reçoit une consigne explicite : ne proposer que les tâches nécessaires à la prochaine tranche fonctionnelle, signaler les dépendances et séparer les changements de production des changements de test lorsque leur validation n’est pas identique.

Pour chaque tâche, il est utile d’imposer une fiche comprenant :

• Identifiant : par exemple T-03, stable dans la demande de fusion ;
• Objectif : le résultat recherché ;
• Périmètre : fichiers ou modules autorisés ;
• Préconditions : tâches déjà terminées ;
• Modification attendue : comportement à ajouter ou à corriger ;
• Validation : commande, test ou inspection ;
• Hors périmètre : ce qui ne doit pas être changé.

Une tâche correctement bornée limite aussi le contexte transmis. L’agent n’a pas besoin de recevoir l’intégralité du dépôt à chaque tour : la Specification concernée, le plan correspondant, les fichiers utiles et les commandes de validation suffisent souvent. Cela réduit les occasions de confusion entre une règle générale et une décision locale.

Les compétences spécialisées suivent une logique comparable. GitHub recommande d’utiliser les instructions personnalisées pour les règles simples applicables à presque toutes les tâches, et les compétences pour des consignes plus détaillées auxquelles l’agent ne doit accéder que lorsqu’elles sont pertinentes. Voir la documentation officielle sur les compétences des agents.

Troisième étape : exécuter une tâche à la fois et exiger une trace

Avant toute modification, l’agent doit reformuler :

1. la tâche qu’il traite ;
2. les exigences de la Specification concernées ;
3. les fichiers qu’il prévoit de consulter ou de modifier ;
4. les commandes qu’il exécutera ;
5. les risques ou hypothèses encore incertains.

Cette étape n’est pas un rituel de politesse. Elle permet de détecter immédiatement une mauvaise interprétation, par exemple lorsqu’une tâche d’interface entraîne une modification de schéma non prévue.

Après modification, le résultat doit comprendre :

• une description des fichiers modifiés ;
• les écarts par rapport au plan ;
• les commandes exécutées ;
• les résultats obtenus ;
• les tests non exécutés et leur raison ;
• les questions restant ouvertes.

L’équipe peut utiliser un environnement isolé et réinitialisable pour permettre à l’agent d’installer les dépendances, d’exécuter les tests et de rejouer la même tâche sans polluer la machine principale. Pour les projets Apple, audio, vidéo ou design, un Mac distant facilite également les vérifications liées à macOS, à Xcode, aux outils de création et aux périphériques ou simulateurs nécessaires. Les lecteurs qui évaluent cette organisation peuvent consulter le centre d’aide de Zutcloud ou examiner les options de location de Mac mini avant de définir leur environnement de validation.

Une réinitialisation fréquente reste préférable à une session dans laquelle l’agent accumule des modifications temporaires. Si l’environnement ne peut pas être reconstruit proprement, les résultats de test deviennent difficiles à interpréter : une réussite peut venir d’un fichier oublié, d’une dépendance installée manuellement ou d’un état local absent du dépôt.

Expérience de terrain : lorsqu’un agent propose de corriger plusieurs erreurs « au passage », la tâche doit être interrompue et redécoupée. Une amélioration non spécifiée peut rendre la différence plus difficile à relire et compliquer l’attribution d’un échec.

Quatrième étape : relier l’acceptation à chaque exigence

L’acceptation ne doit pas commencer par une relecture générale du code. Elle doit repartir de la Specification et construire une matrice simple :

Exigence	Test ou contrôle	Résultat	Décision
Entrée valide acceptée	Test d’intégration ou exemple reproductible	Réussi ou échoué	Accepter ou corriger
Entrée invalide refusée	Test d’erreur et message visible	Réussi ou échoué	Accepter ou revenir à la tâche
Accès non autorisé bloqué	Test de permission	Réussi ou échoué	Corriger la logique de sécurité
Données conservées après reprise	Scénario de redémarrage	Réussi ou échoué	Revoir la conception si nécessaire
Code conforme aux règles	Analyse statique et revue ciblée	Conforme ou non conforme	Demander une correction limitée

La validation doit couvrir les tests unitaires, les tests d’intégration, les contrôles statiques, les exemples d’interface et les vérifications manuelles nécessaires. Pour une application de traitement vidéo, cela peut inclure un fichier source valide, un fichier corrompu, une interruption pendant l’export et la présence du résultat final. Pour une application audio, il peut être nécessaire de vérifier les métadonnées, les fréquences d’échantillonnage prises en charge et la restitution d’une erreur compréhensible.

Si une exigence échoue, la correction doit revenir au niveau qui porte réellement le problème :

• Specification incorrecte : le comportement attendu doit être clarifié ;
• Plan incomplet : une dépendance ou un impact architectural a été oublié ;
• Tâche mal découpée : la modification a couvert trop de modules ;
• Implémentation défectueuse : le code doit être corrigé sans modifier l’objectif.

Continuer à ajouter des instructions temporaires après chaque échec produit souvent une accumulation de règles contradictoires. La traçabilité est plus solide lorsque la correction est enregistrée dans l’artefact approprié.

Cinquième étape : versionner les changements et empêcher la dérive

La Specification, le plan, les tâches et les tests doivent évoluer dans le même processus de contrôle de version que le code. L’objectif n’est pas de créer une bureaucratie documentaire, mais de conserver le lien entre une demande, sa conception, son implémentation et sa preuve d’acceptation.

Lorsqu’une exigence change, l’ordre recommandé est le suivant :

1. modifier la Specification ;
2. noter la raison du changement ;
3. analyser les fichiers, tests et tâches affectés ;
4. mettre à jour le plan ;
5. réviser ou fermer les tâches devenues obsolètes ;
6. modifier le code ;
7. rejouer les validations liées ;
8. demander une revue de la différence complète.

Dans une grande fonctionnalité, une feuille de route peut servir de source de vérité pour les sous-spécifications. Spec Kit recommande de mettre à jour la feuille de route avant les sous-spécifications concernées et de conserver les dépendances visibles entre les tranches. Cette discipline limite le risque qu’une petite demande locale contredise l’objectif global. Voir les règles de synchronisation des sous-spécifications.

La version du document compte autant que la version du code. Une demande de fusion qui contient uniquement le code final mais pas la Specification correspondante ne permet pas de déterminer si l’équipe a livré le besoin initial ou une interprétation improvisée.

Liste de contrôle avant d’autoriser l’agent à poursuivre

• [ ] Les contraintes techniques et les zones interdites sont versionnées.
• [ ] La Specification distingue le comportement nominal, les erreurs et les limites.
• [ ] Chaque exigence importante possède au moins une méthode de vérification.
• [ ] Le plan identifie les fichiers, dépendances et risques principaux.
• [ ] Les tâches sont indépendantes ou leurs dépendances sont explicitement ordonnées.
• [ ] L’agent annonce son périmètre avant de modifier le dépôt.
• [ ] Les commandes de test et de contrôle peuvent être rejouées dans un environnement propre.
• [ ] La différence produite indique les fichiers modifiés et les validations exécutées.
• [ ] Les échecs sont renvoyés au bon niveau : Specification, plan, tâche ou code.
• [ ] Toute modification de besoin commence par une mise à jour de la Specification.
• [ ] Les tests, documents et code évoluent dans la même demande de fusion.
• [ ] Une personne peut relier chaque résultat accepté à une exigence précise.

Le Spec-Driven Development n’est donc pas une version plus longue du développement par instructions. Il s’agit d’un dispositif de contrôle qui rend l’intention progressive, vérifiable et réversible. L’AI Coding Agent peut alors produire du code, mais il ne décide pas seul des frontières du produit, de la définition du terminé ou de la preuve nécessaire pour accepter un changement.

Pour un projet court et peu risqué, une Specification concise, quelques tâches et une validation automatisée peuvent suffire. Pour un produit d’équipe, une application de création audio ou vidéo, un outil de design ou un projet nécessitant des tests macOS, le coût initial de cette structure devient justifié dès que plusieurs personnes doivent relire, reprendre ou auditer les modifications.

Une station locale reste pratique pour un développement continu, mais elle concentre les dépendances, les états résiduels et les conflits d’usage. Un environnement cloud générique peut être rapide à créer, mais il ne fournit pas toujours macOS, les outils Apple ou une session réinitialisable adaptée aux tests créatifs. Une machine dédiée peut enfin devenir disproportionnée pour une phase de prototypage ou une campagne de validation limitée. Dans ces situations, louer un Mac auprès de Zutcloud permet de disposer d’un environnement distant séparé, de tester une chaîne complète d’AI Coding Agent et de revenir à une base propre lorsque la Specification évolue. Cette option reste moins adaptée aux charges longues et constantes ou aux projets exigeant un accès physique permanent aux périphériques ; elle devient surtout pertinente lorsque l’objectif est de tester, livrer ou valider sans immobiliser une machine principale. Pour les questions d’accès et de mise en place, la page contacter Zutcloud constitue le point de départ approprié.