Meilleures pratiques

Les Specs de fonctionnalités prennent en charge deux flux de travail : Exigences d'abord et Conception d'abord.

Choisissez Exigences d'abord lorsque :

• Vous connaissez le comportement du système que vous voulez créer
• L'architecture est flexible et peut être conçue pour répondre aux besoins
• Vous créez des fonctionnalités de produit guidées par la rétroaction des clients
• Vous démarrez sans contraintes techniques

Choisissez Conception d'abord lorsque :

• Vous avez une conception technique ou une architecture existante
• Le système doit répondre à des exigences non fonctionnelles strictes (latence, débit, conformité)
• Vous faites du prototypage avec une pile technologique précise
• Vous explorez la faisabilité technique avant de vous engager sur la portée

En savoir plus sur les flux de travail →

Non, vous devez choisir un flux de travail lors de la création de la spec. Si vous devez changer d'approche, créez une nouvelle Spec de fonctionnalité avec le flux de travail souhaité. Vous pouvez copier le contenu pertinent de la spec précédente si nécessaire.

Oui! Vous pouvez créer plusieurs specs. Par exemple :

1. Utilisez Conception d'abord pour valider la faisabilité technique
2. Créez une spec Exigences d'abord pour le développement complet de la fonctionnalité

Si vous avez des diagrammes d'architecture ou des documents de conception existants :

1. En utilisant le flux de travail Conception d'abord :

   • Créez une nouvelle Spec de fonctionnalité et sélectionnez Conception d'abord
   • Téléversez des diagrammes d'architecture (PNG, JPG) ou collez le contenu de la conception
   • Kiro formalisera la conception dans design.md
   • Dérivez les exigences à partir de l'architecture

2. En utilisant des images : Exportez des diagrammes à partir d'outils comme draw.io, Lucidchart, ou prenez des photos d'esquisses de tableau blanc et incluez-les dans votre requête initiale.

3. En utilisant l'intégration MCP : Si votre outil de conception dispose d'un serveur MCP, vous pouvez vous y connecter directement pour importer des conceptions.

Si vos exigences ou conceptions existent déjà dans un autre système (comme JIRA, Confluence, ou des documents Word), vous avez deux options :

1. En utilisant l'intégration MCP : Si votre outil d'exigences dispose d'un serveur MCP, vous pouvez vous y connecter directement pour importer des exigences dans votre session de spec. Kiro prend en charge les serveurs MCP locaux et distants.

2. Importation manuelle : Copiez vos exigences existantes (p. ex. foo-prfaq.md) dans un nouveau fichier de votre dépôt, ouvrez une session de clavardage de spec et dites #foo-prfaq.md Generate a spec from it. Kiro lira vos exigences et générera des specs d'exigences et de conception.

Les Specs de fonctionnalités de Kiro sont conçues pour un raffinement continu, vous permettant de les mettre à jour et de les améliorer à mesure que votre projet évolue. Cette approche itérative garantit que les spécifications restent synchronisées avec l'évolution des exigences et des conceptions techniques, offrant une base fiable pour le développement.

Pour les specs Exigences d'abord :

1. Mettre à jour les exigences : Modifiez directement le fichier requirements.md ou lancez une session de spec et demandez à Kiro d'ajouter de nouvelles exigences ou éléments de conception.

2. Mettre à jour la conception : Accédez au fichier design.md de votre spec et sélectionnez Refine. Cette action mettra à jour à la fois la documentation de conception et la liste de tâches associée pour refléter vos exigences modifiées.

3. Synchroniser les fichiers : Accédez au fichier tasks.md et choisissez Sync Files. Cela créera de nouvelles tâches correspondant aux nouvelles exigences.

Pour les specs Conception d'abord :

1. Mettre à jour la conception : Modifiez directement le fichier design.md ou demandez à Kiro de le mettre à jour dans une session de spec.

2. Mettre à jour les exigences : Après des changements d'architecture, demandez à Kiro de valider et de régénérer les exigences pour s'assurer qu'elles restent réalisables.

3. Synchroniser les fichiers : Accédez au fichier tasks.md et choisissez Sync Files pour refléter les changements.

Une description de bogue claire aide Kiro à effectuer une analyse précise de la cause première. Incluez :

1. Étapes de reproduction - Décrivez les conditions exactes qui déclenchent le bogue
2. Comportement actuel - Ce que le système fait maintenant (le défaut)
3. Comportement attendu - Ce que le système devrait faire à la place
4. Contraintes - Tout code ou comportement qui ne doit pas changer

Exemple de requête :

When a user submits a form with special characters in the name field 
(e.g., O'Brien), the API returns a 500 error. It should accept the 
input and save it correctly. The validation logic for email and 
password fields should not be affected.

Les Specs de correction de bogues capturent explicitement le « comportement inchangé » en plus du correctif. Pendant la phase d'analyse, documentez ce qui doit continuer à fonctionner :

• WHEN [condition] THEN le système SHALL CONTINUE TO [comportement existant]

Kiro génère des tests basés sur les propriétés qui valident à la fois le correctif et la préservation du comportement existant, vous donnant la certitude que le correctif ne casse rien d'autre.

Utilisez une Spec de correction de bogue lorsque :

• Le bogue se trouve dans un chemin de code critique
• Des tentatives de correctif précédentes ont causé des régressions
• La cause première n'est pas immédiatement évidente
• Vous avez besoin de documentation pour la conformité ou les connaissances de l'équipe

Un correctif rapide en clavardage convient pour les problèmes simples comme les fautes de frappe, les erreurs de logique simples ou les changements d'une ligne bien compris.

Pas directement. Si l'analyse de la cause première révèle que le correctif nécessite de nouvelles fonctionnalités importantes, créez une Spec de fonctionnalité distincte pour le nouveau travail et gardez la Spec de correction de bogue centrée sur le défaut d'origine.

Les Specs sont conçues pour être gérées par contrôle de version, ce qui les rend facilement partageables au sein de votre équipe. Stockez les specs directement dans le dépôt de votre projet, à côté du code qu'elles décrivent. Cela regroupe tous les artéfacts du projet et maintient le lien entre les exigences et l'implémentation.

Oui, vous pouvez partager des specs entre plusieurs équipes en utilisant des sous-modules Git ou des références de paquets. Voici quelques meilleures pratiques pour gérer des specs partagées entre équipes :

1. Créer un dépôt central de specs - Établissez un dépôt dédié pour les spécifications partagées que plusieurs projets peuvent référencer.

2. Utiliser des sous-modules Git ou des références de paquets - Reliez vos specs centrales à des projets individuels en utilisant des sous-modules Git, des références de paquets ou des liens symboliques selon votre environnement de développement.

3. Mettre en œuvre des flux de travail interdépôts - Développez des processus pour proposer, examiner et mettre à jour les specs partagées qui touchent plusieurs projets.

Si vous avez des besoins précis pour la gestion de specs entre projets, veuillez partager vos exigences sur notre suivi des problèmes GitHub afin que nous puissions prioriser les fonctionnalités qui prennent en charge votre flux de travail.

Oui. Vous pouvez avoir une conversation vibe et ensuite dire Generate spec. Kiro vous demandera alors si vous voulez démarrer une session de spec. Si vous répondez oui, il procédera à la génération des exigences en fonction du contexte de votre session vibe.

Oui, vous pouvez exécuter toutes les tâches de votre fichier tasks.md en cliquant sur le bouton Run all Tasks. Kiro analyse les dépendances entre les tâches et exécute les tâches indépendantes de manière concurrente, ce qui peut accélérer considérablement l'exécution. Les tâches ayant des dépendances attendent leur tour. Cela n'exécute que les tâches incomplètes marquées comme requises. En savoir plus sur l'exécution parallèle des tâches →

Oui. Lorsque vous cliquez sur Run all Tasks, Kiro construit un graphe de dépendances de vos tâches et regroupe celles qui sont indépendantes en vagues qui s'exécutent de manière concurrente. Aucune configuration n'est nécessaire. En savoir plus →

Utilisez Quick Spec lorsque :

• Vous travaillez sur une fonctionnalité bien comprise pour laquelle vous faites confiance au résultat de Kiro
• Vous faites du prototypage rapide et privilégiez la vitesse à la révision
• Vous modifiez rarement les exigences ou la conception dans le flux standard
• Vous aviez pris l'habitude d'utiliser le mode Vibe parce que le flux Spec standard semblait trop lourd

Utilisez les Specs de fonctionnalités standards lorsque :

• Vous explorez un territoire inconnu
• Les exigences ou la conception nécessitent des itérations
• Vous travaillez dans un domaine sensible à la conformité où les points de contrôle de révision apportent une réelle valeur
• Votre équipe profite de points de contrôle d'approbation explicites

Les deux produisent les mêmes artéfacts (requirements.md, design.md, tasks.md). La différence est de savoir si vous révisez chacun avant que le suivant ne soit généré. En savoir plus sur Quick Spec →

Après que Kiro génère vos exigences, vous pouvez sélectionner Analyze Requirements pour lancer une analyse approfondie qui détecte les incohérences logiques, les ambiguïtés, les contraintes contradictoires et les lacunes. C'est particulièrement utile pour :

• Les fonctionnalités complexes comportant de nombreuses exigences où les interactions comptent
• Les projets sensibles au domaine (services financiers, santé, conformité) où l'ambiguïté coûte cher
• Les sessions Quick Spec où les exigences ont été générées automatiquement sans révision manuelle

L'analyse prend des minutes (et non des secondes) parce qu'elle raisonne sur l'ensemble de vos exigences. Pour les specs petites ou bien comprises, vous pouvez l'ignorer et passer directement à la conception. En savoir plus →

Lorsque vous travaillez sur une base de code existante, vous pourriez constater que certaines tâches de votre spec sont déjà terminées parce qu'un collègue ou vous-même avez fini par le faire dans une autre session. Voici deux façons de gérer cela :

Option 1 : Cliquez sur Sync Files dans votre tasks.md

• Ouvrez votre fichier tasks.md
• Cliquez sur Sync Files
• Kiro marquera automatiquement les tâches terminées.

Option 2 : Laissez Kiro analyser pour vous dans une session de clavardage de spec

• Dans une session de spec, demandez à Kiro : « Vérifie quelles tâches sont déjà terminées »
• Kiro analysera votre base de code et identifiera les fonctionnalités implémentées
• Kiro marquera automatiquement les tâches terminées

Cela garde votre spec de tâches exacte.

Vous pouvez référencer n'importe quelle spec de votre liste de specs dans les conversations de clavardage en utilisant le fournisseur de contexte #spec. Tapez #spec et appuyez sur Entrée pour voir une liste des specs disponibles, puis sélectionnez celle que vous voulez inclure. Kiro inclut automatiquement tous les fichiers de la spec (requirements.md, design.md et tasks.md) dans le contexte de la conversation pour s'assurer que les réponses correspondent à vos spécifications documentées.

L'utilisation de #spec est particulièrement utile lorsque vous avez besoin d'une assistance sensible au contexte :

• Implémenter des tâches - Générez du code qui correspond à vos décisions de conception et respecte les critères d'acceptation
• Raffiner des specs - Demandez des changements aux exigences, à la conception ou aux tâches en fonction de nouvelles observations
• Valider le travail - Vérifiez si votre implémentation correspond aux exigences de la spec
• Poser des questions - Obtenez des réponses sur l'architecture ou la conception de votre fonctionnalité

Exemples :

#spec:user-authentication implement task 2.3
#spec:user-authentication update the design file to include password reset flow
#spec:user-authentication does my current implementation meet the acceptance criteria for task 7.1?
#spec:user-authentication why did we choose JWT over session-based authentication?

Vous pouvez avoir autant de specs que vous le voulez dans un seul dépôt. Nous recommandons de créer plusieurs specs pour différentes fonctionnalités de votre projet plutôt que d'essayer d'en avoir une seule pour toute votre base de code.

Par exemple, dans une application de commerce électronique, vous pourriez organiser vos specs ainsi :

.kiro/specs/
├── user-authentication/       # Login, signup, password reset
├── product-catalog/           # Product listing, search, filtering
├── shopping-cart/             # Add to cart, quantity updates, checkout
├── payment-processing/        # Payment gateway integration, order confirmation
└── admin-dashboard/           # Product management, user analytics

Cette approche vous permet de :

• Travailler sur des fonctionnalités indépendamment sans conflits
• Maintenir des documents de spec ciblés et faciles à gérer
• Itérer sur une fonctionnalité précise sans affecter d'autres domaines
• Collaborer avec les membres de l'équipe sur différentes fonctionnalités simultanément