Spec-Driven Development pour AI Coding Agent : guide

Le symptôme est toujours le même : l’AI Coding Agent produit du code plausible, mais chaque nouvelle correction éloigne un peu plus le projet de la demande initiale.

La solution la plus fiable consiste à appliquer le Spec-Driven Development comme une chaîne de décision : contraintes du projet, Specification testable, plan technique, tâches isolées, implémentation contrôlée, puis acceptation reliée aux exigences d’origine.

Cette méthode ne consiste donc pas à écrire un « super prompt ». Elle transforme l’intention en artefacts versionnés que l’agent peut consulter, que l’équipe peut relire et que les tests peuvent vérifier.

À qui cette méthode apporte le plus de valeur

Ce guide concerne les développeurs qui doivent souvent corriger plusieurs fois le même code généré, les responsables techniques qui souhaitent intégrer l’IA dans un processus d’équipe et les organisations qui ont besoin d’une trace claire entre la demande, l’implémentation et la validation.

Les projets audio, vidéo et design bénéficient également de cette approche lorsque les exigences sont nombreuses : formats de fichiers, comportement de l’interface, règles de nommage, droits d’accès, compatibilité avec les outils de production ou conservation des métadonnées.

Première étape : fixer les contraintes avant d’écrire la Specification

Un AI Coding Agent ne distingue pas spontanément une préférence temporaire d’une règle structurelle. Si le dépôt contient plusieurs conventions implicites, l’agent risque de choisir une solution techniquement cohérente, mais incompatible avec l’organisation existante.

La première production attendue n’est donc pas du code, mais un document de contraintes relativement stable. Celui-ci peut préciser :

• la pile technique autorisée et les versions réellement utilisées ;
• l’organisation des répertoires et les emplacements où les nouveaux fichiers peuvent être créés ;
• les conventions de nommage, de formatage et de journalisation ;
• les zones interdites à la modification ;
• les règles de sécurité, notamment la gestion des secrets et des données personnelles ;
• les commandes officielles de test, de vérification statique et de construction ;
• la définition de « terminé » pour une fonctionnalité ;
• les décisions qui nécessitent une validation humaine.

Une contrainte utile doit être observable. « Le code doit être propre » est trop vague. « Toute nouvelle route doit posséder un test d’erreur et ne doit pas lire directement les variables d’environnement dans le contrôleur » peut être vérifié par inspection ou automatisation.

La documentation officielle de Spec Kit et son modèle de développement piloté par les spécifications présente justement une première étape dédiée aux principes directeurs du projet. Dans ce modèle, ces principes sont conservés dans un fichier de constitution afin de guider les phases suivantes, plutôt que d’être répétés dans chaque demande.

Point de vigilance : une règle qui change à chaque fonctionnalité n’est pas une contrainte de projet. Elle doit plutôt figurer dans la Specification concernée, faute de quoi l’agent risque de traiter une décision locale comme une obligation générale.

Une base minimale peut être organisée ainsi :

project/
├── docs/
│   ├── constitution.md
│   └── architecture/
├── specs/
│   └── 001-nom-fonctionnalite/
│       ├── specification.md
│       ├── plan.md
│       └── tasks.md
├── src/
└── tests/

L’objectif n’est pas d’imposer cette arborescence à tous les projets, mais de séparer clairement les règles durables des décisions propres à une fonctionnalité.

Comment commencer le Spec-Driven Development sans alourdir le projet

Le Spec-Driven Development commence avec un objectif utilisateur limité, et non avec une liste de fichiers à modifier. Pour une galerie vidéo, par exemple, la demande initiale pourrait être : « permettre à un utilisateur de filtrer les vidéos par format et de conserver ce filtre lors du retour sur la page ».

Cette phrase doit ensuite être clarifiée selon cinq axes :

1. comportement attendu ;
2. données d’entrée ;
3. résultat visible ou retourné ;
4. cas d’erreur et états vides ;
5. contraintes non fonctionnelles ou règles de sécurité.

Une Specification exploitable pourrait préciser que le filtre accepte uniquement les formats présents dans le catalogue, que l’absence de résultat affiche un état explicite, que le filtre est restauré après un rechargement et qu’une valeur inconnue est ignorée sans provoquer d’erreur serveur.

La question centrale n’est pas de savoir si le document est long. Elle est de savoir si chaque exigence peut être reliée à une preuve. Une règle est suffisamment détaillée lorsque l’un des éléments suivants permet de conclure qu’elle est respectée :

• un test automatisé ;
• une vérification statique ;
• un exemple d’interface ou de réponse ;
• une inspection d’un fichier ou d’un parcours ;
• une validation manuelle décrite à l’avance.

Quel niveau de détail donner à une Specification pour qu’un agent puisse l’exécuter ?

Une bonne Specification décrit le quoi, le pourquoi, les limites et les critères d’acceptation. Elle ne doit pas forcément imposer le comment dès le départ, car la phase de planification sert précisément à comparer les options techniques.

Une structure pratique peut contenir :

# Fonctionnalité : filtrage du catalogue vidéo

## Objectif
Un utilisateur doit pouvoir afficher uniquement les vidéos correspondant
à un format disponible dans le catalogue.

## Scénario principal
- L'utilisateur ouvre le catalogue.
- Il sélectionne un format.
- La liste est mise à jour.
- Le choix reste visible après actualisation.

## Cas limites
- Aucun élément ne correspond au filtre.
- Le format demandé n'existe plus.
- Le catalogue est indisponible.

## Contraintes
- Aucun changement dans le modèle de stockage.
- Le filtre ne doit pas exposer de données privées.
- La requête doit réutiliser le service de catalogue existant.

## Critères d'acceptation
- Un format valide filtre les résultats.
- Une valeur inconnue revient à l'état sans filtre.
- Un catalogue vide affiche un message dédié.
- Les tests de régression existants restent réussis.

Cette forme empêche plusieurs ambiguïtés fréquentes. L’agent ne doit pas deviner si un catalogue vide est une erreur, si un filtre invalide doit être rejeté ou si la modification peut toucher la structure de stockage.

La Specification doit également distinguer les décisions obligatoires des choix ouverts. Par exemple, « conserver l’API publique existante » est une contrainte, tandis que « utiliser un composant de sélection ou des boutons » peut rester une décision de conception.

Deuxième étape : transformer la Specification en plan vérifiable

Une fois la Specification relue, l’agent doit produire un plan technique séparé. Cette séparation évite de mélanger le besoin utilisateur avec une première solution parfois prématurée.

Le plan doit répondre à des questions précises :

• quels modules sont concernés ;
• quelles interfaces existantes seront réutilisées ;
• quelles données circulent entre les composants ;
• quels contrats doivent rester compatibles ;
• quels risques peuvent provoquer une régression ;
• quelles commandes permettront de vérifier la modification ;
• quelles parties peuvent être réalisées indépendamment.

Le modèle officiel de workflow Spec Kit distingue la Specification, le plan technique, la liste des tâches et l’implémentation. Cette succession est importante : elle donne à chaque artefact une responsabilité différente et évite de demander à l’agent de résoudre simultanément le besoin, l’architecture et le code.

Avant d’accepter le plan, le développeur doit demander à l’agent de signaler :

• les hypothèses non confirmées ;
• les fichiers qu’il compte modifier ;
• les dépendances indirectes ;
• les éléments absents de la Specification ;
• les tests impossibles à automatiser immédiatement.

Si l’agent ajoute une base de données, une nouvelle couche d’abstraction ou une bibliothèque alors que le besoin pouvait être traité localement, l’alerte doit être traitée avant la génération des tâches.

Troisième étape : faire produire des tâches réellement indépendantes

La liste des tâches est le pont entre la conception et le code. Elle ne doit pas être un simple résumé du plan, mais une série d’actions pouvant être exécutées et vérifiées avec un périmètre limité.

Une tâche utile contient au minimum :

• un identifiant stable ;
• une description de l’action ;
• les fichiers ou modules concernés ;
• les prérequis ;
• le test ou contrôle associé ;
• le résultat attendu ;
• une indication de dépendance lorsqu’elle existe.

Pour la fonctionnalité de filtrage vidéo, un découpage raisonnable pourrait être :

T001 — Ajouter le modèle de filtre accepté
T002 — Adapter le service de catalogue
T003 — Ajouter les tests du service
T004 — Relier le filtre à l’interface
T005 — Gérer l’état vide et la valeur inconnue
T006 — Ajouter le scénario de régression

Ce découpage est préférable à une tâche unique comme « implémenter le filtrage complet », car une modification de service, une évolution d’interface et une vérification de régression ne se valident pas de la même manière.

La documentation consacrée à la génération des tâches explique que les tâches peuvent être dérivées du plan, des scénarios, des contrats et du modèle de données. Elle décrit également la possibilité d’identifier les tâches parallélisables, mais cette option doit rester soumise aux dépendances réelles du dépôt.

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

Une règle simple consiste à limiter chaque cycle à une unité qui possède :

1. un objectif unique ;
2. un ensemble de fichiers raisonnablement proche ;
3. une vérification identifiable ;
4. un point de retour clair en cas d’échec.

Une tâche qui modifie simultanément l’authentification, le stockage, l’interface et les tests d’intégration est trop large, même si l’agent peut techniquement la traiter en une seule réponse. Plus le périmètre est large, plus il devient difficile de savoir quelle hypothèse a provoqué l’échec.

Comparer une demande improvisée avec un flux piloté par les spécifications

Le tableau suivant résume la différence entre deux façons d’utiliser un agent de programmation. Il ne compare pas des performances chiffrées, car celles-ci dépendent du dépôt, du modèle et de la qualité des tests.

Élément	Demande improvisée	Flux piloté par une Specification
Point de départ	Prompt centré sur le fichier ou la correction immédiate	Objectif utilisateur et contraintes versionnées
Contexte fourni	Mélange de règles, d’hypothèses et de code	Artefact ciblé, plan et tâche courante
Découpage	Souvent laissé à l’agent	Tâches isolées avec dépendances explicites
Contrôle avant modification	Variable	Plan, fichiers concernés et hypothèses à relire
Validation	Impression générale ou test final	Critères d’acceptation reliés à chaque exigence
Retour arrière	Correction par nouveaux prompts	Retour à la tâche ou à la Specification en échec
Évolution du besoin	Ajout de demandes dans le fil de discussion	Modification de la Specification puis analyse d’impact

La méthode pilotée par les spécifications n’élimine pas les erreurs. Elle rend surtout leur origine plus lisible. Une erreur de comportement doit renvoyer à la Specification ; une mauvaise architecture au plan ; une modification incomplète à la tâche ; un défaut de code à l’implémentation ou au test.

Quatrième étape : exécuter une seule tâche à la fois

Pendant l’implémentation, l’agent ne doit recevoir que le contexte nécessaire à la tâche courante : l’extrait pertinent de la Specification, le plan correspondant, les fichiers concernés et les commandes de validation.

Avant toute modification, il est utile d’exiger une réponse structurée :

Plan d'action :
1. Fichiers qui seront lus
2. Fichiers qui seront modifiés
3. Hypothèses utilisées
4. Tests à ajouter ou à exécuter
5. Fichiers explicitement exclus

Après la modification, la sortie attendue doit inclure :

• un résumé des changements ;
• la liste des fichiers modifiés ;
• les commandes exécutées ;
• les résultats obtenus ;
• les points non vérifiés ;
• les écarts éventuels par rapport à la Specification.

Cette discipline protège contre le glissement de périmètre. Un agent qui découvre une difficulté dans une tâche ne doit pas automatiquement réécrire une autre couche du projet pour la contourner. Il doit signaler l’écart, puis attendre une décision.

Expérience de terrain : lorsque l’agent modifie une zone interdite pour « faire passer » un test, le problème n’est pas seulement technique. Il révèle souvent une tâche mal découpée ou une Specification qui ne décrit pas le contrat existant.

Pour les projets audio, vidéo ou design, cette étape doit aussi contrôler les fichiers binaires, les profils de couleur, les codecs, les métadonnées et les chemins d’exportation. Une fonctionnalité peut sembler correcte dans l’interface tout en dégradant le fichier final ou en supprimant des informations nécessaires à la chaîne de production.

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

L’acceptation ne doit pas commencer lorsque tout le code est terminé. Chaque tâche doit laisser une preuve proportionnée à son risque.

Une matrice simple permet de conserver la traçabilité :

Exigence	Preuve attendue	Statut
Un format valide filtre le catalogue	Test du service et vérification de l’interface	À vérifier
Une valeur inconnue ne provoque pas d’erreur	Test d’entrée invalide	À vérifier
Le choix reste visible après actualisation	Test d’interface ou contrôle manuel documenté	À vérifier
Le catalogue vide affiche un état dédié	Test de rendu et capture de référence si nécessaire	À vérifier

Les contrôles peuvent inclure les tests unitaires, les tests d’intégration, l’analyse statique, la compilation, la vérification des contrats d’API et une inspection manuelle. L’important est de relier le résultat à une exigence précise, plutôt que d’annoncer que « les tests sont verts » sans expliquer ce qu’ils couvrent.

Les modèles de tâches documentés dans les ressources officielles de Spec Kit prévoient notamment l’organisation par scénario utilisateur, les dépendances entre composants, les chemins de fichiers et des points de contrôle intermédiaires.

Pour renforcer la revue, il est possible d’ajouter une analyse de cohérence entre les artefacts. La documentation sur les commandes complémentaires de Spec Kit décrit notamment des étapes destinées à clarifier les zones ambiguës, analyser la cohérence et générer des listes de vérification.

Que faire lorsqu’une Specification change après l’implémentation ?

Une modification de besoin ne doit pas être injectée directement sous la forme d’un nouveau prompt dans la conversation en cours. La première action consiste à modifier la Specification, puis à identifier les conséquences sur le plan, les tâches, les tests et les interfaces existantes.

Le processus peut suivre cette séquence :

1. enregistrer la demande de changement ;
2. identifier les exigences concernées ;
3. comparer l’ancien et le nouveau comportement ;
4. analyser les dépendances techniques ;
5. mettre à jour le plan ;
6. régénérer ou corriger les tâches ;
7. adapter les tests d’acceptation ;
8. implémenter le changement sur une branche isolée ;
9. vérifier les exigences conservées ;
10. fusionner uniquement après revue des écarts.

La version de la Specification doit rester consultable avec la version du code qui l’implémente. Une équipe peut utiliser une branche, une demande de fusion ou un dossier de fonctionnalité, à condition de conserver le lien entre les trois niveaux : intention, implémentation et preuve.

La gestion de versions permet également de revenir à l’état précédent lorsque le changement produit une dérive. La documentation de référence sur les opérations de restauration et l’historique des versions rappelle qu’un retour arrière doit être traité comme une opération contrôlée, et non comme une succession de corrections improvisées.

Règle de retour arrière : si plusieurs tâches tentent de réparer le même écart sans résoudre la cause, il faut interrompre l’implémentation et revenir à la dernière Specification cohérente. Continuer à ajouter des instructions temporaires augmente généralement la dette de contexte.

La liste de contrôle avant de déclarer la fonctionnalité terminée

Cette liste peut être intégrée au dépôt et adaptée à chaque projet :

• [ ] Les contraintes générales du projet sont documentées et approuvées.
• [ ] La Specification décrit le comportement nominal, les entrées, les sorties et les erreurs.
• [ ] Chaque exigence importante possède un critère d’acceptation.
• [ ] Les hypothèses non confirmées sont explicitement signalées.
• [ ] Le plan indique les modules concernés et les zones exclues.
• [ ] Les tâches sont assez petites pour être exécutées et vérifiées séparément.
• [ ] L’AI Coding Agent a annoncé son plan avant toute modification.
• [ ] Les tests ou contrôles associés à la tâche ont été exécutés.
• [ ] Les changements hors périmètre ont été refusés ou documentés.
• [ ] Les fichiers audio, vidéo, graphiques ou métadonnées ont été contrôlés lorsque le projet en contient.
• [ ] La validation finale renvoie aux exigences originales, et non à l’impression générale laissée par l’agent.
• [ ] La Specification et le code sont enregistrés dans le même cycle de version.
• [ ] Un retour arrière vers une version connue reste possible.

Préparer un environnement qui permet de vérifier réellement le résultat

Le Spec-Driven Development perd une grande partie de son intérêt si l’agent ne dispose pas d’un environnement reproductible. Le projet doit au minimum définir les commandes de préparation, de test, de contrôle statique et de réinitialisation.

Il faut également vérifier les éléments qui sont souvent oubliés :

• variables d’environnement documentées sans secrets en clair ;
• versions des dépendances verrouillées lorsque cela est nécessaire ;
• données de test reproductibles ;
• accès limité aux services externes ;
• fichiers générés séparés des sources ;
• possibilité de supprimer puis recréer l’environnement ;
• journal des commandes exécutées par l’agent.

Pour un travail ponctuel, une équipe peut préférer un environnement distant réinitialisable plutôt qu’une machine locale difficile à remettre dans un état propre. Les équipes qui évaluent ce type d’organisation peuvent consulter le centre d’aide consacré aux environnements de développement à distance, puis vérifier si une machine Mac temporaire convient à leurs outils de test, de création ou d’automatisation.

Un accès distant n’est toutefois pas automatiquement préférable. Un projet qui exige une charge lourde permanente, un périphérique physique spécifique ou un accès local continu peut être mieux servi par une machine dédiée. À l’inverse, une courte phase de prototypage, une validation de compatibilité macOS ou une chaîne de test isolée peuvent justifier la location d’un environnement plutôt que l’achat immédiat d’un poste.

Pourquoi une machine Mac temporaire peut compléter ce processus

Dans un flux de développement piloté par les spécifications, l’environnement d’exécution fait partie des conditions de validation. Une configuration locale unique peut masquer des problèmes de chemins, de droits, de dépendances système ou de compatibilité macOS jusqu’au dernier moment. Un environnement distant ajoute aussi ses propres contraintes : latence, accès aux périphériques, stockage temporaire et gestion des identifiants.

La solution actuelle doit donc être comparée honnêtement à une solution Mac :

• un poste local peut être difficile à réinitialiser entre deux branches ;
• un serveur générique ne reproduit pas toujours les comportements attendus sur macOS ;
• une machine personnelle peut être indisponible pendant une phase de test ou de démonstration ;
• l’achat d’un poste dédié immobilise un budget pour un besoin qui peut rester temporaire.

Lorsque l’objectif est de disposer rapidement d’un environnement Mac isolé pour tester un AI Coding Agent, exécuter une chaîne de validation ou contrôler un projet audio, vidéo ou design, la location d’un Mac mini à Hong Kong peut constituer une option plus souple qu’un achat immédiat. Elle n’est pas adaptée à tous les projets, notamment lorsque l’équipe exige une charge stable de longue durée ou des connexions physiques particulières, mais elle permet de séparer l’environnement de test du poste de travail principal.

Le critère décisif reste le même que pour la Specification : avant de choisir l’outil ou la machine, il faut définir les preuves attendues, les commandes à exécuter et les conditions dans lesquelles le résultat sera accepté.