Spec Kit et Kiro : cadrer le développement avec l’IA

L’objectif n’est pas de produire davantage de documentation. Il s’agit de formaliser un accord concis : le fondateur doit pouvoir refuser un comportement inadapté, l’ingénieur remettre en question la conception proposée, et la personne chargée de la revue identifier les preuves nécessaires avant la fusion.

Pour commencer, choisissez une fonctionnalité bien délimitée dans le dépôt que vous utilisez déjà. Un export, une règle d’approbation ou un paramètre de notification feront mieux ressortir l’intérêt de la méthode qu’une demande de spécification portant sur une application entière.

Qu’est-ce que le développement piloté par les spécifications ?

Le développement piloté par les spécifications avec des agents IA, ou spec driven development, consiste à partir d’une description relue et validée du comportement attendu pour guider la planification, le découpage en tâches, l’implémentation et la vérification. La spécification dit ce qui doit se passer et pourquoi. Le plan explique comment l’application existante le permettra. Les tâches découpent ce plan en travaux vérifiables.

Avant l’IA, des approches apparentées utilisaient déjà les spécifications comme tests exécutables, à l’image du développement piloté par le comportement, ou BDD. Cette tradition est compatible avec le workflow présenté ici, mais une spécification en Markdown n’est pas, à elle seule, un test exécutable. Documentation BDD de Cucumber.

Ce qui change en pratique, c’est que les agents de développement peuvent exploiter ces documents tout au long de l’implémentation. GitHub Spec Kit, une boîte à outils open source destinée à structurer le travail d’un agent, apporte le processus qui l’encadre. Kiro, l’environnement de développement d’AWS, intègre ce workflow au produit. Aucun des deux ne dispense de décider de l’expérience à offrir au client.

Documentation vérifiée le 13 octobre 2026 : les noms de commandes, chemins de fichiers et capacités présentés ci-dessous proviennent des documentations actuelles de GitHub, Kiro, Anthropic et OpenAI. L’exemple de fonctionnalité sert d’illustration : il ne prétend décrire ni un déploiement en production ni un essai ayant mesuré des gains de productivité.

Pour les développeurs, le périmètre d’implémentation se resserre : l’agent doit réutiliser l’application qui entoure la fonctionnalité, plutôt que la repenser. Pour les responsables opérationnels et les fondateurs, la revue décisive intervient plus tôt : on détermine qui peut exporter les données avant d’examiner le bouton d’export. Pour les acheteurs, adopter la méthode n’impose pas de faire migrer tous les développeurs vers un nouvel éditeur. Commencez avec votre agent actuel ; investissez dans un cadre supplémentaire lorsque la maintenance des documents devient le problème.

Développement piloté par les spécifications : le workflow pas à pas

Séparez les documents, car chacun répond à une question différente. Un schéma d’architecture ne peut pas trancher une règle produit manquante, et une liste de tâches ne prouve pas que la fonctionnalité fonctionne.

Le fondateur ou le responsable produit tranche les décisions de comportement. Le responsable technique juge si la conception s’intègre au système. L’agent peut rédiger les deux propositions, mais un texte fluide ne prouve pas que ces décisions sont justes.

Spec Kit, Kiro ou simples fichiers : quel niveau de structure choisir ?

Choisissez vos outils en fonction des difficultés de coordination. GitHub Spec Kit convient à un dépôt dans lequel vous souhaitez instaurer un processus reproductible autour d’un agent existant. Kiro s’adresse aux développeurs qui veulent réunir exigences, conception et exécution des tâches dans leur environnement de développement. De simples fichiers suffisent pour une première fonctionnalité ou pour une équipe dont les pratiques de revue sont déjà solides.

GitHub Spec Kit : les commandes et les fichiers à connaître

GitHub Spec Kit fournit des instructions réutilisables, des modèles et des scripts d’appui ; c’est l’agent de développement choisi qui réalise le travail. Son README actuel décrit clairement la séquence principale : établir les principes du projet, spécifier la fonctionnalité, la planifier, créer les tâches, les implémenter, puis rechercher les écarts restants.

Le README actuel exige Python 3.11 ou une version ultérieure, uv — un outil d’installation de paquets Python — et un agent compatible. L’exemple de configuration utilise GitHub Copilot, l’assistant de développement de GitHub. Exécutez ces commandes dans le terminal :

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Lancez ensuite votre agent de développement dans ce répertoire. Exécutez chaque instruction du workflow dans la conversation avec l’agent et relisez sa réponse avant de poursuivre. Il ne s’agit pas de commandes shell.

La différence de nommage compte. Le README emploie la syntaxe des skills utilisée par défaut dans Copilot : /speckit-specify. La référence détaillée des commandes utilise la forme avec un point : /speckit.specify. L’intégration des skills de Codex emploie $speckit-specify. Utilisez la syntaxe de l’intégration installée ; les signes de ponctuation ne sont pas interchangeables. Référence des intégrations.

Ces noms et ces rôles suivent la référence Agentic SDD de GitHub. Clarify, checklist et analyze ajoutent des points de contrôle qualité. La constitution fixe les règles durables du projet ; ne la réécrivez pas pour chaque petite fonctionnalité.

Pour l’exemple d’export, l’instruction de spécification doit décrire qui peut exporter, quels enregistrements retenir, le contenu du fichier et le comportement en cas d’échec. Fournissez la stack existante et les contraintes du dépôt à l’étape de planification. Demandez explicitement des tests d’acceptation : la documentation de la commande tasks prévoit la génération de tests lorsqu’on la demande. Une liste de tâches générée ne prouve donc pas que des tests adaptés y figurent.

Voici les fichiers à relire :

• .specify/memory/constitution.md : les principes du projet. Modèle de constitution.
• specs/<feature-directory>/spec.md : le comportement de la fonctionnalité. Les répertoires de fonctionnalités se trouvent normalement sous specs/ ; leur nom est généré ou configuré. Modèle de spécification.
• plan.md et tasks.md, dans le répertoire de la fonctionnalité : la conception technique et le découpage du travail. La planification produit aussi research.md, data-model.md et quickstart.md, ainsi que contracts/ pour les interfaces externes concernées. Modèle de plan, référence des tâches.

Après l’implémentation, converge compare le code à la spécification, au plan et aux tâches. S’il détecte des écarts, il ajoute du travail à tasks.md ; il ne corrige pas le code lui-même. Réalisez les tâches ajoutées, puis relancez la vérification. Un résultat « Converged » constitue une information utile pour la revue, mais ne remplace ni vos tests ni votre approbation.

Pour une application existante, le guide d’adoption de GitHub commence par préserver un état de référence, puis initialise l’outil sur place. La commande est specify init --here --force --integration <key> : remplacez <key> par la clé d’intégration documentée, par exemple claude ou codex. Le guide avertit que --force peut remplacer des fichiers gérés en conflit. Examinez le diff obtenu. Il n’est pas nécessaire de reconstituer les spécifications de toute l’application avant d’en spécifier la prochaine évolution.

La limite : Spec Kit peut détecter des contradictions entre documents tout en acceptant une règle métier erronée, dès lors qu’elle reste cohérente partout. La maintenance de ses fichiers supplémentaires se justifie lorsque plusieurs personnes ou sessions ont besoin du même accord.

Avec Kiro : distinguer specs, steering et hooks

Kiro sépare l’intention de la fonctionnalité, les consignes durables du projet et les actions automatiques. Utilisez les specs pour la fonctionnalité en cours, le steering pour les conventions du dépôt et les hooks pour les contrôles récurrents.

Dans l’IDE, l’éditeur de code de Kiro, cliquez sur + sous Specs, ou sélectionnez Spec dans la conversation. Choisissez Feature, puis Requirements-First. Relisez les exigences avant d’accepter la conception technique et le découpage en tâches. Le répertoire de la fonctionnalité contient alors .kiro/specs/<feature-name>/requirements.md, design.md et tasks.md. Après revue, lancez les tâches depuis l’interface dédiée. Documentation des specs de Kiro.

Kiro utilise EARS, pour Easy Approach to Requirements Syntax, afin d’exprimer une condition et le comportement attendu du système. Dans notre exemple : « Lorsqu’un membre demande un export, le système doit refuser la demande et ne renvoyer aucun fichier d’export. » La formulation est assez concrète pour devenir un test. Spécifications de fonctionnalités.

Kiro propose aussi Design-First et Quick Spec. Design-First part de la conception technique ; Quick Spec crée les documents sans étapes intermédiaires d’approbation. Si votre agent comprend régulièrement mal votre intention, choisissez Requirements-First et utilisez ces revues. Les supprimer reviendrait à retirer précisément la partie du processus qui répond au problème.

Le steering fournit un contexte Markdown durable dans .kiro/steering/. Les fichiers de base sont product.md, tech.md et structure.md : ils décrivent le produit, la stack et l’organisation du dépôt. Dans l’IDE, Generate Steering Docs crée ce contexte initial. Confrontez-le au dépôt. Placez ici « réutiliser la politique d’autorisation existante fondée sur l’appartenance à l’espace » si la consigne s’applique à plusieurs fonctionnalités ; gardez « seuls les propriétaires peuvent exporter » dans la spécification de l’export. Documentation du steering.

Les hooks exécutent des commandes shell ou des prompts d’agent lorsqu’un événement se produit. Les fichiers de hooks du projet se trouvent actuellement dans .kiro/hooks/<id>.json ; PostFileSave est un déclencheur documenté. Un hook ciblé pourrait lancer vos tests d’export existants lorsque le code source concerné change. Conservez les mêmes contrôles dans l’intégration continue, qui automatise les vérifications des changements de code proposés, afin qu’ils ne reposent pas uniquement sur un hook local. Le tableau actuel des capacités de Kiro indique que les hooks sont pris en charge dans l’IDE et la CLI, mais pas sur Web ou Mobile. Documentation des hooks.

La limite : une exigence générée automatiquement peut formaliser une hypothèse que personne n’a approuvée. Examinez les autorisations, les résultats vides et les cas d’échec avant la conception. Le mode spec apporte de la structure ; il ne remplace pas les décisions produit manquantes.

Appliquer la méthode avec Claude Code

Claude Code, l’agent de développement d’Anthropic, peut suivre ce processus avec une spécification de fonctionnalité et Plan Mode. Il n’est pas nécessaire d’installer un framework de spécification pour essayer la méthode.

Créez vous-même specs/workspace-export/spec.md, ou relisez une ébauche rédigée par l’agent. Démarrez ensuite la session de terminal en mode planification :

claude --permission-mode plan

Demandez à Claude de lire ce fichier, d’examiner le code existant lié à l’export et de proposer un plan d’implémentation rattaché aux critères d’acceptation. Avant d’autoriser l’implémentation, demandez-lui de préciser les questions non résolues et les contrôles exacts qu’il prévoit d’exécuter.

Plan Mode est conçu pour l’exploration et la proposition d’une approche. Anthropic documente toutefois une exception dans les sessions de terminal interactives où le contournement des permissions est disponible : les blocages de modification du mode planification ne sont alors pas appliqués. Démarrez sans activer ce contournement si vous souhaitez préserver l’étape d’approbation. Documentation des modes de permission.

Après revue de la proposition, enregistrez l’approche retenue dans specs/workspace-export/plan.md et sa checklist dans tasks.md, puis autorisez l’implémentation. Ces chemins constituent la convention proposée dans cet article ; Plan Mode ne promet pas de créer automatiquement ces fichiers. Le guide de Plan Mode dans Claude Code détaille les contrôles et le passage à l’implémentation après approbation.

Conservez les instructions durables du dépôt dans CLAUDE.md, en vous appuyant sur le guide de la mémoire d’équipe, et le comportement propre à la fonctionnalité dans sa spécification. Sinon, une exigence temporaire concernant l’export risque de devenir une instruction permanente qui affecte des travaux sans rapport.

La limite : un plan conservé uniquement dans une conversation se perd ou se contredit facilement. L’enregistrer n’est utile que si l’implémentation et la revue s’y réfèrent ensuite explicitement.

Codex : utiliser le même fichier de spécification en mode planification

Codex, l’agent de développement d’OpenAI, permet la même transmission légère entre les étapes. Dans une conversation CLI au repos, /plan lance la planification et peut inclure la demande sur la même ligne. Documentation officielle des commandes.

Voici une demande utile : « Lis specs/workspace-export/spec.md. Examine la politique d’appartenance existante, la requête sur les tâches et les tests. Propose le plan d’implémentation minimal qui satisfait toutes les exigences. Repère les décisions manquantes avant l’implémentation. »

Relisez le plan, enregistrez les fichiers convenus, puis demandez à Codex d’implémenter les tâches en produisant un bilan qui relie chaque exigence aux tests réalisés. Utilisez AGENTS.md pour les instructions durables du dépôt ; /init peut en générer une première structure. Le guide de configuration de Codex CLI présente l’environnement de départ.

OpenAI décrit également l’usage de fichiers Markdown pour conserver les spécifications, les plans et l’avancement des travaux longs. Leur intérêt est de permettre à une session ultérieure de retrouver l’accord. La limite : Plan Mode ne maintient pas de lui-même une spécification de fonctionnalité séparée. Intégrez sa mise à jour à la revue des changements. Workflow documenté par OpenAI.

Exemple concret : spécifier un export CSV d’espace de travail

Un petit export CSV, c’est-à-dire le téléchargement d’enregistrements sous forme de valeurs séparées par des virgules, montre pourquoi définir le comportement en amont peut éviter de reprendre plusieurs fichiers. « Ajouter un export CSV » laisse l’agent deviner le rôle de l’utilisateur, le périmètre des données, la pagination et le format du fichier. Un bouton soigné peut masquer une mauvaise réponse à chacune de ces questions.

L’exemple ci-dessous porte sur une application existante de gestion des tâches. Les chemins, identifiants d’exigences et tests proposés sont pédagogiques ; ils ne décrivent pas un dépôt dans lequel les changements auraient été testés ou fusionnés pour cet article.

Une spécification qui tient sur une page

Enregistrez ce contenu dans le fichier spec.md de la fonctionnalité, ou reprenez les mêmes exigences de comportement dans le fichier requirements.md de Kiro :

R2 contient une décision facile à manquer : « tous les résultats correspondants » ne signifie pas « la page visible ». La trancher avant l’implémentation change immédiatement la requête et le plan de tests. Attendre la démonstration peut obliger à reprendre les deux.

R4 désigne volontairement une décision qui exige des exemples concrets. Avant d’approuver la spécification, définissez le traitement des valeurs susceptibles de devenir des formules de tableur, puis consignez les exemples retenus. Une phrase comme « sécuriser les exports » laisserait l’agent choisir cette politique à votre place.

Le plan : s’intégrer à l’application existante

Le plan doit réutiliser la session et la politique d’appartenance existantes, extraire ou réutiliser la logique de filtrage de la liste des tâches, puis ajouter une réponse d’export sans modifier celle de la liste. Faites passer l’export par les contrôles d’autorisation du serveur. Déterminez l’accès à l’espace de travail à partir de l’appartenance de l’utilisateur authentifié, puis appliquez les filtres demandés dans ce périmètre.

Choisissez le sérialiseur CSV déjà utilisé dans le dépôt s’il en existe un. Précisez les en-têtes de contenu et de téléchargement, la politique de sécurisation des champs, le comportement en cas d’erreur et les tests. Ajoutez le bouton en reprenant les états de chargement et d’erreur actuels de l’application.

Le plan doit aussi confronter la taille attendue des résultats aux contraintes existantes sur les requêtes et la mémoire. Si un export complet ne peut pas les respecter, soumettez ce conflit au responsable de la fonctionnalité. Décidez d’un export borné, ou définissez séparément le périmètre d’un traitement en arrière-plan. L’agent ne doit ni inventer discrètement une limite maximale ni ajouter un système de tâches en contradiction avec R6.

Les tâches : rendre chaque changement vérifiable

Transformez le plan en travaux que la personne chargée de la revue pourra identifier :

1. Couvrir le comportement actuel de la liste des tâches et les règles de filtrage partagées par des contrôles de non-régression.
2. Ajouter des tests d’autorisation des requêtes pour un propriétaire, un membre, un ancien propriétaire et un autre espace de travail.
3. Implémenter la requête limitée au bon périmètre et la réponse CSV selon la politique convenue pour les champs.
4. Ajouter la commande d’export, l’état de chargement et l’affichage des échecs.
5. Terminer les contrôles d’acceptation et examiner le diff pour repérer les changements hors périmètre.

Ce découpage appartient à l’exemple. Un outil peut générer une autre liste ; jugez-la sur sa capacité à couvrir l’accord.

Dans une application TypeScript, les changements à relire pourraient comprendre server/exports/tasks.ts pour l’autorisation, le filtrage et la réponse ; ui/tasks/ExportButton.tsx pour l’interaction ; et tests/task-export.test.ts pour les cas d’acceptation. Ces chemins sont illustratifs et ne constituent pas des conventions imposées par un framework. Un nouveau worker de file d’attente ou une migration de base de données signaleraient un changement de périmètre à résoudre avant la fusion.

Des critères d’acceptation à la décision de fusionner

Exigez des preuves du comportement, pas une liste de fichiers modifiés par l’agent. La description de la pull request doit relier les exigences à des vérifications telles que celles-ci :

La personne chargée de la revue doit comparer ces contrôles à la spécification, examiner le code d’autorisation et de requête, puis essayer le parcours utilisateur convenu dans l’environnement habituel de revue du projet. Si l’agent a écrit l’implémentation et les tests, examinez indépendamment les résultats attendus. Un test peut confirmer fidèlement la même hypothèse erronée que le code.

Supposons, par exemple, que la revue révèle un point d’accès qui ne lit que la page courante. Conservez R2 si le responsable souhaite toujours tous les résultats correspondants ; corrigez la requête et ajoutez un test dont les correspondances dépassent cette page. Si le responsable modifie le périmètre, mettez à jour R2, le plan et les tests ensemble avant l’approbation.

Fusionnez la fonctionnalité lorsque les preuves correspondent à l’accord : réunissez dans la même pull request la spécification relue, le plan final, le relevé des tâches terminées, l’implémentation et les tests. Consignez-y toute modification de périmètre acceptée. Après la fusion, maintenez la spécification comme contrat en vigueur ou indiquez qu’il s’agit d’une archive de la fonctionnalité. Une ancienne spécification qui paraît toujours faire autorité prépare la prochaine confusion.

Le bénéfice vient du fait de trancher les questions d’autorisation et de pagination avant que leurs hypothèses se propagent dans l’implémentation. La spécification, les tests et le code conservent alors la même décision après la fusion.

Quel coût, et dans quels cas l’effort est-il rentable ?

La méthode coûte du temps de revue et de maintenance, auquel s’ajoute le travail de l’agent pour rédiger et implémenter. Spec Kit est open source, mais l’agent de développement que vous y connectez conserve ses propres conditions d’utilisation. De simples fichiers Markdown n’ajoutent aucun abonnement à un outil de spécification ; ils ne rendent pas l’usage du modèle gratuit.

La tarification commerciale standard de Kiro propose Free à $0 par mois avec 50 crédits et Pro à $20 par utilisateur et par mois avec 1,000 crédits, hors taxes applicables. Quatre abonnements Pro coûtent donc 4 × $20 = $80 par mois, avant crédits supplémentaires et taxes. Ce calcul porte sur les licences, pas sur le nombre de fonctionnalités que vous pourrez livrer. Page tarifaire de Kiro.

Les crédits supplémentaires payants coûtent $0.04 l’unité. Kiro indique que l’affinement des spécifications, l’exécution des tâches et celle des hooks d’agent consomment des crédits, et qu’une tâche de spécification complexe peut en utiliser plus d’un. Sans observer la charge de travail réelle, il n’est pas possible de convertir sérieusement des « crédits » en « fonctionnalités terminées ». Définition des crédits Kiro.

Le critère économique est simple : le surcoût de spécification, de revue et de maintenance doit rester inférieur au travail de reprise qu’il permet d’éviter. Mesurez ces coûts dans votre propre processus. Une méthode qui ajoute des documents mais reporte toujours les mêmes décisions à la revue de code ne justifie pas son surcroît de travail.

Quelles promesses sont exagérées, et quand la méthode est-elle excessive ?

La promesse exagérée consiste à croire qu’un document assez détaillé rend l’agent fiable à coup sûr. Ce n’est pas le cas. Une spécification peut être fausse, l’implémentation peut l’ignorer, et les tests peuvent reproduire ses hypothèses erronées.

La distinction utile sépare l’intention formulée du comportement effectivement imposé. Une exigence dit que les membres ne peuvent pas exporter ; un contrôle côté serveur et ses tests contribuent à faire respecter cette règle. Une checklist d’exigences vérifie la description. Elle n’exécute pas l’application. Confondre les deux donne une fausse assurance.

Autre échec possible : le décalage progressif entre les documents et le code. Si un développeur modifie les autorisations sans mettre à jour autre chose que le code, le prochain agent risque de « corriger » l’application pour la ramener à une spécification périmée. Exigez que tout changement de comportement mette à jour l’accord concerné, ou archivez explicitement cet accord. Un contexte plus durable n’aide que s’il reste exact.

Adoptez la méthode dès maintenant si votre agent manque régulièrement des autorisations, des cas limites, des intégrations ou des critères d’acceptation. Utilisez ce workflow pour une fonctionnalité dont les ambiguïtés concernent plusieurs composants ou plusieurs personnes chargées de la revue.

Attendez avant de formaliser une spécification si vous cherchez encore à savoir si quelqu’un veut la fonctionnalité. Commencez par un prototype jetable ou par l’exploration de l’inconnu. Une spécification soignée pour une idée non validée peut donner l’impression qu’un mauvais investissement a déjà été décidé.

Gardez les petites corrections simples lorsque le changement voulu est évident et localisé : une faute de frappe, un ajustement conforme au style existant ou un bug ciblé couvert par un test de non-régression clair. Formulez le comportement attendu et vérifiez-le. Un cycle complet de constitution, de plan et de tâches peut demander plus d’attention que le changement ne le justifie.

Le critère de décision n’est pas le nombre de lignes de code. C’est le nombre d’hypothèses lourdes de conséquences que l’agent devrait autrement formuler seul.

Comment démarrer cette semaine ?

Choisissez une petite fonctionnalité déjà inscrite au backlog. Faites approuver par son responsable une spécification de comportement d’une page, avec les exclusions et les cas d’échec. Utilisez votre agent actuel en mode planification, ou le workflow correspondant dans Spec Kit ou Kiro, pour proposer un plan ancré dans le dépôt.

Examinez les questions avant l’implémentation. Demandez une liste de tâches reliée aux exigences. Au moment de la pull request, confrontez les preuves au même accord et consignez les décisions qui ont changé. Adaptez le poids du processus au degré d’ambiguïté.

Abonnez-vous à la newsletter pour découvrir des méthodes pratiques de développement et de gestion avec l’IA.