Le passage des exigences au code est l'endroit où l'adoption des agents échoue en silence. L'agent n'a pas écrit du mauvais code. Le problème, c'est que six semaines plus tard, personne ne peut dire de quelle exigence découle une modification, qui a validé le périmètre, ni quelles preuves le relecteur avait sous les yeux avant de l'accepter. Le code est arrivé vite. La trace, non.
Ce tutoriel construit cette trace délibérément : une chaîne unique qui va d'une exigence écrite jusqu'à une pull request fusionnée, où chaque maillon est quelque chose que vous pouvez ouvrir. Le Spec Kit de GitHub répond au même manque avec des fichiers dans le dépôt. Ce guide y répond avec un système de travail, en s'appuyant sur Sharkly parce qu'il conserve toute la chaîne sur une seule Task, même si le schéma se transpose à n'importe quel outil de suivi capable de porter les mêmes liens. Si vous voulez d'abord la boucle opérationnelle, commencez par notre guide sur la gestion de projet par agents IA.
TL;DR
Un workflow traçable des exigences au code est un workflow où chaque artefact pointe vers l'artefact qui l'a causé : exigence, Task, sous-tâches, exécutions, pull request, acceptation. Dans Sharkly, l'exigence devient une Task, un Agent propose la décomposition en mode Plan et une personne la confirme, chaque sous-tâche s'exécute dans un worktree isolé avec un journal d'exécution, la pull request renvoie à la Task par son ID, et une personne accepte le résultat au regard des critères d'acceptation rédigés au départ. Les agents font la recherche, l'exécution, les tests et le reporting. Les humains donnent la direction, accordent l'autorité et acceptent le résultat.
Ce que « traçable » doit vraiment vouloir dire
La traçabilité n'est pas un rapport que l'on génère à la fin. C'est une propriété de la chaîne : chaque maillon existe à cause du précédent, et vous pouvez la parcourir dans les deux sens. Six maillons suffisent à couvrir une fonctionnalité.
| Maillon | Où il se trouve | Ce qui le relie au maillon précédent |
|---|---|---|
| Exigence | Description de la Task, type Requirement ou User Story | La personne qui l'a rédigée |
| Décomposition | Sous-tâches rattachées à la Task parente | Proposition en mode Plan confirmée |
| Exécution | Exécutions de la Task et journal d'exécution | Assignation plus un statut prêt |
| Preuves | Commentaire de l'Agent avec les vérifications et les résultats | L'exécution qui l'a produit |
| Modification | Pull request | ID de la Task dans la branche, le titre ou le corps |
| Acceptation | Changement de statut par une personne identifiée | Revue au regard des critères d'acceptation |
Si un maillon manque, la chaîne n'est que décorative. Le manque le plus fréquent concerne le dernier : une pull request fusionnée prise pour une acceptation alors que personne n'a comparé la modification à l'exigence.
Étape 1 : rédiger l'exigence sous forme de Task
Une Task est l'unité de base du travail suivi dans Sharkly, et un Space configuré pour le développement logiciel démarre avec les types de tâches Requirement, Bug, Task et User Story. Utilisez Requirement ou User Story pour la Task parente. Le type détermine les champs personnalisés et les statuts de Workflow applicables, de sorte qu'une Requirement peut porter son propre statut de revue sans polluer le workflow des Bug.
C'est la description qui porte tout le poids. Rédigez-la pour quelqu'un qui n'a jamais vu la conversation : pourquoi le travail compte, ce qui entre ou non dans le périmètre, les fichiers concernés ou le comportement observé, les décisions déjà prises, et la manière dont la complétion sera évaluée. Cette dernière ligne, ce sont les critères d'acceptation, l'ancrage du sixième maillon. Si vous ne pouvez pas encore les écrire, l'exigence n'est pas prête, et c'est exactement à cela que sert le Backlog : une Task assignée à un Agent ne démarre pas tant qu'elle y reste.
Rattachez les dépôts au niveau du Space pour que chaque sous-tâche en hérite. Un Agent sans liaison de dépôt retombe sur les dépôts Git du Space, ce qui est exactement ce que vous voulez pour une fonctionnalité composée de plusieurs Tasks.
Étape 2 : laisser un Agent proposer la décomposition, puis la confirmer
Ouvrez le chat Agent de la Task et basculez la session en mode Plan. En mode Plan, l'Agent peut proposer des actions que vous validez, et Sharkly ne crée la Task et les sous-tâches prévues qu'après confirmation de la proposition. Vous pouvez confirmer sans démarrer, ou confirmer et lancer le travail.
C'est le maillon que la plupart des équipes sautent, et c'est lui qui rend la décomposition traçable plutôt qu'improvisée. La proposition est visible avant de devenir du travail : supprimez la sous-tâche qui élargit le périmètre, ajoutez l'étape de migration que l'Agent a oubliée. Les sous-tâches restent dans le même Space que leur parent, et Sharkly refuse l'auto-parenté et les cycles, de sorte que la hiérarchie reste un arbre.
Utilisez un seul Agent pour une exigence qu'un seul rôle peut couvrir. Utilisez une Crew quand le leader doit interpréter l'objectif, impliquer d'autres membres Agent comme un rédacteur de tests, et ramener leurs résultats dans une même Task. Pour une modification de trois fichiers, la Crew ajoute des pièces mobiles sans ajouter de traçabilité. Notre guide sur les Crews de Sharkly détaille le modèle « le leader d'abord ».
Recopiez dans la description de la Task tout ce qui a été décidé dans le chat. Le chat d'une Task n'est pas un commentaire et n'apparaît pas dans Activity ; une décision qui n'existe que là reste donc invisible pour la chaîne.
Étape 3 : exécuter en isolation, avec une trace
Assignez chaque sous-tâche à un Agent via le contrôle Assignee, puis sortez-la du Backlog. Sharkly vérifie la catégorie de statut et l'aptitude à l'exécution, met l'exécution en file d'attente et l'envoie vers le Computer sélectionné, où le service local prépare un répertoire de tâche isolé et démarre le Runtime.
Deux détails garantissent l'honnêteté de ce maillon. L'exécution inclut le titre et la description de la Task, les commentaires récents, ainsi que le Workflow du type de Task avec ses statuts autorisés : l'Agent travaille donc à partir de l'exigence, et non d'une paraphrase. Et chaque exécution adossée à un dépôt dispose de son propre worktree en mode Temporary, si bien que des sous-tâches parallèles ne peuvent pas s'écraser mutuellement. Notre article sur l'exécution d'agents en parallèle sans conflits de fusion explique pourquoi l'isolation est ce qui rend la répartition sûre.
La progression, les événements de trace et le résultat reviennent dans la Task. Le journal d'exécution consigne la raison de la mise en file d'attente, l'heure de début et de fin, les appels d'outils et les événements du Runtime, la source du déclencheur et les détails des échecs. Ce journal, c'est le quatrième maillon.
Étape 4 : relier la pull request par son ID
Connectez une seule fois l'organisation GitHub, puis placez l'ID de la Task dans le titre de la pull request, dans la description ou dans le nom de la branche source. Un simple SH-312 ou Fixes SH-312 crée le lien. Les linkbacks ajoutent en commentaire l'URL de la Task sur la pull request, activés par défaut pour les dépôts privés.
Voyons maintenant la limite, car elle compte pour la traçabilité : des mots comme fixes ou closes n'ont aucune signification supplémentaire, et fusionner une pull request ne change pas le statut de la Task. Sharkly relie la modification à la Task ; il ne décide pas que la Task est terminée. Le statut reste une décision humaine, ce qui est tout l'intérêt du sixième maillon. Notre tutoriel sur l'assignation d'un ticket Jira à un agent IA et l'obtention d'une PR en retour montre le même lien, vu du côté de l'outil de suivi.
Étape 5 : relire au regard de l'exigence, puis accepter
Un Agent peut laisser une Task en attente de revue humaine, et ce signal arrive dans l'Inbox de la personne responsable, sous Primary. Lisez trois choses dans l'ordre : les critères d'acceptation de l'étape 1, le commentaire de l'Agent listant les vérifications effectuées et ce qui reste incertain, puis le journal d'exécution. Seulement ensuite, le diff.
Si une Task de test distincte vérifie la modification, consignez explicitement cette relation. Les Owners et Admins d'organisation peuvent créer des types de liens personnalisés, et l'exemple donné par la documentation, validates / is validated by, constitue l'arête de traçabilité de ce maillon. Les relations ne changent pas le statut à elles seules : l'acceptation doit donc toujours être un changement de statut effectué par une personne.
Une règle de catégorie vous protège ici : déplacer une Task vers Completed la marque comme terminale, mais n'annule pas une exécution déjà active. Si l'Agent travaille encore, annulez d'abord, puis décidez.
Où la chaîne se rompt
Le workflow ci-dessus comporte trois points de rupture connus, et ils méritent d'être énoncés clairement.
Des conclusions laissées dans le chat. Les sessions d'Agent Chat autonomes appartiennent à la personne qui les a créées. Si la conception a été arrêtée là, la Task n'en sait rien.
Des exécutions lancées hors Task. L'action Run Agent d'un workflow d'automatisation ne crée pas de Task ; l'exécution est enregistrée sur l'Agent. Très bien pour une vérification nocturne, inadapté au travail de fonctionnalité.
Des fichiers au lieu d'une trace. Les spec.md, plan.md et tasks.md de Spec Kit forment une chaîne solide pour un développeur travaillant seul dans un seul dépôt. Utilisez-les quand l'équipe se résume à vous. Utilisez un système de travail partagé quand une deuxième personne doit relire, accepter ou demander ce qui s'est passé sans ouvrir votre copie locale. Sharkly ne remplace pas Claude Code, Codex ou d'autres outils d'exécution ; c'est la couche qui garde la chaîne visible autour d'eux. La documentation approfondit chaque concept sur docs.sharkly.ai.
FAQ
« Des exigences au code », est-ce que cela signifie que l'Agent rédige l'exigence ? Non. C'est une personne qui rédige l'exigence et ses critères d'acceptation. Un Agent peut explorer le code et proposer une décomposition en mode Plan, mais la proposition ne devient des Tasks qu'après confirmation par une personne.
Puis-je garder l'exigence dans Jira et obtenir quand même la traçabilité ? Oui. L'import et la synchronisation Jira conservent l'outil de suivi que lit votre organisation, tandis que Sharkly détient la trace d'exécution. Notre article sur les alternatives à Jira pour les équipes humains-agents couvre le cas où l'outil de suivi lui-même est à remplacer.
Que se passe-t-il si la pull request est fusionnée avant la revue ? Le statut de la Task ne change pas : la chaîne montre donc une Task non acceptée accompagnée d'une modification fusionnée. C'est le bon signal : une personne doit encore une décision.
Quelle taille doit avoir la première fonctionnalité traçable ? Une exigence, deux ou trois sous-tâches, un Agent. Notre tutoriel sur la gestion de projet avec Claude Code déroule la boucle de bout en bout sur une seule Task.
