Développement axé sur les spécifications dans Jira
Le développement axé sur les spécifications consiste à rédiger une spécification structurée avant qu'un agent ne procède au développement. Ainsi, celui-ci crée exactement ce qui est prévu, plutôt qu'une hypothèse plausible. Dans Jira, cette spécification est intégrée au ticket sur lequel vous travaillez déjà, dès lors qu'elle reflète une intention réelle : résultats, périmètre, contraintes et critères d'acceptation. Un ticket peut contenir la spécification complète d'une tâche, ou une partie d'une spécification de fonctionnalité plus vaste répartie sur plusieurs tickets.
Ce guide explique ce qui rend une spécification prête à être traitée par un agent, pourquoi le ticket est le support idéal pour l'accueillir, et comment rédiger votre première spécification. En résumé, le développement axé sur les spécifications dans Jira vous apporte trois avantages :
une source de référence unique à partir de laquelle l'agent effectue le développement et sur laquelle le réviseur effectue ses vérifications
des critères d'acceptation qui définissent ce qui est considéré comme « terminé » tant pour l'agent que pour le réviseur
moins de retouches, car l'intention est clairement définie avant même que l'agent ne rédige la moindre ligne de code
Qu'est-ce que le développement axé sur les spécifications ?
Le développement axé sur les spécifications est une pratique qui consiste à rédiger une spécification structurée définissant ce qu'il faut développer et comment mesurer la réussite. L'agent se charge ensuite de l'implémenter, plutôt que de devoir deviner à partir d'un simple prompt.
La spécification devient la source de référence. Elle guide la planification, le développement et la vérification. Dans Jira, ces trois étapes se déroulent sur le même ticket. Ce concept est antérieur à l'IA, puisqu'il trouve son origine dans la conception d'API et la pratique des méthodes formelles, où l'on définit le comportement avant de le développer.
La définition évolue constamment à mesure que les outils gagnent en maturité. Considérez-la donc comme une pratique, et non comme un format de spécification figé. Ce qui reste constant, c'est le principe fondamental : définir le travail à effectuer avant que l'agent ne procède au développement.
La différence réside dans le moment où l'on lève les ambiguïtés. La programmation intuitive les résout une fois le code écrit, tandis que le développement axé sur les spécifications (SDD) les résout en amont.
Programmation intuitive : vous guidez l'agent à l'aide de prompts et acceptez ce qu'il renvoie. Ainsi, le périmètre, les contraintes et les limites qu'il suppose n'apparaissent qu'une fois le code écrit.
Développement axé sur les spécifications : vous définissez d'abord l'intention, les contraintes et les critères d'acceptation, afin que l'agent développe le livrable à partir d'une définition plutôt que d'une intuition, et que la vérification s'effectue par rapport à cette même définition, directement sur le ticket concerné.
Pour un code destiné à être intégré dans une base de code réelle, un agent dont le contexte n'est pas bien défini risque de résoudre le ticket de manière trop littérale et de passer à côté de la contrainte essentielle. C'est là que le travail de reprise commence.
Les prompts ont tendance à confondre deux notions : la spécification correspond à ce que l'on développe, tandis que le plan décrit la méthode de développement. Le développement axé sur les spécifications définit d'abord le « quoi », puis détermine le « comment » à partir de là. C'est l'étape que le mode de planification des outils de codage basés sur l'IA omet souvent : il élabore la méthode directement à partir d'un prompt, généralement sans s'appuyer sur aucune spécification validée en amont.
Ce mode peut faire office de spécification simplifiée, mais il définit la manière de procéder à partir d'un prompt donné sur le moment, et non à partir d'un cahier des charges convenu qui accompagne le ticket tout au long de son traitement.
Pourquoi les spécifications sont importantes pour le codage basé sur l'IA ?
Lorsque la génération de code devient peu coûteuse, le plus difficile n'est plus d'écrire des lignes de code, mais de définir ce qu'il faut développer. C'est pourquoi la spécification, et non le prompt, devient l'artefact le plus déterminant que vous produisez.
Un prompt unique laisse des lacunes à l'agent, qui les comble avec des suppositions et produit un code qui semble correct, mais qui résout le mauvais problème. Une spécification comble d'abord ces lacunes, de sorte que l'agent s'appuie sur une définition plutôt que sur une supposition. Dans Jira, cette spécification est le ticket que votre équipe planifie, assigne et examine déjà.
Que contient une spécification à partir de laquelle un agent peut développer un produit ?
Une spécification prête à être mise en oeuvre par un agent répond aux questions qu'un bon ingénieur se poserait avant de se lancer. Dans Jira, ces informations figurent dans le résumé, la description, les exigences associées et les critères d'acceptation du ticket. Six éléments sont essentiels :
Résultats : ce que le changement doit accomplir, dans des termes qu'un réviseur peut vérifier.
Périmètre : ce qui est inclus et, tout aussi important, ce qui est exclu.
Contraintes : les limites d'architecture, de sécurité et de performances à respecter.
Décisions antérieures : contexte déjà établi, l'agent ne le remet donc pas en question.
Division des tâches : le travail divisé en étapes suffisamment petites pour être vérifiées.
Critères d'acceptation : la définition vérifiable de l'état « Terminé » vers laquelle l'agent tend et sur laquelle repose l'évaluation. Dans Jira, ils se trouvent sur le ticket, et une revue de code basée sur l'IA peut vérifier la conformité du changement par rapport à ceux-ci avant qu'il ne soit transmis à un humain.
Comment le ticket devient la spécification dans Jira
Un ticket bien structuré peut servir de spécification sur laquelle l'agent s'appuie pour développer et effectuer ses révisions. La spécification peut également figurer dans un document associé, ce qui correspond au mode de fonctionnement de nombreux outils SDD. Jira permet simplement de la placer au même endroit que le ticket exécuté. Un ticket est considéré comme une spécification lorsqu'il comporte les six éléments ci-dessus. À l'inverse, il est jugé non conforme lorsqu'il ne contient qu'une seule ligne demandant de « corriger le bug de connexion ».
Le fait de conserver la spécification sur le ticket présente un avantage structurel : elle est hébergée au même endroit que le travail effectué, ce qui rend son abandon plus difficile que celui d'un fichier Markdown stocké dans un dépôt que personne ne rouvre. Cela ne signifie pas pour autant qu'elle s'ajuste automatiquement, mais simplement que la spécification et le ticket restent toujours associés.
Tout est regroupé : le résumé, la description, les exigences associées sur Confluence et les critères d'acceptation. L'agent et le réviseur peuvent ainsi consulter ces informations dans un même espace.
Un fichier de dépôt, en revanche, est distinct de l'espace où le travail est suivi, révisé et clôturé ; il devient donc obsolète dès que le plan change.
Une fois que l'agent a terminé son travail, ce ticket devient l'interface de révision, c'est-à-dire l'endroit où votre équipe se met d'accord sur les exigences et les questions en suspens.
Jira définit des plans intégrant des exigences, des tâches et des estimations claires.
Comment le Planificateur Jira génère une spécification structurée ?
La section précédente traitait des bases : comment transformer soi-même un ticket en une spécification. Le Planificateur Jira est destiné aux initiatives complexes impliquant plusieurs équipes, pour lesquelles la rédaction manuelle de chaque spécification n'est pas envisageable à grande échelle. Il part donc de l'initiative et la divise en tickets structurés, chacun comportant son propre cahier des charges.
Le Planificateur Jira est un outil d'accélération, et non une solution de référence. La méthode SDD de référence consiste en l'élaboration d'un ticket bien défini accompagné de critères d'acceptation, et toutes les équipes sont déjà en mesure de le faire aujourd'hui. Le Planificateur, quant à lui, accélère la partie la plus difficile de ce travail : transformer une demande complexe et ambiguë en une spécification structurée.
Pour les projets complexes, le Planificateur Jira se base sur le Teamwork Graph, qui intègre votre base de code, l'historique de Jira et Confluence, ainsi que le contexte de l'équipe, afin de définir les exigences et générer une spécification technique structurée dans Confluence, sur laquelle un développeur ou un agent de codage peut s'appuyer. Un plan a plusieurs publics : il doit donc être lisible par un humain, et utile à un agent.
Voici ce qu'un plan accomplit :
Il fournit un espace partagé sur lequel vous et votre équipe pouvez collaborer, afin de vous mettre d'accord avant qu'un agent ne se mette à l'œuvre.
Il extrait le contexte de l'ensemble de votre travail, de sorte que la spécification s'appuie sur les connaissances de votre équipe au lieu d'un prompt vierge.
Il génère une spécification claire pour l'humain et facile à analyser pour un agent, ce qui permet d'utiliser le même artefact à la fois pour la révision et l'exécution.
Il conserve la spécification dans Confluence, où elle est associée au ticket, afin que l'intention et les décisions soient bien consignées.
Le Planificateur Jira transforme les idées générales en spécifications structurées et prêtes à être traitées par les agents
Cet outil est disponible en accès anticipé : inscrivez-vous sur la liste d'attente
Comment rédiger votre première spécification destinée aux agents dans Jira
Prenez un ticket et transformez-le manuellement en une spécification destinée aux agents, en utilisant ces six éléments comme checklist.
Partez d'un ticket. Indiquez dans la description le résultat attendu, le périmètre et les contraintes, et ne vous contentez pas d'un simple titre.
Transformez l'intention en spécification structurée. C'est là le véritable travail de développement axé sur les spécifications. Il s'agit de traduire le contexte préalable en résultats, en périmètre et en contraintes sur le ticket, afin que l'agent en hérite la définition.
Rédigez des critères d'acceptation vérifiables. Ce sont les engagements que l'agent s'efforce de respecter et que le réviseur vérifie. La plupart des critères nécessitent souvent plusieurs itérations avant de devenir vérifiables.
Attribuez-le à un agent de codage. Un ticket de type « spécification » fournit à l'agent suffisamment d'éléments pour procéder à l'implémentation et ouvrir une pull request liée à la tâche.
Vérifiez la pull request par rapport aux critères, puis affinez-la. Précisez la spécification là où l'agent a fait des suppositions, et réutilisez ce modèle pour le ticket suivant.
Questions fréquentes concernant le développement axé sur les spécifications
Ai-je besoin du Planificateur Jira pour pratiquer le développement axé sur les spécifications ?
Non. L'essentiel est de disposer d'un ticket bien défini assorti de critères d'acceptation, ce que toutes les équipes sont déjà en mesure de rédiger aujourd'hui. Pour les projets complexes, le Planificateur Jira accélère le processus en partant d'un plan de haut niveau, une initiative, et en le divisant en tickets Jira structurés, chacun avec ses spécifications déjà renseignées, ce qui vous évite de devoir tout rédiger à la main.
Quelle est la différence entre une spécification et des critères d'acceptation ?
La spécification définit l'ensemble du changement : les résultats, le périmètre, les contraintes et le contexte. Les critères d'acceptation en constituent une partie : il s'agit de la définition vérifiable de l'état « Terminé » vers laquelle l'agent tend et à laquelle le réviseur se réfère.
Un très bon prompt est-il suffisant ?
Pour les petites tâches réversibles, c'est souvent le cas. Pour tout ce qui est complexe ou difficilement réversible, un simple prompt oblige l'agent à deviner ce que vous avez omis. Une spécification élimine toute supposition.
La spécification doit-elle figurer dans un fichier de dépôt ou dans un ticket Jira ?
Un ticket permet de conserver la spécification à l'endroit où le travail est suivi, révisé et clôturé. Elle est ainsi moins susceptible de se perdre qu'un fichier Markdown stocké dans un dépôt que plus personne ne consulte.
Le développement axé sur les spécifications ralentit-il les équipes ?
Il demande plus d'efforts au départ, mais évite les reprises par la suite. Pour les projets complexes, ce compromis représente un gain net. Pour les corrections mineures, passez l'étape de la spécification et utilisez directement un prompt.
Quand dois-je rédiger une spécification, et quand puis-je m'en passer ?
Rédigez-en une pour un projet complexe, à fort impact ou difficilement réversible, ou pour tout ce qui présente de réelles contraintes d'architecture ou de sécurité. Passez cette étape pour les petites corrections réversibles, pour lesquelles un prompt rapide est plus efficace.