# Développement basé sur les spécifications

> Comment les ingénieurs d'Asana ont transformé les requêtes répétées aux agents de codage en un processus durable basé sur des spécifications, et ce que nous avons appris après environ trois mois d'utilisation en interne.

Source: https://asana.com/fr/inside-asana/spec-driven-development

## Développement axé sur les spécifications : les points positifs et ce que nous avons appris après trois mois

_Au bout de trois mois, nous avions une vision plus claire des cas où la structure supplémentaire était utile et de ceux où elle constituait un frein._

L'un de nos ingénieurs préparait une migration de données et a décidé d'utiliser le développement basé sur les spécifications (SDD) pour planifier le travail. Le SDD devait l'aider à détecter les lacunes à un stade précoce, à faciliter la révision de l'approche et à donner des orientations claires à l'agent. Le plan qui en a résulté était détaillé et, sur le papier, semblait assez raisonnable. Il structurait le travail de la manière suivante :

**Problème → Recherche → Spécifications → Examen → Mise en œuvre → Vérification**

Au fur et à mesure de l'avancement de la mise en œuvre, l'ingénieur s'est rendu compte que deux tâches pouvaient s'exécuter simultanément et créer des champs personnalisés en double. L'approche rendait également le code de plus en plus complexe et difficile à suivre. Heureusement, l'ingénieur a identifié le problème, interrompu la mise en œuvre, rédigé un document de conception d'une page et mentionné quelques collègues pour obtenir leur avis. Ensemble, ils ont examiné la conception et ont trouvé une approche plus sûre.

La spécification initiale a rempli sa mission : elle a permis au projet de continuer à avancer dans la direction initiale. Le problème, c'est que l'orientation était mauvaise. Une spécification détaillée permettait de poursuivre facilement le projet, même lorsque l'idée de départ était fragile. L'agent pouvait développer cette idée plus vite que les autres n'auraient pu s'arrêter pour la remettre en question.

Ce projet a mis en évidence un risque lié à l'ajout de structure : un agent pouvait reporter la même hypothèse erronée de la spécification dans le code et les tests. Les spécifications, le code et les tests étaient cohérents les uns avec les autres, mais cela ne signifiait pas que l’hypothèse sous-jacente était correcte. Pour les décisions plus risquées, une autre personne devait tout de même revenir à l'objectif initial et rechercher les moyens par lesquels l'implémentation pourrait le compromettre.

Néanmoins, les agents se chargeaient de tâches qui duraient plus d’une session, et une simple invite ne suffisait souvent pas pour conserver l’objectif du projet ou sa raison d’être. Cela nous a amenés à créer /spec-driven, un outil de processus centré sur les spécifications. La spécification permettait de conserver l’orientation du projet pour la session suivante. Les scripts apportaient le contexte et effectuaient des vérifications. Lorsqu’une exécution révélait une règle, une vérification ou un élément de contexte manquant, nous pouvions l’ajouter au processus afin que les agents ultérieurs n’aient pas à découvrir à nouveau la même lacune.

Il existe encore de nombreux désaccords quant à savoir si la structure supplémentaire apportée par le SDD en vaut la peine. [Microsoft](https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering) et [AWS](https://aws.amazon.com/blogs/machine-learning/how-frontier-teams-are-reinventing-ai-native-development/) promeuvent le SDD, tandis que [Thoughtworks le décrit comme une approche émergente et controversée](https://www.thoughtworks.com/en-sg/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices), et [les praticiens font état d'expériences mitigées](https://news.ycombinator.com/item?id=45610996). Les détracteurs avertissent que la SDD peut produire plus de Markdown que les ingénieurs ne peuvent en gérer, transformer une spécification détaillée en code écrit en prose ou laisser derrière elle une autre description du système qui s'écarte du code.[1][2][3]

Après trois mois d’utilisation réelle, nous avons appris que la question importante n’était pas de savoir s’il fallait utiliser la SDD. C'était ce qui manquait à l'agent sur ce projet. Parfois, la réponse était une spécification. Parfois, il s'agissait d'un meilleur exemple, d'une vérification automatisée ou d'un ingénieur qui connaissait le domaine.

## Pourquoi nous avons créé /spec-driven

Certains ingénieurs d'Asana avaient déjà testé [GitHub Spec Kit](https://github.com/github/spec-kit/blob/main/docs/reference/workflows.md) et [OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md), mais aucun de ces outils n'a été intégré à leur processus habituel. Nous voulions une version que nous pourrions adapter au fur et à mesure de notre apprentissage et connecter au processus de développement d’Asana.

Le mode plan intégré pouvait déjà analyser la base de code et élaborer un plan d'implémentation utile avant d'apporter des modifications. La SDD a apporté davantage de structure à ce plan : elle a permis de garder le problème, les décisions clés et les critères d'acceptation visibles tout au long de la mise en œuvre et de la vérification.

Avant la mise en œuvre, /spec-driven a rappelé sa compréhension du problème et a soulevé les questions susceptibles de modifier le plan. Cela a donné à l'ingénieur la possibilité de rectifier l'orientation avant qu'il n'y ait de code à réécrire.

Nous avons stocké cet état dans le dépôt afin que les sessions ultérieures n’aient pas à deviner ce qui s’était passé. Nous voulions que les règles du processus soient déterministes, c’est pourquoi les scripts se chargeaient de la tenue des registres et des vérifications. Le modèle s'occupait des aspects qui nécessitaient un jugement : poser des questions, évaluer les compromis et expliquer les décisions.

Le processus comprenait plusieurs commandes. Les ingénieurs utilisaient /spec-driven spec pour traiter les questions en suspens et élaborer une spécification ainsi qu'un plan d'implémentation. Après avoir examiné le plan, ils ont utilisé /spec-driven ship pour le mettre en œuvre, vérifier le résultat et préparer le travail pour qu'il soit évalué. Une machine à états suivait le projet à mesure qu'il passait par ces commandes, de sorte que les sessions ultérieures savaient ce qui s'était passé et ce qui allait suivre.

Dès le départ, nous voulions que /spec-driven soit bien plus qu'un simple moyen de rédiger et de mettre en œuvre des spécifications. Nous voulions également qu'il orchestre des processus avec agents. Il classe les tâches par dépendance et conserve les modifications de fichiers qui se chevauchent dans des cycles d'exécution distincts. Il envoie des tâches indépendantes à plusieurs agents en parallèle, puis utilise les résultats pour décider de ce qui peut être exécuté ensuite.

C'est comme un GPS pour le travail : à tout moment, l'étape suivante est claire et les décisions importantes sont identifiées, ce qui permet d'éviter de se retrouver bloqué.Les ingénieurs d'Asana ont utilisé /spec-driven à la fois de manière « spec-first » et « spec-anchored ». Avec l'approche « spec-first », ils ont utilisé une spécification pour choisir une direction, puis ont cessé de la mettre à jour. Avec l'approche « ancrée sur les spécifications », ils l'ont maintenue à jour au fur et à mesure de l'évolution du travail. Les ingénieurs ont également rédigé des spécifications indépendantes pour certaines parties d'un effort plus vaste, afin qu'une personne puisse utiliser le processus sans demander à toute l'équipe de l'adopter.

## Quand /spec-driven vaut la peine de fournir un effort supplémentaire

La structure supplémentaire s'est avérée particulièrement utile lorsque des informations contextuelles importantes devaient être conservées d'une session à l'autre, lors de transferts ou dans le cadre de nombreuses tâches connexes. Les ingénieurs pouvaient examiner l’évolution du plan, et l’orientation du projet restait accessible lorsque le travail était transféré à une autre session d’agent ou à une autre personne. Deux projets de produits ont conservé des spécifications évolutives pendant environ deux à trois mois : l'un consistait à créer une nouvelle fonctionnalité majeure, l'autre à reporter les dates des sous-tâches aux tâches parentes.

Je viens de terminer une initiative assez importante avec Spec-driven et je pense que cela m'a vraiment aidé ! J'ai travaillé sur le plan pendant environ deux jours, puis j'ai effectué tout le travail d'ingénierie et procédé à la fusion en trois jours.Les spécifications ont facilité les transferts. Une personne reprenant un projet en pause pouvait voir ce que l'équipe essayait de faire, pourquoi elle avait pris cette forme et ce qu'il restait à accomplir. Il n’a pas eu à reconstituer le projet à partir des validations et des discussions.

Les ingénieurs ont également utilisé /spec-driven pour coordonner de gros lots de travail gérés par des agents. Dans la console d’administration d’Asana, où les équipes informatiques des entreprises clientes gèrent les paramètres de sécurité, d’accès, d’intégration et de partage à l’échelle de l’organisation, les ingénieurs l’ont utilisée pour transférer 66 paramètres vers des cadres partagés. Le déplacement de ces paramètres a nécessité environ 150 migrations dans plusieurs cadres de la console d'administration. Chaque migration est devenue un ticket Asana pour un agent cloud, et les ingénieurs les ont exécutées par lots en parallèle, en mettant à jour les tickets restants en fonction des résultats précédents.

L'équipe chargée de cet effort a indiqué que 91 % des migrations n'ont pas nécessité de révision après vérification et que l'ensemble de l'effort a été achevé plus d'un mois plus tôt que prévu initialement.

Une autre migration d'envergure n'a nécessité qu'une brève instruction. La différence résidait dans le degré de clarté déjà apporté par la base de code. Elle contenait des exemples que les agents pouvaient suivre et des vérifications permettant de contrôler le résultat. Les agents de la console d’administration n’ont pas réussi à déterminer toutes les exigences à partir du code, de sorte que le travail nécessitait davantage de structure.

L'approche /spec-driven a également contribué à la réalisation rapide de prototypes. Les ingénieurs ont pu répondre rapidement à un nombre suffisant de questions ouvertes sur le produit pour concevoir une expérience fonctionnelle de bout en bout. Les chefs de produit et les concepteurs pouvaient tester un prototype avant que les ingénieurs n'investissent dans la stabilisation du produit en production. Si les ingénieurs décidaient de conserver le code, celui-ci devait généralement faire l'objet d'un nettoyage approfondi avant de pouvoir être fusionné. À ce stade, le prototype avait déjà permis de déterminer si l'idée méritait d'être poursuivie.

## Ce que les premiers chiffres ont révélé

Nous avons encouragé tout le monde à essayer /spec-driven une fois, mais nous n’avons pas exigé une utilisation continue. Environ la moitié des ingénieurs l'ont essayée. Au cours du dernier mois, l'utilisation hebdomadaire a varié de 30 à 50 ingénieurs. Parmi les compétences des agents intégrées et développées par Asana que les ingénieurs ont invoquées directement, /spec-driven s'est classée à la troisième place. L’utilisation continue était encourageante, mais elle ne nous indiquait pas comment /spec-driven avait influencé la livraison.

La vélocité en ingénierie est notoirement difficile à mesurer. Les demandes d'extraction et les ajouts de code d'implémentation sont des indicateurs imparfaits de la productivité, mais nous pensons qu'ils constituent souvent des mesures utiles pour évaluer la tendance. Pour la comparaison de la vélocité, nous avons examiné sept ingénieurs et 524 demandes d'extraction fusionnées sur quatre mois. Nous avons comparé le travail effectué avant et après la première utilisation évidente de /spec-driven par chaque ingénieur et avons exclu les spécifications, les plans et autres éléments du processus. Pour la comparaison des annulations, nous avons classé une pull request comme étant /spec-driven lorsqu’elle modifiait les fichiers du projet du processus.

Le nombre de demandes d'extraction par semaine a augmenté de 38 %, et les ajouts de code d'implémentation ont été multipliés par 2,66. Une courte période de volume exceptionnellement élevé a influencé le résultat des ajouts. Même sans cette période, les ajouts étaient encore 66 % plus élevés. Le taux de réversion explicite était également légèrement inférieur : 1,2 % pour le travail /spec-driven, contre 1,66 % pour les autres demandes d'extraction.

Une augmentation du volume de code n’est pas nécessairement un bon résultat. Un agent peut produire une implémentation volumineuse alors qu'une implémentation plus petite suffirait. Par conséquent, l'augmentation du nombre d'ajouts de code pourrait refléter des solutions inutilement volumineuses plutôt qu'une plus grande quantité de travail terminé. La révision normale nous a permis de vérifier ce mode de défaillance. Nous avons compté sur les relecteurs pour signaler les implémentations qui étaient plus importantes ou plus complexes que ce que le problème nécessitait, et ces modifications ont tout de même été validées. Cela nous a permis de penser que les implémentations surdimensionnées n’étaient pas à l’origine de l’ensemble de l’augmentation.

Ces comparaisons n’ont pas été contrôlées, et nous n’avons pas pu séparer l’effet de /spec-driven de la combinaison de projets ou des améliorations plus générales apportées aux outils des agents. Malgré ces limites, nous sommes ressortis encouragés par les résultats.

## Ce qui reste à améliorer

### La vérification des documents peut devenir un frein

La création d’une spécification prenait entre 30 minutes et plusieurs jours, selon la familiarité de l’ingénieur avec le domaine concerné, ainsi que la complexité et le risque du projet. Les ingénieurs pouvaient utiliser /spec-driven pour qu'un agent rédige rapidement des spécifications, mais leur vérification prenait tout de même du temps.

Lors d'un effort, un ingénieur a passé des heures à examiner une demande d'extraction (pull request) avec research.md, un fichier de travail dans lequel l'agent a enregistré ce qu'il avait appris de la base de code, de la documentation et des décisions antérieures avant de rédiger la spécification. Certaines de ces informations étaient vagues, imprécises ou légèrement erronées.

Cet examen a montré que nous n’étions pas parvenus à un accord sur la question de savoir si ces fichiers étaient des notes de travail temporaires ou une documentation sur laquelle les futurs ingénieurs devraient pouvoir se fier. Certains ingénieurs appréciaient l'enregistrement de la manière dont une décision avait été prise. D'autres craignaient que le fait d'enregistrer des recherches imparfaites ne leur donne un caractère officiel.

Au sein d'une équipe d'infrastructure, la révision des spécifications est devenue un nouvel obstacle avant la mise en œuvre.

J'avais l'impression que les commandes et le processus étaient beaucoup plus compliqués et prenaient plus de temps que de simplement générer un plan, puis de le mettre en œuvre.La plupart des personnes chargées de la révision ne voulaient pas lire une longue spécification, puis examiner le code en plus. Au moment où le travail atteignait le stade de la pull request, le transfert devait résumer la décision, les raisons pour lesquelles nous l'avions prise, les éléments qui semblaient risqués et la manière dont nous avions vérifié le résultat. Si l'orientation elle-même devait être examinée, nous devions le demander plus tôt, alors qu'il était encore facile de la modifier.

### Une spécification utile évolue au même rythme que le projet

Les ingénieurs ont continué à apprendre au fur et à mesure de la mise en œuvre du plan. Mettre à jour la spécification en fonction de ce qu'ils avaient appris demandait un certain effort. Son niveau de détail a été utile lors de la mise en œuvre, car il montrait ce que l'agent pensait être en train de créer. Par la suite, une grande partie de ces détails répétaient le code.

Nous pensons désormais qu'une spécification fonctionnelle doit s'étoffer tant que le projet est incertain et se réduire une fois que le code peut expliquer l'implémentation. Ce qui reste devrait aider le prochain lecteur à comprendre la conception, les décisions importantes, les contraintes et les risques non résolus.

Les spécifications terminées soulèvent une question connexe : que devrait-il leur arriver ? Nous avons attendu trop longtemps pour y répondre. Les laisser dans le monorepo facilite leur identification, mais laisse également des documents dont personne n'est responsable. Nous les déplaçons vers une archive distincte. Nous avons encore besoin d'un transfert plus concis qui conserve l'essentiel pour plus tard. Si un document créait plus de travail qu’il n’en épargnait, il n’était pas utile.

## Intégrer des boucles de feedback dans le système

Parfois, la solution n’était pas un autre document, mais une modification du système autour de l’agent. Un exemple était un bug dans la façon dont /spec-driven lisait le Markdown : les titres et les cases à cocher dans les exemples pouvaient être confondus avec de véritables jalons ou des tâches non terminées. Après avoir enregistré le bug, nous avons exploré le reste de /spec-driven et avons découvert plusieurs commandes dotées de leur propre petit analyseur Markdown et présentant le même point faible. Nous les avons remplacées par un analyseur partagé, avons ajouté des tests de régression et un contrôle de l'architecture, puis avons intégré la correction dans l'environnement. [OpenAI décrit une approche connexe qu'elle appelle l'ingénierie du harnais](https://openai.com/index/harness-engineering/) : placer les connaissances importantes là où les agents peuvent les trouver, rendre les règles applicables et utiliser les échecs pour améliorer l'environnement autour de l'agent.

D’autres enseignements n’ont pas pu être transformés en test ou en règle d’architecture. Nous avons transformé les erreurs récurrentes en conseils. Étant donné que /spec-driven guidait les utilisateurs tout au long d'un processus prévisible, nous pouvions présenter chaque leçon lorsque l'agent atteignait l'étape concernée. Les ingénieurs ont néanmoins décidé quelles leçons s'appliquaient au-delà du projet d'origine.

Nous avons testé les consignes sur huit demandes d'extraction antérieures, ainsi que sur des cas synthétiques conçus pour détecter les conseils non pertinents. Dans un test complémentaire, nous avons testé trois de ces tâches historiques avec des requêtes courtes, moyennes et détaillées, soit neuf comparaisons au total. Les conseils ont permis de mettre en évidence une question supplémentaire utile ou une limite de planification dans huit des neuf comparaisons. Un test distinct a porté sur trois autres tâches historiques. Il a clairement amélioré deux plans ; dans le troisième, l'agent non guidé avait déjà repéré le problème.

Les conseils les plus utiles portaient sur les changements de comportement, les consommateurs et les variantes concernés, ainsi que sur les contrats entre les API, les schémas ou les analyseurs syntaxiques. Les évaluations ne portaient que sur les questions et les plans. Nous n’avons pas mesuré si les conseils avaient permis d’accélérer l’implémentation. Les consignes ciblées sont également devenues obsolètes plus rapidement et ont parfois refait surface dans des tâches sans rapport.

La maintenance des consignes et des évaluations a nécessité plus de travail que la création de la première version. Nous pouvions cartographier la mine avec des consignes, la désamorcer en corrigeant le système sous-jacent ou accepter le risque qu'un agent ou un évaluateur doive la retrouver. Nous commencions généralement par la cartographier, car c'était moins coûteux. La correction de l'API, du test, de la documentation ou de l'exemple sous-jacents a nécessité davantage de travail, mais elle a profité à tout le monde et a supprimé le besoin de consignes.

## Comment nous aborderions l'approche /spec-driven aujourd'hui

Nous voulions empêcher les ingénieurs de répéter les mêmes instructions et de réexpliquer le projet sans supprimer la friction utile. L'agent devait toujours s'arrêter lorsqu'il avait une question importante, lorsqu'il manquait des éléments probants ou lorsque l'étape suivante nécessitait un jugement humain. Nous avons retenu quelques consignes pratiques :
- Pour la plupart des petits changements locaux, une discussion ou un plan concis suffisent.
- Utilisez l'approche « spécifications d'abord » pour vous mettre d'accord sur une orientation. Conservez les spécifications comme point de référence lorsque les décisions doivent rester valables lors de sessions ultérieures ou de transitions.
- N’incluez pas tous les éléments manquants dans la spécification. L'outil doit fournir le contexte et effectuer des vérifications ; le jugement architectural nécessite toujours une vérification humaine.

Lorsqu'une spécification mérite d'être conservée, rédigez-la pour le prochain lecteur. Faites en sorte que les décisions et les risques soient faciles à trouver, ajoutez des liens vers les éléments probants au lieu de les copier et décidez de ce qu'il convient de faire de la spécification à la fin du projet.

## Prochaines étapes

Après trois mois, les ingénieurs utilisent toujours /spec-driven lorsque le travail s'étend sur plusieurs sessions, passe d'une personne à l'autre ou se divise en de nombreuses tâches connexes. Ils l'ont utilisé pour faire avancer des projets s'étalant sur plusieurs mois et pour organiser de gros volumes de travail gérés par des agents. C'est un bon résultat pour une expérimentation interne.

Au fur et à mesure que nous avons étendu /spec-driven pour prendre en charge davantage de types de tâches, certaines nouvelles fonctionnalités ont résolu des problèmes réels pour des équipes particulières, mais ont rendu le processus plus complexe pour tout le monde. Dans la prochaine version, nous souhaitons nous orienter vers un noyau plus restreint et plus ciblé.

Les gens ont des opinions bien arrêtées sur le SDD et l'ingénierie d'instructions. Nous avons appris davantage en les testant sur des projets réels qu'en les passant au crible. Avant d'ajouter d'autres processus, nous nous demandons maintenant ce qui manque à l'agent sur ce projet. Commencez petit, observez dans quelle mesure le processus est utile ou constitue un frein, puis ajustez-le en fonction de ce que vous apprenez.

[1] Birgitta Böckeler, «[Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) », octobre 2025.

[2] François Zaninotto, «[Spec-Driven Development: The Waterfall Strikes Back](https://marmelab.com/blog/2025/11/12/spec-driven-development-waterfall-strikes-back.html) », novembre 2025.

[3] Gabriella Gonzalez, «[A sufficiently detailed spec is code](https://haskellforall.com/2026/03/a-sufficiently-detailed-spec-is-code) », mars 2026.

#### **À propos de l'auteur**

Walter Li est ingénieur logiciel au sein de l’équipe Infrastructure de stockage principale d’Asana, et Rohan Batra est ingénieur logiciel au sein de l’équipe Cadres backend. Tous deux ont passé quelques mois au sein de l'équipe tigre Agent Success, où ils ont dirigé le développement et l'évaluation du processus /spec-driven décrit dans cet article.

#### **Remerciements à l'équipe**

Nous adressons nos sincères remerciements à Leo Zhang, Karol Krupa, Gordie Levitsky et Mitch Conquer pour leur aide dans la conception et le développement du processus /spec-driven, ainsi que pour avoir été parmi les premiers à l'adopter.

- [Développement axé sur les spécifications : les points positifs… et ce que nous avons appris après trois mois](/fr/inside-asana/spec-driven-development)

ingénierie

Au bout de trois mois, nous avions une vision plus claire des cas où la structure supplémentaire était utile et de ceux où elle constituait un frein.L'un de nos ingénieurs prépara ...

- [ingénierie](/inside-asana/engineering-spotlight)