Spec-Driven Development : du besoin aux tests dans Symfony
Transformez une demande ambiguë en comportements vérifiables : spécification, plan, contre-exemples et revue sur un projet Symfony.
« Ajoute un filtre par ingrédients » semble être une petite demande. Pourtant, plusieurs réponses seraient possibles : rechercher au moins un ingrédient, exiger tous les ingrédients, proposer seulement les recettes réalisables avec son placard ou exclure certains allergènes. Un agent peut coder très vite une de ces options sans avoir choisi celle que l’utilisateur attendait.
Le AI Coding Radar de Theodo présente le Spec-Driven Development parmi ses pratiques. Voici une application concrète à Symfony : transformer un besoin en quelques comportements vérifiables, puis garder leur lien avec les tests et la revue de code. Les choix et l’exemple de cet article sont indépendants du classement du radar.
Sources consultées le . Les outils évoluent ; les exemples ci-dessous proposent une méthode de travail à adapter au dépôt.
Commencer par la décision qui change le résultat
Dans notre exemple, la règle retenue est un ET logique : cocher chocolat et vanille doit afficher les recettes associées aux deux ingrédients. Il s’agit d’ingrédients principaux renseignés dans le catalogue. D’autres produits peuvent être nécessaires ; la fonctionnalité ne promet pas qu’un gâteau est réalisable avec les seules cases cochées.
Ce paragraphe règle déjà plusieurs ambiguïtés avant de parler de SQL, de formulaire ou de composant JavaScript. Un désaccord à ce stade coûte une discussion. Découvert après livraison, il peut nécessiter de modifier les textes, la requête et les tests en même temps.
Écrire une spécification courte et réfutable
Objectif
Trouver des recettes à partir de leurs ingrédients principaux.
Règles
F1. Plusieurs ingrédients cochés sont combinés avec ET.
F2. Seules les recettes publiées du site et de la langue demandés sont visibles.
F3. Le filtre est appliqué avant la pagination de 24 résultats.
F4. Un ingrédient inconnu provoque une réponse 400.
F5. Sans sélection, le catalogue publié reste accessible.
F6. La sélection est conservée lors du changement de page.
F7. Le formulaire et sa remise à zéro fonctionnent sans JavaScript.
Limites
La disponibilité en stock, les substitutions et les allergies sont hors périmètre.
Exemples attendus
- A : chocolat + vanille, publiée => retenue.
- B : chocolat seulement, publiée => exclue si chocolat et vanille sont cochés.
- C : chocolat + vanille, brouillon => exclue.
- D : chocolat + vanille, autre site => exclue.
Ces identifiants servent à la discussion et à la revue. Ils n’imposent aucun outil particulier. La spécification doit être assez précise pour qu’une autre personne puisse expliquer pourquoi un résultat passe ou échoue, même sans lire l’implémentation.
Construire le plan depuis le dépôt existant
Demandez ensuite où réside chaque responsabilité : le contrôleur valide les paramètres HTTP, un service construit la recherche et le gabarit conserve la sélection. Le plan doit nommer les points d’entrée trouvés dans le projet et expliquer ce qui est réutilisé. Une proposition qui invente une seconde couche de catégories alors qu’elle existe déjà mérite une correction avant le codage.
Les invariants du projet ont une place différente des nouvelles exigences. Préserver les contrôles de publication est un invariant. Ajouter une sélection multiple est le changement demandé. Cette distinction aide à détecter les effets de bord : une nouvelle page qui fonctionne tout en exposant les brouillons reste une régression.
Le projet GitHub Spec Kit fournit un cadre pour formaliser besoin, plan, tâches et vérification. Son guide pour les dépôts existants conseille de commencer par un changement délimité et de s’appuyer sur les règles déjà présentes. On peut appliquer cette discipline sans installer le toolkit : une fiche de fonctionnalité et les outils habituels du dépôt suffisent pour un premier essai.
Dériver les tests des contre-exemples
Le cas A seul ne démontre pas la règle ET : une implémentation en OU le renverrait aussi. Le cas B est indispensable pour distinguer les deux comportements. Ajoutez également une recette contenant seulement de la vanille et vérifiez qu’elle reste exclue lorsque les deux cases sont cochées.
Pour F3, créez davantage d’éléments non correspondants que la taille d’une page, puis vérifiez qu’une recette correspondante plus ancienne apparaît malgré tout. Un filtre appliqué après avoir chargé les 24 derniers éléments échouerait. Pour F2, préparez des brouillons et des contenus d’un autre site ; leur absence doit faire partie des assertions.
Un test navigateur complète cette couverture pour F6 et F7 : sélectionner, soumettre, passer à la page suivante, revenir, puis tout effacer. Les tests d’application Symfony permettent de contrôler les réponses HTTP ; un navigateur apporte une preuve supplémentaire sur les interactions. Gardez une base de test isolée pour les données nécessaires à ces scénarios.
Relire le code avec la spécification à côté
Une revue utile suit le trajet de la demande : validation des clés d’ingrédients, requête sur le bon périmètre, ordre stable, pagination et rendu. Elle cherche les contre-exemples oubliés. Le nombre de tests et la taille du diff ne remplacent pas cette lecture.
F1 — combinaison ET : scénario positif + contre-exemples chocolat seul et vanille seule.
F2 — publication et site : fixtures dédiées, aucune fuite dans les résultats.
F3 — pagination : résultats filtrés globalement avant découpage.
F6/F7 — parcours : sélection et remise à zéro vérifiées sans JavaScript.
Limite connue — ces filtres ne prouvent pas l'absence d'allergènes.
Demandez aussi à l’agent de signaler les divergences découvertes. Un catalogue incomplet ou une route déjà utilisée peut obliger à revoir le plan. La bonne réaction est d’ajuster le choix produit avec une trace claire ; modifier silencieusement la règle pour faire passer les tests inverse le sens de la démarche.
Entretenir la spécification au bon niveau
Quand la règle passe de ET à OU, mettez à jour l’interface, les exemples et les contrôles associés dans le même changement. Si la fiche n’est conservée que pour l’historique, indiquez-le. Évitez de garder un document présenté comme une référence active alors qu’il ne décrit plus le produit.
Cette méthode est particulièrement utile lorsque quelques mots cachent une décision métier ou un risque de régression. Pour une correction de libellé, une fiche détaillée ajoute peu de valeur. Ajustez la formalisation au changement : le but est de réduire les interprétations erronées avant qu’elles deviennent du code à maintenir.