Demander à un agent de « créer la fonctionnalité » produit souvent du code plausible, mais fondé sur des hypothèses invisibles. Le spec-driven development inverse l’ordre : l’équipe clarifie d’abord le résultat attendu, puis transforme cette intention en plan, tâches et critères vérifiables.
Cette approche ne consiste pas à rédiger un cahier des charges de cinquante pages. Elle crée juste assez de structure pour que le modèle, le développeur et le reviewer parlent du même problème.
Faire de l’intention un artefact versionné
La spécification décrit ce que le produit doit permettre et pourquoi. Elle contient les utilisateurs concernés, les scénarios, les règles métier, les cas limites et les critères d’acceptation. Elle évite d’imposer trop tôt une bibliothèque ou un schéma de base de données.
Stockée dans le dépôt, elle évolue avec la pull request. Les commentaires portent alors sur des décisions explicites plutôt que sur l’interprétation d’un prompt disparu dans un historique de chat.
Séparer spécification et plan technique
Le plan traduit les exigences dans l’architecture existante : composants touchés, données, interfaces, migrations, sécurité, tests et déploiement. Cette séparation permet de changer la solution technique sans perdre le besoin métier.
Avant l’implémentation, demandez à l’agent de relever les contradictions, les termes non définis et les dépendances manquantes. Une question posée à ce stade coûte moins cher qu’une refonte après génération.
Découper en tâches vérifiables
Une tâche utile produit un résultat observable : ajouter une migration réversible, exposer un endpoint avec son test de contrat, modifier un composant avec un scénario d’accessibilité. « Faire le backend » est trop large pour suivre la progression ou isoler une erreur.
Chaque tâche doit préciser ses fichiers probables, ses dépendances et sa condition de fin. L’ordre doit protéger les invariants : schéma et tests de contrat avant l’interface, garde-fous avant l’automatisation.
Transformer les critères en tests
Les scénarios de la spécification fournissent une base naturelle pour les tests. Associez chaque exigence importante à au moins une vérification automatisée ou à une procédure de validation manuelle. Les contraintes non fonctionnelles — performance, permissions, compatibilité, observabilité — méritent aussi des critères.
L’agent peut proposer les tests, mais il ne doit pas être seul juge de leur pertinence. Un test généré à partir de la même mauvaise hypothèse que le code peut valider une erreur avec beaucoup d’assurance.
Garder le contexte spécifique au dépôt
Les instructions persistantes décrivent la structure, les commandes de build, les conventions et les zones interdites. La spécification ne doit pas recopier tout ce contexte. Elle référence les règles stables et se concentre sur le changement en cours.
Notre méthode de context engineering pour agents IA aide à sélectionner les fichiers et les contrôles utiles sans noyer le modèle.
Éviter la dérive entre texte et code
À chaque modification importante, comparez spécification, plan, tâches et implémentation. Si le code révèle une contrainte nouvelle, mettez à jour l’artefact concerné. Une spécification figée devient rapidement une nouvelle documentation trompeuse.
La revue doit chercher les exigences sans code, mais aussi le code sans exigence. Cette seconde catégorie révèle les ajouts opportunistes, les abstractions prématurées et les changements de périmètre.
Utiliser les outils sans adopter une religion
GitHub Spec Kit formalise un enchaînement Spec → Plan → Tasks → Implement et ajoute des étapes de clarification et d’analyse. Il peut servir de point de départ, mais une équipe peut appliquer les mêmes principes avec de simples fichiers Markdown et sa CI.
Le bon niveau de formalisme dépend du risque. Une correction locale exige quelques critères précis ; une migration de paiement ou d’authentification justifie un plan détaillé, une stratégie de retour arrière et plusieurs validations humaines.
Workflow minimal
- Écrire le problème, les utilisateurs et le résultat attendu.
- Clarifier les ambiguïtés et cas limites.
- Définir les critères d’acceptation.
- Produire un plan adapté au dépôt existant.
- Découper en petites tâches ordonnées.
- Implémenter avec tests et contrôles.
- Comparer les artefacts avant la revue finale.
Signaux d’alerte
- La spécification nomme surtout des technologies et peu de comportements.
- Aucun critère ne décrit l’échec ou l’absence de permission.
- Le plan ignore migration, observabilité ou retour arrière.
- Les tâches sont trop larges pour être vérifiées séparément.
- Le code ajoute des fonctionnalités absentes du besoin.
