Guide Spec Kit 2026 : installation et pratique du développement piloté par les spécifications sous Windows, macOS et Linux

Spec Kit, maintenu par GitHub, transforme le développement piloté par les spécifications en une CLI à installer et en skills que l’agent invoque. Le paquet PyPI s’appelle specify-cli. Le dépôt source est github/spec-kit. Il ne remplace ni Cursor, ni Claude Code, ni GitHub Copilot, ni Codex. Il impose à ces agents d’écrire d’abord le comportement observable, ensuite le choix technique, et seulement ensuite les modifications du dépôt. En novembre 2026, Windows utilise directement des scripts PowerShell. Il n’est pas nécessaire d’installer WSL d’abord. Cette page couvre l’installation, l’arborescence et l’ordre des commandes. Pourquoi une spécification doit exister avant le code, c’est le sujet du guide du développement piloté par les spécifications. L’emplacement des fichiers de skills est dans le guide Agent Skills.

Pourquoi « fais-moi un tableau » est déjà le mauvais départ

Le conflit entre l’ancienne manière et la nouvelle est concret. L’ancienne est centrée sur la session. L’objectif, la pile et l’arborescence partent dans un seul chat. L’agent devine et modifie des fichiers. Changez de machine ou de personne, et le contexte disparaît. La nouvelle est centrée sur les artefacts. Les principes vont dans .specify/memory/constitution.md. Le comportement et sa raison vont dans specs/<feature>/spec.md. La pile attend plan.md. L’ordre exécutable attend tasks.md. La fonction active est le dossier indiqué par .specify/feature.json, pas le souvenir du fil précédent.

En 2026, c’est un problème d’installation, pas d’attitude, pour trois raisons. D’abord, l’orthographe de l’appel dépend de l’agent. Cursor, Claude Code et le mode skills par défaut de Copilot utilisent /speckit-specify. Codex utilise $speckit-specify. La forme à points de la documentation est une notation de référence. Ensuite, installer une fois avec uv et une fois avec pipx laisse deux binaires specify. L’ancienne copie sur le PATH refuse --integration. Enfin, l’extension git facultative peut créer des branches numérotées, mais git checkout lui-même ne change pas la fonction active. Les trois se produisent avant la première ligne de code produit.

Comment Spec Kit découpe le travail en couches

Ne traitez pas les neuf skills en slash comme une seule liste plate. Ils atterrissent sur trois sortes d’artefacts, et deux chemins seulement sont licites.

La couche des principes existe une fois par dépôt. /speckit-constitution enregistre des contraintes dures sur la qualité, les tests, les droits et l’expérience. Les étapes suivantes sont jugées contre ce fichier. La couche fonctionnelle existe une fois par fonction. /speckit-specify répond seulement à ce qu’une personne peut observer et à pourquoi cela doit exister. /speckit-clarify interroge les zones floues et réécrit les réponses dans la spécification. La couche d’implémentation est le premier endroit où un framework ou un dossier est permis. /speckit-plan produit le plan, les notes de recherche, le modèle de données et les contrats. /speckit-tasks découpe le plan selon les dépendances et marque le travail parallèle avec [P]. /speckit-implement modifie les fichiers dans cet ordre. /speckit-converge compare le code aux artefacts, ajoute les tâches manquantes et recommence jusqu’à rapporter Converged.

Deux portes de qualité se trouvent au milieu. Ne les confondez pas avec « le code est fini ». /speckit-checklist construit une liste de qualité des exigences, détenue par la personne qui relit. Une case cochée signifie que l’exigence est claire, pas que la fonction est implémentée. /speckit-analyze est en lecture seule. Il signale les conflits entre spec.md, plan.md et tasks.md et ne modifie pas le dépôt. Le fichier intégré checklists/requirements.md est tenu par specify et clarify. Les listes personnalisées restent à la relecture. Implement s’arrête et demande si des cases sont ouvertes. Il ne les coche pas à votre place.

Le chemin court convient à un petit changement dont la frontière est déjà claire : specify, plan, tasks, implement, converge. Le chemin complet convient à tout ce que vous comptez livrer : constitution une fois par projet, puis specify, clarify, plan, checklist, tasks, analyze, implement, converge. Un défaut suit le démarrage rapide officiel de correction de bug. Une idée à laquelle vous ne vous êtes pas encore engagé suit l’évaluation d’idée. Ni l’un ni l’autre n’est un préalable de ce chemin piloté par les spécifications.

Installer sous Windows, macOS et Linux

Les prérequis communs sont Python 3.11 ou plus récent, Git seulement si vous activez l’extension git, et l’agent avec lequel vous écrivez vraiment du code. Utilisez uv pour une installation durable. Le terminal lance la CLI. Les skills en slash s’exécutent dans le chat de l’agent.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

Après l’installation, vérifiez deux choses. specify version prouve seulement que la commande tourne et affiche une version. Il ne prouve pas que le binaire vient de PyPI plutôt que de GitHub. specify self check est en lecture seule. Il indique si une version plus récente existe et ne modifie pas l’installation. La documentation illustre les tags avec un v initial, par exemple v0.12.11. Pour épingler une installation depuis les sources, lancez uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z et gardez le v. Un pin PyPI est uv tool install specify-cli==X.Y.Z. Mettez à jour avec le même outil que l’installation d’origine : uv tool install --force specify-cli, pipx install --force specify-cli ou pip install --upgrade specify-cli.

N’initialisez pas un dépôt qui contient déjà du code sur un arbre de travail sale. Commitez ou sauvegardez d’abord, puis lancez specify init --here --force --non-interactive --integration claude. --force signifie seulement que vous acceptez la fusion des modèles dans les fichiers existants. Une CI sans clavier a besoin de --non-interactive, sinon init s’arrête sur un menu à flèches. Si le binaire de l’agent est sur une autre machine, ajoutez --ignore-agent-tools pour sauter le contrôle local. L’init non interactif choisit Copilot, sauf si vous passez un autre --integration.

Ne devinez pas la clé d’intégration. Cursor est cursor-agent, pas cursor. Les autres clés courantes sont claude, copilot, gemini, pi, omp et codebuddy. Un terminal interactif demande si vous omettez --integration. Un script ou un tube doit le passer explicitement.

Si specify version affiche un vieux numéro, regardez d’abord le chemin avec which specify. Un binaire 0.1 resté en place transforme --integration en No such option: --integration, et l’ancien --ai répond No matching release asset found. Ce n’est pas une panne réseau. Le début du PATH pointe vers une autre installation. Ne retirez que la copie que vous n’utilisez pas, et mettez à jour avec l’outil d’origine plus --force ou --upgrade. Alterner les deux outils vous ramène à deux binaires.

Neuf commandes : où elles tournent, ce qu’elles peuvent changer, à qui elles servent

Les deux tableaux suivants partagent les mêmes colonnes. La vraie différence est le point d’entrée et la frontière d’exécution, pas le nom du modèle.

Choisir le chemin court ou complet selon la situation

L’exemple suivi est un tableau de notes qui reste sur une seule machine. Rien n’est envoyé. La première phase n’a pas de mot de passe. Trois membres fixés à l’avance. Quatre colonnes sous un projet : À faire, En cours, À confirmer, Terminé. Une carte change de colonne par glisser-déposer. Un commentaire ne peut être modifié que par son auteur. Specify enregistre ce comportement et la raison. Le plan est l’endroit où vous écrivez « SQLite local, pas d’API distante ». Mettre la base dans specify transforme la première intuition technique en exigence que personne n’a plus le droit de contester.

Le texte specify collé dans le chat s’arrête à ce grain. Trois personnes fixes ouvrent un projet et font glisser des cartes entre quatre colonnes. Modifier ou supprimer un commentaire n’est permis qu’à l’auteur. Au démarrage, aucun mot de passe n’est demandé. L’emplacement des fichiers, le framework et le nom de table n’y figurent pas. Dès qu’ils y figurent, la spécification devance le plan. C’est dans le plan que vous fixez : stockage SQLite local, une seule page, aucune sortie réseau.

Accorder l’agent, le type de script et une machine isolée

Si vous écrivez déjà ce dépôt dans Cursor, utilisez cursor-agent et le type de script de la machine : ps sous Windows, sh sous macOS et Linux. Après init, invoquez un skill à la fois dans le chat, sur le chemin court ou le chemin complet. Lisez l’artefact avant le skill suivant. Ne collez pas les neuf commandes dans un seul prompt.

Si vous utilisez surtout Claude Code, la clé est claude. Quand beaucoup de descriptions de skills encombrent le contexte, initialisez avec --integration-options="--no-model-invocation" pour que les commandes centrales ne tournent que lorsque vous tapez /speckit-specify. Les utilisateurs de Copilot gardent l’agencement skills par défaut. Ajoutez --commands seulement si vous voulez explicitement les anciens fichiers d’agent.

Implement modifie des fichiers et lance des commandes. Ne faites pas le premier passage sur un portable qui contient des clés de production. Placez le dépôt sur un Mac distant, lisez le diff, puis ramenez-le. Pour commander un nœud, voir la location Mac mini. Pour le budget, voir les tarifs. Si la spec inclut une construction macOS ou une signature, faites tourner cette phase sur un vrai nœud Mac et séparez-la du portable quotidien avec l’automatisation OpenClaw. Si l’installation échoue, vérifiez la connexion et les prérequis dans le centre d’aide avant d’incriminer Spec Kit.

Cinq erreurs qui obligent à refaire le reste

1. Écrire le framework et la base dans specify. La pile appartient au plan. Dès que la spec dit « il faut cette bibliothèque », clarify et analyze passent leur temps à défendre ce choix.
2. Taper /speckit-specify dans le terminal. Les skills en slash n’existent que dans le chat de l’agent. Le terminal lance specify lui-même.
3. Coller la commande à points de la doc dans Cursor. Le skill Cursor est /speckit-specify. La forme à points est une notation de référence.
4. Installer avec uv et pipx. Un vieux binaire 0.1.x répond No such option: --integration, ou No matching release asset found sur --ai. Lancez which specify avant de décider quelle copie retirer.
5. Utiliser git checkout comme commutateur de fonction. Modifiez .specify/feature.json, ou définissez SPECIFY_FEATURE_DIRECTORY. Changer de branche seul laisse les commandes pointées sur le dossier de la fonction précédente.

Sept étapes

1. Installez uv et specify-cli. Lancez specify version et specify self check. Confirmez que le PATH ne résout qu’un seul binaire.
2. Choisissez --script selon le système et --integration selon l’agent réellement utilisé, puis lancez specify init. Sur un dépôt existant, commitez d’abord et ajoutez --here --force.
3. Lancez /speckit-constitution une fois dans le chat. Principes seulement : valider les entrées, un commentaire n’est modifiable que par son auteur, la première phase n’envoie rien.
4. Décrivez le comportement et la raison du tableau de notes avec /speckit-specify. Si vous livrez, enchaînez avec /speckit-clarify et fermez les questions sur le glisser-déposer, les droits et un projet vide.
5. Seulement quand la spec est stable, lancez /speckit-plan. Puis checklist, tasks et analyze. Si analyze signale un conflit, corrigez l’artefact source. Ne le rafistolez pas pendant implement.
6. Lancez /speckit-implement sur un Mac isolé ou dans un dossier propre. Si la liste est longue, avancez par phase. N’avalez pas tout tasks.md d’un coup.
7. Lancez /speckit-converge jusqu’à Converged. Puis lisez le diff : fichiers hors spec, et tout secret écrit dans le dépôt.

Questions qui décident l’installation

En quoi Spec Kit diffère-t-il d’une discussion dans Cursor ?

Une discussion reste dans la session. Changez de personne ou de machine, et elle disparaît. Spec Kit écrit principes, spec, plan et tâches en Markdown dans le dépôt. La fonction active est le dossier de .specify/feature.json, pas votre mémoire du fil précédent.

La commande est-elle /speckit-specify ou /speckit.specify ?

Cursor, Claude Code et le mode skills par défaut de GitHub Copilot utilisent la forme à trait d’union, dans le chat de l’agent, pas dans le terminal. Le mode skills de Codex utilise $speckit-specify. La forme à points de la documentation est une notation de référence. Ne la collez pas dans Cursor.

Windows exige-t-il WSL d’abord ?

Non. En 2026, Spec Kit prend PowerShell par défaut sous Windows. Passez --script ps à l’init. macOS et Linux prennent bash, c’est-à-dire --script sh.

Puis-je installer avec uv et avec pipx ?

Non. Vous garderez deux binaires specify. L’ancienne copie en tête du PATH refusera --integration ou affichera No matching release asset found. Mettez à jour avec l’outil d’origine, --force ou --upgrade.

git checkout change-t-il la fonction active ?

Non. La fonction active est .specify/feature.json. Remplacez-la avec SPECIFY_FEATURE_DIRECTORY. L’extension git facultative peut créer des branches numérotées, mais un checkout seul ne met pas cet état à jour.

Installer la bonne commande, puis laisser l’agent modifier le dépôt

Spec Kit n’a pas de valeur parce qu’il ajoute une commande slash de plus. Il en a parce que « spec, puis plan, puis modification des fichiers » devient des fichiers du dépôt qu’une autre personne peut relire. Windows utilise PowerShell. macOS et Linux utilisent bash. Cursor utilise cursor-agent et des skills à trait d’union. Un petit changement prend le chemin court. Une fonction que vous livrez prend le chemin complet. Implement tourne sur un nœud isolé. L’étape suivante n’est pas une nouvelle collection de prompts. Lancez specify version et confirmez que le binaire devant vous est celui que vous venez d’installer. Si le numéro ne correspond pas, corrigez le PATH avant de taper un skill.

Pour aller plus loin

• Guide du développement piloté par les spécifications : la méthode →
• Agent Skills : quoi installer, et où →
• Automatisation OpenClaw sur un Mac distant →