Coroid utilise le développement piloté par les spécifications: la spécification accompagne un travail depuis la phase de planification jusqu'aux tests et à la révision, afin que chaque étape s'appuie sur la même définition du succès.
Plutôt que de partir d'une simple phrase et de définir les détails au fur et à mesure de l'écriture du code, Coroid transforme la demande en périmètre explicite, exclusions et critères d'acceptation. Ce document devient alors la source de vérité pour le plan, l'implémentation, les tests et la révision finale.
Qu'est-ce que le développement piloté par les spécifications ?
Le développement piloté par les spécifications est une méthode de conception logicielle basée sur une description convenue et testable du résultat attendu. La spécification indique ce qui va changer, ce qui ne doit pas changer, quelles contraintes s'appliquent et comment un réviseur peut constater que le travail est réussi.
Cette approche sépare deux décisions qui sont facilement confondues :
- La spécification définit ce que signifie le succès.
- Le plan d'implémentation définit comment y parvenir.
Cette séparation permet de corriger le périmètre avant même l'existence du code, sans prescrire l'implémentation trop tôt. Dans Coroid, vous pouvez également activer le workflow SDLC optionnel workflow SDLC lorsque vous souhaitez approuver l'intention et la spécification avant de commencer la planification.
Comment fonctionne ce workflow dans Coroid ?
- Décrivez le résultat souhaité. Fournissez à Coroid le résultat attendu, le contexte pertinent ainsi que toutes les contraintes ou objectifs non visés.
- Examinez la spécification. Vérifiez le périmètre, les exclusions et les critères d'acceptation dans l'onglet Spécification du Projet.
- Approuvez le plan. L'architecte transforme le résultat convenu en étapes d'implémentation ordonnées.
- Construisez et vérifiez. Les agents développeurs et QA utilisent les mêmes critères pour implémenter la modification et prouver chaque comportement promis.
- Révisez le pull request. La modification livrée reporte le plan, les résultats des tests, les constatations et les preuves au regard de la spécification initiale.
Le résultat obtenu est une traçabilité allant de l'intention produit jusqu'au code et aux preuves consultables par un réviseur humain. Consultez Comment une Tâche devient-elle un pull request ? pour connaître l'ensemble du parcours d'exécution.
Pourquoi cette étape supplémentaire ?
Une instruction comme « ajouter la mise en cache pour la recherche d'utilisateurs » présente au moins quatre implémentations plausibles et aucune définition du « fait accompli ». Un agent en choisira une au hasard. Que ce soit la vôtre relève de la chance.
La spécification rend ce choix explicite avant le début de l'implémentation, au moment où il est le moins coûteux de changer d'avis.
Elle offre également à la vérification un élément de comparaison. Sans critères d'acceptation, la question « cela fonctionne-t-il ? » se réduit à « les tests passent-ils encore ? », ce qui est bien moins probant.
Que contient une spécification ?
| Élément | Ce qu'il répond |
|---|---|
| Périmètre | Ce qui va changer |
| Hors périmètre | Ce qui ne sera pas modifié volontairement, afin d'éviter toute dérive du périmètre |
| Critères d'acceptation | Comment savoir si cela a fonctionné ? |
| Contexte | Contraintes, conventions et décisions antérieures applicables |
Vous pouvez le lire et l'éditer dans l'onglet Spécification du Projet avant le début de l'exécution. Pour la description du travail et le contexte associé qui alimentent ce processus, consultez Décrire vos besoins.
Exemple concret : de la note de synthèse à la spécification testable
Supposons que la note de synthèse initiale soit la suivante :
Add caching to the user lookup so repeated requests are faster.Elle indique le résultat souhaité, mais laisse des choix importants en suspens. Une bonne spécification transforme ces choix en limites et en contrôles :
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.Le plan peut alors choisir une implémentation, le service QA peut convertir les critères en tests, et le réviseur peut comparer le pull request au comportement promis.
Ce qui fait la qualité des critères d'acceptation
Ils doivent être vérifiables par quelqu'un qui n'était pas présent lors de la discussion.
Faible :
Caching works correctly and performance is improved.Fort :
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.La seconde version indique à l'agent développeur ce à construire, à l'agent QA ce à tester, et vous ce à vérifier sur le pull request. La première laisse chacune de ces décisions ouvertes.
Les limites de périmètre comptent autant que les critères.
La cause la plus fréquente d'une pull request surdimensionnée n'est pas un agent dépassant son périmètre, mais une spécification qui n'indique pas où s'arrête ce périmètre.
Si vous ne souhaitez pas que le module environnant soit refactorisé pendant l'opération, précisez-le. « Ne modifier aucun point d'appel » est une instruction tout à fait légitime et utile.
Erreurs courantes de spécification
| Erreur | Meilleure approche |
|---|---|
| Décrire l'implémentation plutôt que le résultat attendu | Indiquez le comportement et les contraintes, puis laissez le plan déterminer l'implémentation. |
| Utiliser des termes comme « rapide », « sécurisé » ou « fonctionne correctement » | Remplacez-les par un seuil observable, un comportement ou un test. |
| Omettre les éléments non visés | Nommez le code, les interfaces ou les comportements adjacents qui doivent rester inchangés. |
| Combiner des résultats non liés | Découpez le travail afin qu'une tâche aboutisse à une seule pull request pouvant être révisée. |
| Copier un ticket sans vérifier les hypothèses sous-jacentes | Ajoutez le contexte et les décisions que le dépôt ne peut pas révéler. |
Lorsque vous n'êtes pas d'accord avec elle
Modifiez-la. La spécification reste un document dynamique jusqu'au début de l'exécution ; la corriger coûte bien moins cher que de rectifier le code généré à partir de celle-ci.
Si la spécification indique que le travail concerne en réalité deux éléments distincts, découpez-le en deux tâches. Une tâche doit aboutir à une seule pull request que une personne peut réviser en une seule session.
Prochaines étapes
Pour toute modification dépassant le cadre d'une petite modification, la spécification devient un plan. Consultez Tâches, plans, sprints et colonnes, qui explique comment le travail est divisé et approuvé avant l'écriture du code.
Questions fréquemment posées
Une spécification équivaut-elle à une conception technique ?
Non. Une spécification définit le résultat attendu et ses limites. Une conception technique ou un plan d'implémentation décrivent l'architecture et les étapes permettant d'atteindre ce résultat.
Chaque modification nécessite-t-elle une spécification détaillée ?
Non. Une modification mineure et sans ambiguïté peut nécessiter seulement quelques lignes définissant le périmètre et les critères d'acceptation. La spécification doit éliminer les incertitudes significatives, sans ajouter de formalités inutiles.
Qui doit approuver la spécification ?
La personne responsable du résultat doit confirmer que le périmètre et les critères correspondent aux besoins de l'équipe. Les validateurs techniques, en matière de sécurité ou de conformité peuvent participer lorsque leurs contraintes influencent la réussite du projet.
Une spécification peut-elle être modifiée après le début du travail ?
Oui, mais la modification doit générer une nouvelle version et déclencher une révision du plan et du travail associés. Des changements de périmètre non signalés rompent la chaîne d'évidence entre la demande et la pull request livrée.