Spec-kit
Autrice : Mélanie SEAN
Spec-kit - Kézako ?
Spec-kit est un toolkit open source publié par GitHub (plus de 85k stars sur le repo) qui structure le développement assisté par IA autour d'une méthodologie appelée Spec-Driven Development (SDD). Le principe inverse le paradigme habituel : au lieu que la spec serve de documentation qu'on écrit puis qu'on oublie une fois le code en place, c'est elle qui pilote l'implémentation. L'outil est compatible avec la plupart des agents IA (GitHub Copilot, Claude Code, Gemini...) et fonctionne aussi bien sur un nouveau projet que sur du legacy.
Le workflow s'articule en six commandes successives :
- /speckit.constitution - pose les principes et standards non négociables du projet (conventions de tests, stack imposée, architecture...), une référence que toutes les étapes suivantes doivent respecter.
- /speckit.specify - rédige le "quoi" : les specs fonctionnelles en langage gherkin, ce qu'on veut construire et pourquoi, sans entrer dans le détail technique.
- /speckit.clarify - clarifie les zones d'ombre et ambiguïtés de la spec avant de passer à la suite.
- /speckit.plan - transforme la spec en plan technique : choix de stack, architecture.
- /speckit.tasks - découpe le plan en tâches ordonnées.
- /speckit.implement - l'agent (Copilot dans mon cas) génère le code à partir des tâches.
Le projet a été annoncé début septembre 2025 et se décrit lui-même comme une expérimentation encore en évolution.
Depuis, l'outil a beaucoup grossi : il supporte aujourd'hui plus de 30 intégrations d'agents (Copilot, Claude Code, Gemini, Codex, Cursor, Windsurf, Kiro, Zed, et plus), avec un système de switch d'un agent à l'autre en une seule commande, et un catalogue de plus de 70 extensions communautaires ajoutant des intégrations comme Jira, Azure DevOps ou GitHub Issues.
Utilisation en mission - Assez de blabla, un peu plus de concret
- Contexte et pourquoi j'ai utilisé spec-kit :
Dans le cadre de mon intégration dans une nouvelle mission, mon rôle a été d'aider au développement d'un nouvel ETL (Extract-Transform-Load). Le but de celui-ci est de recevoir des flux de données de différentes applications et de différents formats, d'appliquer des règles métier puis de les transformer dans un format donné.
Quelques points qui ressortent :
- Nombreux flux/traitements similaires.
- Deadline de 9 mois -> pas beaucoup de temps.
- Spécifications en cours qui risquent de changer durant toute la période -> contrainte à ne pas négliger
Oui, des contraintes classiques finalement auxquelles s'ajoute le contexte actuel : la montée de l'IA et l'envie d'expérimenter son utilisation sur un nouveau projet. Notre équipe a alors décidé d'utiliser Spec-kit.
Intégration à notre cycle de travail
1 - Rédaction des spécifications générales en langage naturel
Les personnes fonctionnelles de l'équipe rédigent les premières specs à la suite de différents ateliers avec le métier.
2 - Rédaction du fichier de mapping pour chaque application (.md)
Les personnes fonctionnelles de l'équipe traduisent leurs spécifications dans un format plus structuré, en .md, avec des tableaux de mapping, des exemples de format des données en entrée et en sortie, des règles de transformation…
3 - Réception du .md par le développeur
À ne pas négliger. Les premières étapes étant la base de tout ce qui va suivre, il est important de repérer la moindre coquille/ambiguïté. Si le développeur ne comprend même pas ce qui est demandé, qui peut garantir que l'IA le pourra ?
- Spec.md
- Plan.md
- Task.md
4 - Génération des spécifications
Le développeur fournit alors ce .md à Spec-kit et commence le workflow des commandes :
5 - Relecture et validation des spécifications
Même exercice qu'à l'étape 3. Le développeur relit et valide les documents générés, et n'hésite pas à utiliser la commande /clarify en cas d'ambiguïté.
6 - Lancement de l'implémentation, génération du code
7 - Relecture et validation du code généré
J'ai dit qu'il fallait ne pas négliger la relecture, ou pas ?
8 - Tests techniques manuels en local
9 - Commit + MR + code review par d'autres développeurs
Retour d'expérience - Quelques réflexions
- Les points positifs
- Gain de temps
Dans mon contexte, avec plein de flux similaires à implémenter, le vrai gain de temps est apparu à partir du deuxième flux. Le premier a pris du temps, normal, fallait poser toute la structure : specs générales, mapping, constitution... Mais une fois ce premier flux fait, Spec-kit avait juste à s'en inspirer pour les suivants. La base était posée, restait à adapter les spécificités de chaque flux. Sur ce genre de contexte où les flux se ressemblent, c'est clairement là que l'outil prend tout son sens.
Deuxième point : j'étais sur un projet from scratch, avec des specs qui pouvaient changer en pleine phase de dev. Sans un outil comme Spec-kit, ça veut dire retourner à la main dans tout le code impacté à chaque changement, avec le risque d'en oublier un bout au passage. Là, il suffisait de mettre à jour la spec, régénérer le plan et les tâches, et le code suivait. Sur un projet classique, ce genre de changement en cours de route, ça aurait pu être extrêmement long à gérer proprement et c'est un risque à tout casser.
- Maintenance
Le risque avec l'IA en mode "vibe coding" pur, c'est qu'elle produit du code qui a l'air bon, qui compile, qui passe les tests basiques... mais qui ne fait pas ce qu'on voulait vraiment.
Exemple : Sur un flux de mapping, l'IA peut très bien coder une règle de validation métier avec une condition légèrement inversée (> au lieu de >=), ou oublier un cas particulier mentionné une seule fois dans la spec. Rien ne crash, la review rapide ne voit rien passer d'anormal, et pourtant le comportement réel n'est pas celui attendu. Le fait de valider spec.md et plan.md avant de lancer l'implémentation, ça permet de trouver le problème à la racine, pas après en review ou pire, en prod.
Avec Spec-kit, t'es obligé d'avoir des specs, et de les tenir à jour à chaque évolution (en relançant les commandes à chaque changement de fichier). Concrètement, ça veut dire qu'on a toujours une trace écrite de ce qui a été fait et pourquoi, pas juste le code, mais l'intention derrière. Sur mon projet, avec des règles métier précises, ce filet de sécurité a clairement limité les mauvaises surprises en review, et pour cause : une bonne partie des erreurs qu'on aurait pu faire à la main (mauvaise interprétation d'une règle, oubli d'un cas particulier dans le mapping) étaient déjà cadrées avant même d'écrire une ligne de code. Et cette trace écrite, elle sert autant sur le moment que plus tard. Pour quelqu'un qui reprendrait le projet après la mission, avoir les specs versionnées à côté du code plutôt que le code seul, ça aide. C'est un argument que défend fortement OpenSpec aussi, avec une idée simple : les specs vivent dans le code.
Concrètement, ça sert à qui vient après : un nouveau développeur qui rejoint l'équipe peut parcourir la bibliothèque de specs pour comprendre le système, sans devoir tout redemander ou relire des milliers de lignes de code pour comprendre l'intention derrière.
Un autre point qui vaut le coup d'être mentionné : cette trace écrite peut aussi servir en cas d'audit. Pouvoir montrer "voici la spec validée, voici comment elle a été traduite en code", c'est un vrai plus quand il faut justifier une implémentation face au métier, bien plus solide qu'un commit Git sans contexte.
- Nouvelle forme de réflexion
Utiliser Spec-kit, ça oblige à changer sa façon de réfléchir avant de coder. On n'est plus dans "je code au fil de l'eau, je verrai bien" mais dans "je pose d'abord ce que je veux construire et pourquoi, avant de toucher au code".
Une spec sert d'alignement, une façon de structurer sa réflexion dans un seul espace avant qu'une seule ligne de code soit écrite, avec une meilleure clarté sur ce qu'on construit et un meilleur contexte pour l'agent qui exécute le plan. Et c'est vrai autant pour l'humain que pour l'IA :
Le fait d'écrire la spec, ça t'oblige toi-même à clarifier ce que tu veux, avant même de voir si l'agent a bien compris.
Sur mon projet, ça s'est traduit très concrètement : les personnes fonctionnelles étaient obligées de formaliser leur besoin de façon précise (mapping, formats, règles de transformation) avant même que le dev touche à Spec-kit. Ça a forcé des discussions qu'on aurait peut-être eues plus tard, en plein milieu du dev, avec un coût de correction bien plus élevée.
- Les limites
- Pour les projets legacy plutôt un autre spec-kit
Vous vous rappelez le nombre de commande ? Pas forcément. Pour un début d'une nouvelle feature avec des exigences complexes ça a du sens. Mais on sait que ce qui arrive le plus souvent sur un projet ce sont des petits changements de droite à gauche. En effet, refaire tout le rituel c'est lourd et c'est long (et on a la flemme). Et sur ces petits changements, le process est tellement lourd qu'on a tendance à zapper l'étape de spec. Mais c'est justement là qu'on en aurait le plus besoin : un changement avec un périmètre flou, c'est exactement le genre de cas où l'IA part en hallucination.
Spec-kit, c'est l'outil complet, avec la plus grosse communauté derrière. Mais il part du principe qu'on démarre un truc neuf. Et pour le cas inverse, il existe un autre outil, développé par la boîte Fission AI (une startup indépendante) : OpenSpec.
OpenSpec lui, part de l'autre bout : c'est un outil plus léger, pensé dès le départ pour bosser sur un projet qui tourne déjà en prod. Les deux partagent la même idée de base. Ecrire la spec avant le code, la garder versionnée dans le repo et la filer à l'IA de son choix, mais ils ne font pas le même pari sur la dose de process qu'il faut derrière.
Concrètement, la grosse différence c'est : Spec-kit te fait repartir de zéro à chaque feature (specify, plan, tasks...), comme si tu créais un nouveau projet à chaque fois. OpenSpec, lui, raisonne "par changement" : il y a d'un côté un dossier qui contient l'état actuel du projet (specs/), et de l'autre un dossier avec les changements en cours de proposition (changes/). Une fois qu'un changement est validé et mergé, il vient mettre à jour l'état actuel. C'est beaucoup plus proche de comment on bosse réellement sur un projet en prod : on ne réécrit pas toute la spec à chaque fois, on documente juste ce qui change.
Bah Mélanie pourquoi t'utilises pas juste OpenSpec ??
Alors, je ne ferai pas un sous article sur le sujet (merci déjà d'avoir lu jusqu'ici), mais grosso modo :
Même si les deux outils se ressemblent, les 2 n'ont pas la même origine ni communauté. Spec-kit a une communauté et un ecosystème beaucoup plus gros. OpenSpec, lui, est plus récent, avec moins de retours d'expérience et moins de ressources si on bloque sur un truc.
Ce ne sont pas deux versions du même outil, mais deux boîtes qui ont identifié le même problème : le vibe coding non cadré. Elles l'ont adressé chacune à leur manière, l'une en misant sur la structure complète et la rigueur, l'autre en misant sur la légèreté et l'adoption rapide.
Et puis il y a un côté poids de l'image GitHub qui compte aussi en mission : proposer un outil soutenu par GitHub à un client, c'est plus simple à justifier qu'un outil communautaire qu'on a trouvé sur un blog.
- Nouvelle politique des tokens
Au début du projet, on nous parlait d'un usage "illimité" de Copilot. Dans les faits, jusqu'en juin 2026, GitHub facturait Copilot via des premium requests, un système de quota mensuel, avec un usage qui restait perçu comme assez généreux. Mais à partir du 1er juin 2026, GitHub est passé à une facturation à l'usage, basée sur la consommation réelle de tokens. Concrètement, ça veut dire que chaque session agentique, chaque chat, chaque review de code a un coût réel et mesurable. Je vous invite à consulter l'article de William Ogez sur le sujet, vous le trouverez ici. Ce qui change énormément pour un projet comme le nôtre avec Spec-kit, qui génère et relit des specs volumineuses à chaque commande.
Résultat sur le terrain : on a senti l'équipe devenir plus frileuse sur l'usage de Copilot en cours de mission. Ce qui pose un vrai problème avec Spec-kit : reprendre un projet Spec-kit "à la main" en cours de route, c'est faire les choses à moitié. En tant qu'humain, je ne vais pas naturellement aller mettre à jour tous les fichiers de specs que Spec-kit aurait mis à jour automatiquement pour un changement donné. Résultat : on se retrouve avec des incohérences dans le projet, pourquoi y a une spec ici, et pas là ? Le système entier repose sur le fait que la structure (specs, plans, tasks) reste synchronisée avec le code, et cette synchronisation, c'est justement ce qui coûte des tokens à chaque itération.
On commence à remettre l'IA en question : Spec-kit apporte de la valeur parce qu'il est rigoureux et systématique, mais cette rigueur a un coût en tokens qui devient de plus en plus visible avec la nouvelle politique de facturation. Un point à avoir en tête pour n'importe quelle équipe qui voudrait se lancer là-dessus aujourd'hui : le calcul coût/bénéfice de l'outil n'est plus le même qu'il y a quelques mois.
Conclusion
Pour conclure, il y a plusieurs points sur lesquels je ne me suis pas attardée. J'aurais pu vous parler du fichier constitution.md avec tout son contexte, de la commande clarify, de comment le prompter et le remettre en question, ou encore de discuter des choix d'architecture avec l'IA. Mais il y a tellement de choses à dire que ça pourrait mériter un article pour chaque sujet.
Utiliser un outil comme Spec-kit, c'est un peu réapprendre à coder. Pas dans le sens où on oublie la syntaxe ou les concepts, mais dans la façon d'aborder un problème. On passe moins de temps les mains dans le code, et plus de temps à réfléchir et clarifier une intention avant de la traduire en implémentation. C'est un changement de posture qui demande du temps et une vraie remise en question de ses habitudes.
Utiliser Spec-kit ce n'est pas juste le voir comme un outil pour aller plus vite avec l'IA, mais une nouvelle façon de penser son métier de développeur.
