Spec Kit de GitHub - développer des logiciels de haute qualité plus rapidement

• Spec-Driven Development : une approche qui élève la spécification (spec), autrefois simple outil d’assistance dans le développement traditionnel, au rang de spécification exécutable, afin de générer directement une implémentation fonctionnelle à partir de celle-ci
  • Elle rompt avec une pratique centrée sur le code pour définir d’abord le quoi et le pourquoi, puis préciser ensuite le comment, en mettant l’accent sur un développement centré sur l’intention
  • L’idée clé est de produire des livrables cohérents à partir des spécifications et d’automatiser les tâches répétitives afin de permettre aux développeurs de se concentrer sur les problèmes produit
• Spec Kit est un ensemble d’outils qui aide à transformer ces spécifications en livrables exécutables afin d’automatiser l’implémentation
• Après l’installation, on décrit le quoi/pourquoi avec /specify, on déclare la stack/l’architecture avec /plan, puis on génère les unités de travail avec /tasks
• L’objectif est d’aider les organisations à se détourner de l’écriture de code commun non différenciant pour se concentrer sur les scénarios produit, dans le cadre d’un framework expérimental qui cherche à améliorer à la fois la qualité et la vitesse grâce à une approche pilotée par les spécifications

Philosophie centrale : Core philosophy

• Un état d’esprit spec-first fondé sur le développement centré sur l’intention, où l’on met d’abord en avant le quoi avant de détailler le comment
• La rédaction de spécifications riches intégrant des garde-fous et des principes organisationnels, avec un processus de raffinement en plusieurs étapes plutôt qu’une génération de code ponctuelle
• Une approche qui s’appuie activement sur la capacité d’interprétation des modèles d’IA avancés pour transformer les spécifications en résultats exécutables

Processus piloté par les spécifications avec Spec Kit

• Spec Kit place la spécification au centre du processus d’ingénierie pour piloter l’implémentation, les checklists et la décomposition des tâches, tandis que les développeurs jouent surtout un rôle de pilotage
  • Les agents de code prennent en charge l’essentiel du travail de rédaction
• Le processus se compose de 4 étapes, chacune avec des points de contrôle clairs, et l’on ne passe pas à l’étape suivante tant que le travail en cours n’est pas entièrement validé
• Étape Specify : lorsqu’on fournit une description de haut niveau, l’agent de code génère une spécification détaillée, axée non pas sur la stack technique mais sur le parcours utilisateur, l’expérience et les indicateurs de réussite
  • Elle cartographie qui sont les utilisateurs, quels problèmes sont résolus, comment ils interagissent et quels résultats sont importants
  • Il s’agit d’un artefact vivant qui évolue au fil de l’apprentissage sur les utilisateurs
• Étape Plan : lorsqu’on fournit la stack souhaitée, l’architecture et les contraintes, l’agent de code produit un plan technique complet
  • Il inclut les technologies standards de l’entreprise, l’intégration avec les systèmes legacy, la conformité, les objectifs de performance, etc.
  • On peut demander plusieurs variantes de plan pour les comparer, et intégrer directement des patterns d’architecture en fournissant de la documentation interne
• Étape Tasks : à partir de la spécification et du plan, l’agent de code décompose le travail en petits blocs révisables
  • Chaque tâche peut être implémentée et testée indépendamment, et elle est conçue pour que l’IA puisse la valider et en assurer le suivi
  • Par exemple, au lieu de « construire l’authentification », on aura « créer un endpoint d’inscription utilisateur avec validation du format de l’e-mail »
• Étape Implement : l’agent de code traite les tâches une par une ou en parallèle, pendant que les développeurs examinent des changements ciblés
  • La spécification indique ce qu’il faut construire, le plan comment le construire, et les tâches sur quoi travailler
• À chaque étape, les développeurs réfléchissent et affinent, en jouant un rôle de validation pour vérifier si la spécification capture bien l’intention, si le plan tient compte des contraintes réelles et s’il manque des éléments ou des cas limites

Comment utiliser Spec Kit dans un workflow agentique

• Spec Kit fonctionne avec des agents de code comme GitHub Copilot, Claude Code, Gemini CLI et guide ces agents via une série simple de commandes pour générer des artefacts
  • Cela transforme des prompts ambigus en intentions claires, exécutables de manière fiable
• Après l’initialisation du projet, une invite de haut niveau fournie via la commande /specify permet à l’agent de code de générer la spécification complète, centrée sur le « quoi » et le « pourquoi » du projet
• Avec la commande /plan, une orientation technique de haut niveau permet à l’agent de code de générer un plan détaillé respectant l’architecture et les contraintes
• Avec la commande /tasks, la spécification et le plan sont décomposés en une liste de tâches exécutables, que l’agent de code utilise ensuite pour implémenter les exigences du projet

Phases de développement : Development phases

• Étape 0-to-1 (greenfield) : prise en charge d’un flux génération de la spécification → planification → création d’une application de niveau production à partir d’exigences de haut niveau
• Étape d’exploration créative : accent mis sur un processus d’expérimentation par implémentations parallèles de différentes stacks/architectures et de patterns UX
• Étape d’amélioration progressive (brownfield) : développement évolutif itératif autour de l’ajout de fonctionnalités, de la modernisation du legacy et de l’adaptation des processus

Trois scénarios où cette approche fonctionne bien

• Greenfield (zero-to-one) : au démarrage d’un nouveau projet, on ne se lance pas immédiatement dans le code ; on prépare d’abord la spécification et le plan pour garantir que l’IA construit bien ce qui est voulu, avec des résultats sur mesure plutôt qu’une solution générique fondée sur des patterns courants
• Travail fonctionnel sur un système existant (N-to-N+1) : lorsqu’on ajoute une fonctionnalité à une codebase complexe, la spécification clarifie comment la nouvelle fonctionnalité interagit avec le système existant, et le plan encode les contraintes d’architecture pour générer un code qui semble natif
  • Cela rend le développement continu plus rapide et plus sûr, même si des techniques avancées de context engineering peuvent être nécessaires
• Modernisation du legacy : lorsqu’on reconstruit un système legacy dont l’intention initiale s’est perdue, le processus Spec Kit permet de capturer la logique métier essentielle dans une spécification moderne, puis de planifier une architecture neuve afin que l’IA puisse reconstruire le système sans dette technique

Prerequisites

• Linux/macOS ou WSL2 sur Windows requis
• Choix de l’agent d’IA parmi Claude Code, GitHub Copilot, Gemini CLI, Cursor

[edunga1]

Ça me rappelle copilot workspace.

[cocofather]

On dirait que cela pourrait devenir la base de la programmation IA en langage naturel.

[tested]

L’avantage de Spec Kit de GitHub, c’est qu’on peut aussi l’utiliser avec GitHub Copilot.
Comme il a été créé par GitHub, c’est assez logique ? Mais beaucoup d’autres outils étaient basés sur Claude.

[skageektp]

Ça me rappelle l’IDE Kiro.

[kandk]

Intéressant. C’est assez logique aussi.

[xguru]

Le lien de présentation détaillée de la SDD au milieu de l’article est vraiment intéressant. Ci-dessous, voici un résumé fait avec l’IA.

Développement piloté par les spécifications (Specification-Driven Development, SDD)

The Power Inversion

• En inversant le flux où le PRD et les documents de design n’étaient que des auxiliaires centrés sur le code, la spécification devient la source d’origine et le code n’est plus qu’une expression implémentée dans un langage ou un framework donné
  • Le constat est qu’il était difficile de combler le fossé permanent entre spécification et implémentation par le seul renforcement documentaire ou procédural
  • Si des spécifications exécutables et un plan d’implémentation génèrent le code, alors le fossé disparaît et il ne reste plus qu’une transformation
• L’IA rend possible l’interprétation de spécifications complexes et l’élaboration de plans d’implémentation, mais une génération sans structure provoque de la confusion ; la SDD garantit donc la qualité grâce à une structure précise et des garde-fous
• La maintenance devient un travail d’évolution de la spécification, l’intention de développement s’exprime en langage naturel, actifs de design et principes clés, et le code occupe la position du dernier kilomètre
• Le débogage privilégie la correction de la spécification et du plan d’implémentation plutôt que celle d’un mauvais code, et le refactoring est redéfini comme une recomposition de la clarté

The SDD Workflow in Practice

• Une idée est affinée en PRD via une interaction conversationnelle avec l’IA, qui précise les questions, les cas limites et les critères d’acceptation
  • Les exigences et la conception deviennent une activité continue, avec prise en charge d’un travail de spécification basé sur les branches à l’échelle de l’équipe, ainsi que de la revue et du versioning
• Un agent de recherche explore la compatibilité des bibliothèques, les performances, la sécurité et les contraintes de l’organisation (standards DB, authentification, politiques de déploiement) pour les refléter automatiquement dans la spécification
• À partir du PRD, un plan d’implémentation est généré afin de mapper de façon traçable les exigences et les décisions techniques, tandis que l’IA vérifie en continu les contradictions, ambiguïtés et omissions
• Une fois la spécification et le plan suffisamment stables, la génération de code commence, avec au départ une génération exploratoire pour valider la faisabilité
  • Les concepts métier deviennent des modèles de données, les user stories des endpoints API et les scénarios d’acceptation des tests
• En phase d’exploitation, les métriques et incidents mettent à jour la spécification pour être reflétés dans la génération suivante ; les goulets de performance sont promus en exigences non fonctionnelles et les vulnérabilités en contraintes globales

Why SDD Matters Now

• Seuil critique des capacités de l’IA : il devient possible de générer de manière fiable du code fonctionnel à partir de spécifications en langage naturel, et l’automatisation de la part mécanique de la traduction vers l’implémentation soutient l’exploration et l’amplification de la créativité
• Explosion de la complexité : avec la multiplication des services, frameworks et dépendances, il devient difficile de préserver l’alignement entre intention et implémentation, d’où la nécessité de l’alignement piloté par la spécification de la SDD
• Accélération du changement : dans des contextes de pivots fréquents, la SDD traite les évolutions par une régénération systématique au lieu d’une propagation manuelle dans la documentation, le design et le code
  • Elle permet par exemple les simulations what-if et les implémentations en parallèle, apportant ainsi de l’agilité décisionnelle

Core Principles

• Spécification = langage commun : la spécification est un artefact de premier rang, le code est une expression d’une stack donnée, et la maintenance est un travail d’évolution de la spécification
• Spécifications exécutables : des spécifications précises, complètes et non ambiguës permettent de générer un système opérationnel
• Affinage continu : la vérification de cohérence est permanente, et non un simple contrôle ponctuel
• Contexte fondé sur la recherche : les performances, la sécurité et les contraintes organisationnelles sont collectées en continu puis injectées dans la spécification
• Feedback bidirectionnel : la réalité de l’exploitation devient une entrée de mise à jour de la spécification
• Branching pour l’exploration : prise en charge de la génération de plusieurs implémentations à partir d’une même spécification selon des objectifs d’optimisation comme la performance, la maintenabilité, l’UX ou le coût

Implementation Approaches

• En pratique aujourd’hui, l’essentiel consiste à combiner les outils existants et à maintenir la discipline, avec une mise en œuvre possible via les éléments suivants
  • Assistant IA pour l’affinage itératif de la spécification
  • Agent de recherche pour la collecte du contexte technique
  • Outil de génération de code pour la transformation spécification → implémentation
  • Gestion de versions adaptée à un workflow spec-first
  • Vérification basée sur une analyse de cohérence par IA des documents de spécification
• Le principe commun consiste à faire de la spécification l’unique source de vérité, et à considérer le code comme un livrable exigé par la spécification

Streamlining SDD with Commands

• /specify : convertit une description de fonctionnalité en spécification structurée et automatise la numérotation, la création de branche et l’organisation d’un répertoire basé sur des templates
• /plan : analyse la spécification → vérifie la conformité à la constitution → effectue la traduction technique → documente les modèles de données, contrats API et scénarios de test → génère une validation quickstart
• /tasks : lit plan.md et les conceptions associées pour produire une liste de tâches exécutable, avec signalement des tâches parallélisables et regroupement parallèle sûr
• Exemple : fonctionnalité de chat
  • Présente un exemple de flux où environ 12 heures de travail documentaire dans une approche traditionnelle sont ramenées à environ 15 minutes de configuration grâce à l’automatisation de la spécification, du plan et des tâches
  • Les livrables incluent la spécification, le plan d’implémentation et ses justifications, les contrats API et modèles de données, les scénarios quickstart et tasks.md, le tout versionné dans la branche

The Power of Structured Automation

• Prévention des oublis : les templates couvrent aussi les exigences non fonctionnelles et la gestion des erreurs
• Traçabilité des décisions : chaque choix technique est relié à une exigence précise
• Documents vivants : comme la spécification génère le code, il est plus facile de maintenir la synchronisation
• Itération rapide : en cas de changement d’exigence, la régénération du plan permet de réagir à l’échelle de la minute ou de l’heure

Template-Driven Quality

• Prévention de l’intrusion prématurée des détails d’implémentation : les règles centrées sur le WHAT/WHY, en excluant le HOW, encouragent le maintien du bon niveau d’abstraction
• Imposition de marqueurs d’incertitude : le marqueur [NEEDS CLARIFICATION] évite les suppositions et pousse à poser des questions explicites
• Auto-vérification par checklist : la vérification de la complétude, de la clarté et de critères d’acceptation mesurables met en place une barrière qualité
• Constitution gate : application de contrôles en phase préalable (-1), comme la barrière de simplicité (≤3 projets), la barrière anti-abstraction (utilisation directe du framework) et la barrière integration-first (contrats et tests de contrat en amont)
• Gestion hiérarchisée du détail : le code et les détails excessifs sont séparés dans implementation-details/ afin de préserver la lisibilité
• Primauté des tests : des règles fichiers et tests d’abord, dans l’ordre contrat → intégration → E2E → unité, garantissent la vérifiabilité
• Frein aux fonctionnalités supposées ou spéculatives : l’interdiction des fonctionnalités spéculatives et la définition explicite des préconditions étape par étape renforcent la maîtrise du périmètre

The Constitutional Foundation

• Adoption d’une constitution de développement qui, à travers les principes immuables de memory/constitution.md, maintient toutes les implémentations cohérentes, simples et de haute qualité
  • Article I: Library-First — toute fonctionnalité commence comme une bibliothèque indépendante afin d’assurer la modularité
  • Article II: CLI Mandate — chaque bibliothèque expose une interface CLI prenant en charge entrées/sorties texte et JSON, afin de garantir observabilité et facilité de test
  • Article III: Test-First — interdiction d’implémenter avant validation des tests et confirmation de l’échec (red), avec priorité à la définition du comportement
  • Articles VII & VIII : simplicité et anti-abstraction — réduction du nombre de projets et confiance directe dans le framework pour limiter la sur-ingénierie
  • Article IX: Integration-First Testing — préférence donnée aux tests proches des conditions réelles, et exigence que les tests de contrat précèdent l’implémentation
• Les gates de phase -1 des templates transforment la conformité à la constitution en checklist, et les exceptions consignent leurs justifications explicites dans Complexity Tracking
• Via une procédure d’amendement, les modalités d’application de ces principes peuvent évoluer tout en conservant la philosophie de base

The Transformation

• L’objectif n’est pas de remplacer les développeurs, mais d’automatiser la traduction mécanique pour amplifier les capacités humaines et préserver l’alignement entre intention et implémentation
• La SDD met en pratique une transformation continue où la spécification génère le code, et où spécification, recherche et code coévoluent dans une boucle de feedback étroite

[amoplan]

Avec quelle IA l’avez-vous résumé ?

[xguru]

Je l’ai fait avec GPT-5. J’utilise un prompt assez long que j’ai préparé pour faire des résumés.

[heycalmdown]

J’adhère beaucoup au concept, donc j’ai fait quelques tests ce week-end sur un nouveau projet, mais cela ne fonctionne pas aussi bien que je l’espérais. Il semble qu’il y ait encore beaucoup d’améliorations à apporter. En gros, le fonctionnement est le suivant, comme cela a déjà été présenté plusieurs fois :
Rédaction de la constitution → rédaction de la spec → rédaction des tâches → implémentation

Le problème, c’est que :

• le fichier constitution.md est un guide clé sur la manière de développer, mais il ne contient pas ce que cette application deviendra au final
• spec.md est un document qui décrit une fonctionnalité
• il n’existe pas de document maître expliquant « ce qu’est cette application »
• en lisant les discussions en cours sur GitHub, j’ai l’impression que la chaîne des specs finira par devenir la source of truth ; cela me laisse perplexe, mais je peux à peu près comprendre l’idée
• les commandes /specify et /tasaks génèrent beaucoup de documents comme livrables (ce qui était l’objectif), mais du coup elles consomment rapidement le contexte (j’utilise Claude Code)
• une fois l’implémentation lancée, on s’éloigne temporairement de Spec Kit et on finit l’implémentation comme d’habitude en discutant avec Claude Code
• quand tout le contexte est consommé et qu’on compacte, ou qu’on démarre une nouvelle session, il oublie l’existence des documents générés par Spec Kit
• en avançant sur les tâches définies dans tasks.md, on finit parfois par écraser ce qui avait été bien fait au début, et on crée aussi de nouvelles fonctionnalités en corrigeant des bugs ; on s’éloigne donc de plus en plus de tasks.md. Je ne vois pas l’intérêt de conserver tasks.md de manière permanente.

Pour l’instant, la conclusion à laquelle je suis arrivé est la suivante :

• même si le résultat diffère de l’idée de départ, il faut d’abord terminer la spec, puis en créer une nouvelle pour corriger progressivement
• la spec initiale ne peut qu’être volumineuse ; il vaudrait mieux ne pas décrire du tout les fonctionnalités de l’application et se limiter à créer du boilerplate
• pour construire quelque chose au niveau PoC, il vaut mieux ne pas utiliser Spec Kit