Nouveaux types de specs : corriger des bogues et bâtir sur des applications existantes

Vous migrez votre monolithe vers des microservices. L'architecture est déjà claire : événementielle, messagerie asynchrone, exigences de latence précises. Vous avez seulement besoin d'aide pour la mettre en œuvre. Ou encore, vous corrigez un bogue. Vous savez ce qui est brisé et ce qui doit rester intact. Vous voulez une correction chirurgicale. Quelle est la meilleure façon de travailler avec un agent pour atteindre ces objectifs sans modifier d'autres parties de votre application, ni gaspiller de jetons à tourner en rond ?

Quand nous avons lancé les Specs et le flux de travail de développement piloté par les specs, nous les avons conçus autour du flux traditionnel PM/ingénierie : d'abord les exigences, puis la conception, puis les tâches. Cela fonctionne très bien pour de nombreux projets, et nous avons vu des centaines de milliers de développeurs adopter par défaut cette approche pour construire quelque chose de nouveau.

Cependant, en discutant avec les utilisateurs de Kiro, nous avons remarqué un motif clair : tout le monde ne part pas des exigences. En particulier lorsqu'ils travaillaient sur des applications existantes (brownfield), certains développeurs arrivaient avec l'architecture technique déjà établie. D'autres corrigeaient des bogues et avaient besoin de définir soigneusement ce qui devait changer et ce qui ne devait pas changer. Ils ne voulaient pas abandonner la structure des specs, mais le flux actuel n'était pas assez flexible pour ce type de tâches.

Nous ne voulions pas demander aux développeurs de changer leur façon d'aborder ces projets, alors aujourd'hui, nous lançons deux nouvelles façons d'utiliser les Specs : le flux de travail Design-first et le Bugfix Spec.

Quand nous avons conçu les Specs pour la première fois, nous avons été motivés par ce que Laurence Tratt appelle « le problème de spécification circulaire » et « l'effet observateur » dans le développement logiciel. Tratt identifie une tension fondamentale : la seule façon de savoir exactement quel logiciel nous voulons construire est de le spécifier entièrement, mais une spécification complète représente au moins autant de travail que la création du logiciel lui-même. Cela crée un cercle vicieux où il faut construire le logiciel pour vraiment le spécifier. C'est un vœu pieux, particulièrement pour les grands projets. Comme l'observe Tratt, le logiciel occupe un « état liminal » entre le fantasme et la réalité — plein de contraintes souples difficiles à quantifier avant de vraiment se mettre à construire. L'acte de créer un logiciel est lui-même un acte de spécification. Cela ne veut pas dire travailler sans plan, mais atteindre un terrain d'entente qui vous donne assez de structure pour progresser rapidement.

Requirements-first et Design-first sont deux facettes d'une même médaille, chacune abordant différents aspects de ce problème de spécification circulaire :

• Requirements-first fonctionne quand vous comprenez les comportements et les résultats dont vous avez besoin, mais que la voie technique n'est pas claire. Vous explorez « qu'est-ce que ceci devrait faire ? » avant « comment cela devrait-il fonctionner ? » Excellente option pour les projets entièrement nouveaux où vos options sont ouvertes.
• Design-first fonctionne quand vous avez déjà une vision technique — peut-être issue de votre expérience, de contraintes architecturales ou d'un prototypage — et que vous devez remonter en arrière pour formaliser ce que ce système accomplit réellement. C'est comme dessiner une solution au tableau blanc, puis résumer « ce que ce produit fait ». Cela peut s'appliquer à la construction d'une nouvelle fonctionnalité par-dessus une application existante — vous devez travailler dans le cadre de votre architecture et de votre pile technologique actuelles.

Les deux approches embrassent l'itération et la rétroaction. Aucune des deux ne prétend que vous pouvez spécifier parfaitement un logiciel à l'avance. Elles vous rencontrent plutôt là où vous en êtes réellement dans votre réflexion, puis vous aident à résoudre le problème de spécification circulaire à partir de points de départ différents.

Considérons cette requête.

Le développeur connaît déjà la pile technologique (FastAPI et mcp-python), l'architecture de haut niveau (un serveur MCP) et les contraintes (aucune capacité d'interface utilisateur). Il ne demande pas « qu'est-ce que je devrais construire ? », il demande « aidez-moi à construire cette chose que j'ai déjà conçue ». Dans ce cas, commencer par un document de conception a plus de sens, car cela correspond à la façon dont il pense déjà au problème.

Alors maintenant, quand vous créez un nouveau Feature Spec, Kiro vous demande de choisir : Requirements-first ou Design-first technique. Si vous choisissez Design-first technique, vous choisissez votre niveau de détail. Conception de haut niveau pour les diagrammes système et les composants, ou conception de bas niveau pour les algorithmes et les signatures de fonctions. Kiro génère d'abord votre document de conception. Vous itérez sur celui-ci, en explorant différentes approches techniques. Une fois que vous en êtes satisfait, Kiro dérive les exigences à partir de votre conception, ce qui garantit qu'elles sont réalisables. Le reste du flux de travail des specs est identique : tâches, mise en œuvre, tests basés sur les propriétés pour vérifier si la mise en œuvre correspond à ce que vous voulez.

Le Design-first technique fonctionne particulièrement bien quand vous avez une architecture prédéfinie, quand vous prototypez pour voir si quelque chose est faisable, ou quand vous travaillez avec des exigences non fonctionnelles strictes qui contraignent vos choix de conception. C'est idéal quand l'approche technique est le point de départ, et non la destination.

Lorsque vous corrigez des bogues, vous avez un ensemble différent de contraintes et d'objectifs. Vous ne construisez pas quelque chose de nouveau, mais vous corrigez quelque chose qui existe. Votre surface d'impact est différente aussi. Changez trop de choses, et vous risquez de briser quelque chose qui fonctionnait bien. Vous voulez le changement minimal qui résout le problème.

Alors, quelle est la meilleure façon de travailler avec un agent pour y arriver ? Nous avons constaté que les développeurs qui ont utilisé les Specs pour corriger des bogues avec succès partageaient deux caractéristiques. Premièrement, ils définissaient le scénario détaillé qui causait l'erreur, pas seulement le message d'erreur lui-même. Deuxièmement, ils énonçaient explicitement ce qui ne devait pas être modifié. C'est ainsi que les développeurs expérimentés pensent aux corrections de bogues : ils réparent ce qui est brisé, mais ne touchent à rien d'autre.

Quand vous créez un Bugfix Spec, Kiro suit une approche similaire en générant un document structuré avec trois sections :

1. Current Behavior décrit ce qui se passe actuellement : « WHEN a user submits a form with special characters THEN the system crashes with a validation error. » En étant plus complet à cette étape, Kiro diagnostiquera mieux les conditions dans lesquelles le bogue se produit.
2. Expected Behavior décrit ce qui devrait se passer à la place : « WHEN a user submits a form with special characters THEN the system SHALL sanitize the input and process the form successfully. » Cela indique à Kiro à quoi ressemble l'état résolu, afin qu'il puisse ensuite vérifier qu'il a effectivement corrigé le bogue.
3. Unchanged Behavior décrit ce qui doit rester identique : « WHEN a user submits a valid form THEN the system SHALL CONTINUE TO process it exactly as before. » Plutôt que de rester implicite sur ce qui ne devrait pas changer, le Bugfix Spec l'énonce explicitement. Cela aide Kiro à vérifier que des régressions ne sont pas introduites et alimente les tests de propriétés à valider.

Cette structure vous force à réfléchir explicitement à ce qui change et à ce qui ne change pas, et aide le modèle sous-jacent à comprendre votre intention plus précisément. Kiro construit ces sections automatiquement pour vous; vous n'avez pas besoin de passer du temps à rédiger ce .md vous-même. Vous pouvez réviser et affiner ces conditions, puis Kiro procède à la création d'un design.md et d'un tasks.md, tout comme un Feature Spec, mais adapté aux corrections chirurgicales.

Ce qui rend cela efficace, c'est la façon unique dont Kiro effectue les tests. Kiro génère des tests basés sur les propriétés (PBT) pour les trois catégories. Des tests qui vérifient que la mise en œuvre actuelle présente le bogue. Des tests qui vérifient que votre correction le résout. Et des tests qui vérifient que le comportement inchangé continue de fonctionner exactement comme avant. Sans ces PBT, il est difficile de vérifier si l'agent a réellement corrigé le bogue pour un ensemble complet de conditions, et que les changements étaient bien chirurgicaux.

Les Bugfix Specs excellent pour les bogues complexes qui bénéficient d'une résolution de problème structurée, les situations où le risque de régression est élevé, ou quand vous avez besoin de documentation pour votre correction.

Curieux de savoir comment nous avons appris à un agent d'IA à corriger du code sans tout casser d'autre ? The Bug Fix Paradox présente l'approche derrière les Bugfix Specs.

Les Specs ont changé la façon dont de nombreux développeurs abordent le développement avec l'IA pour livrer un logiciel solide. Mais lorsque vous travaillez avec des applications existantes, particulièrement sur de grandes bases de code, vous pourriez préférer une approche différente. Parfois, vous commencez par les exigences, parce que vous savez exactement ce que vous voulez construire. Parfois, vous connaissez déjà l'approche technique, et elle n'est pas négociable. Parfois, vous corrigez un bogue et avez besoin d'une précision chirurgicale parce que vous ne voulez pas qu'une régression touche tous vos utilisateurs. Maintenant, les Specs prennent en charge ces trois cas d'utilisation.

Apprenez-en plus dans la documentation sur les feature specs et les bugfix specs. Téléchargez ou redémarrez Kiro IDE pour essayer ces nouvelles approches des specs.