Développement piloté par spécification avec IA : OpenSpec et Spec Kit

Le développement piloté par spécification retourne la boucle habituelle prompt-et-prie : vous écrivez une spécification précise — exigences, histoires utilisateur, critères d’acceptation — et l’agent de codage génère le plan, les tâches et le code à partir de ce document. La spécification, pas l’historique du chat, est ce que vous examinez, et elle reste dans le repo après que le code soit expédié. OpenSpec et GitHub Spec Kit sont les deux boîtes à outils open source qui câblent ce flux de travail dans Claude Code, Cursor et d’autres agents via les commandes slash, et ce lab marche les deux de bout en bout sur une petite fonctionnalité : limiter en débit un point de terminaison API.

Ce que le développement piloté par spécification change réellement

Dans une session d’agent normale, vous tapez une instruction, l’agent édite les fichiers et vous examinez le diff résultant. Tout ce qu’il a supposé sur la portée, les cas limites et la gestion des erreurs est resté implicite dans le prompt, et vous ne découvrez qu’il était faux qu’en lisant le code.

Le développement piloté par spécification (SDD) insère un document entre l’instruction et le code : une spécification indiquant ce que fait la fonctionnalité et une liste de scénarios qui doivent être vrais (critères d’acceptation). Vous examinez ce document d’abord ; seulement alors l’agent le transforme en plan, une liste de tâches et un code. La porte d’examen se déplace de « ce diff est-il correct » à « cette spécification est-elle correcte », et une spécification est loin plus courte à vérifier qu’un diff touchant une douzaine de fichiers.

Les deux boîtes à outils ci-dessous implémentent cette forme — proposer/spécifier, planifier, implémenter, vérifier — en tant que commandes slash que l’agent exécute dans son propre chat. Le CLI n’installe que l’outil et les fichiers de commande ; l’agent exécute chaque autre étape.

OpenSpec : installer et la boucle proposer → appliquer → archiver

OpenSpec s’expédie en tant que binaire unique sans dépendance Node.js. Choisissez un chemin d’installation :

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

# Alternative: npm (needs Node.js 20.19.0+) or Homebrew
npm install -g @fission-ai/openspec@latest
brew install openspec

Initialisez à l’intérieur de votre projet :

cd your-project
openspec init                        # interactive tool picker
openspec init --tools claude,cursor  # set up specific tools, no prompts

openspec init écrit un dossier openspec/ et imprime quel épellation de commande slash vos outils choisis utilisent — le nom canonique est /opsx:propose, mais Cursor et Copilot le lisent comme /opsx-propose, Amazon Q en tant que @opsx-propose, Codex en tant que $openspec-propose. Le profil par défaut donne trois commandes : /opsx:explore (une passe de réflexion sans enjeu avant de s’engager dans un plan), /opsx:propose <change-name> (crée openspec/changes/<change-name>/ avec proposal.md, un dossier specs/, design.md et tasks.md), /opsx:apply (implémente les tâches) et /opsx:archive (déplace le dossier à openspec/changes/archive/<date>-<change-name>/ et fusionne ses deltas de spécification dans le dossier du projet openspec/specs/).

Un profil étendu ajoute /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive et /opsx:onboard via openspec config profile plus openspec update, qui rafraîchit aussi les fichiers de commande installés après une mise à niveau CLI.

Les mêmes actions existent en tant que commandes de terminal, utiles pour scripter ou vérifier un changement sans ouvrir l’agent :

openspec list                    # active changes
openspec list --specs            # specs with requirement counts
openspec show add-rate-limit --diff   # requirement diffs for one change
openspec validate add-rate-limit      # check one change's artifacts
openspec validate --all               # check everything
openspec archive add-rate-limit -y    # CLI equivalent of /opsx:archive

GitHub Spec Kit : constitution, spécifier, planifier, tâches, implémenter, converger

Spec Kit est un CLI Python, installé avec uv :

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

--integration claude cible Claude Code ; échangez-le pour copilot ou une autre clé d’agent supportée. Pour Claude Code, l’installation écrit un fichier de compétence par commande sous .claude/skills/speckit-<name>/SKILL.md, invoqué en tant que /speckit-specify, /speckit-plan et ainsi de suite — la forme avec trait d’union, pas la /speckit.specify pointée que les docs de Spec Kit utilisent en tant que notation neutre. Codex utilise $speckit-specify ; Kimi utilise /skill:speckit-specify.

Exécutez-les un à la fois dans le chat de l’agent, en lisant chaque résultat avant le suivant :

/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Limit requests on POST /api/orders to protect the order service from bursts.
/speckit-plan Node.js with an in-memory token bucket per API key, no new infrastructure.
/speckit-tasks
/speckit-implement
/speckit-converge

/speckit-constitution s’exécute une fois par projet et enregistre les principes que chaque étape ultérieure est vérifiée contre. /speckit-specify transforme une description en langage naturel en spec.md — exigences et histoires utilisateur, pas la pile technologique. /speckit-plan génère plan.md, où la pile technologique appartient. /speckit-tasks génère un tasks.md dépendant-ordonné, divisé en Setup, Foundational, une phase par histoire utilisateur, puis Polish. /speckit-implement exécute tasks.md dans l’ordre et est la seule commande qui écrit le code d’application. /speckit-converge vérifie le résultat par rapport aux trois artefacts ; il est append-only, sa seule écriture possible est l’ajout de tâches sous une section « Convergence » si elle trouve des lacunes, et il rapporte Converged quand rien n’est laissé.

Trois portes de qualité optionnelles s’insèrent dans la séquence complète (constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge) : /speckit-clarify pose jusqu’à cinq questions ciblées sur les zones sous-spécifiées et écrit les réponses en retour dans spec.md ; /speckit-checklist génère une liste de vérification propriété du critique testant la spécification elle-même pour l’exhaustivité ; /speckit-analyze est une passe en lecture seule rapportant les conflits sur les trois artefacts avant que vous n’implémentiez quoi que ce soit.

Spec Kit suit la fonctionnalité « active » par .specify/feature.json, pas votre branche git. Deux extensions regroupées suivent le même style : specify extension add bug ajoute /speckit-bug-assess, /speckit-bug-fix et /speckit-bug-test, avec des rapports sous .specify/bugs/<slug>/ ; specify extension add assess ajoute un flux d’évaluation d’idée en cinq étapes sous .specify/assessments/<slug>/.

OpenSpec vs Spec Kit en un coup d’œil

Choisissez OpenSpec pour une boucle légère avec la liberté de sauter en arrière dans une proposition à mi-implémentation. Choisissez Spec Kit pour une séquence plus stricte et vérifiée avec une constitution écrite et une vérification de cohérence automatisée avant que le code ne soit écrit.

Lab : spécifier une limite de débit, générer le plan, implémenter, examiner

La fonctionnalité : limiter POST /api/orders à 20 demandes par minute par clé API, retournant 429 avec un en-tête Retry-After quand l’appelant dépasse.

Étape 1 — écrire les critères d’acceptation d’abord, indépendant de l’un ou l’autre outil

Avant de toucher une commande slash, écrivez l’histoire utilisateur et les critères d’acceptation en langage clair — c’est le document que vous examinerez réellement, et l’entrée que les deux outils ont besoin.

## User story

As an API consumer, I need predictable rate limiting on order creation
so a retrying client cannot overload the order service, and so I know
exactly when to retry.

## Acceptance criteria

### Scenario: under the limit
- GIVEN an API key with fewer than 20 requests in the current minute
- WHEN it sends POST /api/orders
- THEN the request is processed normally

### Scenario: over the limit
- GIVEN an API key with 20 requests already counted in the current minute
- WHEN it sends one more POST /api/orders
- THEN the response is 429 with a Retry-After header in seconds

### Scenario: window resets
- GIVEN an API key that was rate-limited in the previous minute
- WHEN a new minute window starts
- THEN its next request is processed normally

Étape 2 — le transformer en format de spécification de l’outil

Avec OpenSpec, exécutez /opsx:propose add-rate-limit et l’agent brouillon openspec/changes/add-rate-limit/ pour vous. Remplacez le brouillon généré specs/ par vos propres scénarios, traduits dans la grammaire d’exigence d’OpenSpec :

## ADDED Requirements

### Requirement: Order creation rate limit
The orders API SHALL limit POST /api/orders to 20 requests per minute
per API key and SHALL reject requests over that limit with 429.

#### Scenario: Over the limit
- **WHEN** an API key sends a 21st request within the same minute
- **THEN** the API responds 429 and includes a Retry-After header in seconds

#### Scenario: Window resets
- **WHEN** a new minute window starts for a previously limited key
- **THEN** that key's next request is processed normally

Avec Spec Kit, exécutez /speckit-specify et collez l’histoire utilisateur et les scénarios en tant qu’argument. Si un scénario est ambigu pour l’agent — par clé API ou par IP ? — exécutez /speckit-clarify avant de continuer ; c’est exactement l’ambiguïté qu’il est construit pour attraper.

Étape 3 — planifier, implémenter, examiner par rapport à la spécification

OpenSpec : modifiez design.md si vous avez une préférence technique, puis /opsx:apply pour implémenter. Spec Kit : /speckit-plan avec vos contraintes techniques, puis /speckit-tasks, puis /speckit-implement.

Ensuite, examinez le fichier de spécification à côté du diff, scénario par scénario : la 21e demande reçoit-elle un 429 ? Retry-After contient-il un nombre de secondes ? Une clé se réinitialise-t-elle après que la fenêtre passe ? Gardez les tests dans la boucle — voir le workflow TDD assisté par IA. Avec Spec Kit, exécutez /speckit-converge et attendez Converged ; les tâches ajoutées signifient un scénario manqué, pas un bug d’outil. Avec OpenSpec, exécutez openspec validate add-rate-limit avant /opsx:archive pour que la spécification archivée et le code expédié correspondent. Seulement ensuite archivez ou convergez le changement — le même mécanisme de commande slash que les deux boîtes à outils utilisent est couvert dans le lab de commandes personnalisées.

Pièges

Les vagues spécifications produisent du code vague. « Ajouter une limite de débit » n’est pas une spécification — pas de nombre, pas de fenêtre, pas de contrat de réponse. Sans ceux-ci, l’agent les invente, et votre examen n’a rien de concret à vérifier.

Spec drift : l’agent édite la spécification pour correspondre à son propre code. Si une exécution supposée d’écrire du code a aussi silencieusement réécrit une exigence dans spec.md, cette exigence décrit maintenant ce que l’agent a construit, pas ce que vous avez demandé. Diffez les fichiers de spécification après chaque exécution /opsx:apply ou /speckit-implement, pas seulement le code d’application.

Un /speckit-converge vert ou un /opsx:apply propre n’est pas l’examen. /speckit-converge ne vérifie que les artefacts qu’il lui a été donné ; il dira Converged sur une mauvaise spécification qui a été cohéremment implémentée. La lecture scénario par scénario à l’étape 3 ci-dessus est la part qu’aucune vérification automatisée ne remplace.

Exécuter les deux boîtes à outils dans le même repo sans en choisir une en tant que source de vérité. OpenSpec écrit à openspec/ ; Spec Kit écrit à .specify/. Votre agent n’a aucun moyen de savoir que ceux à honorer pour un changement donné — décidez par projet, pas par session.

Sauter /speckit-clarify ou openspec validate parce que la fonctionnalité semble petite. Un limiteur 20-demandes-par-minute a des décisions énoncées — par clé ou par IP, fenêtre fixe ou glissante — qui sont bon marché à résoudre avant la planification et cher à trouver après que /speckit-implement a déjà choisi une réponse.

FAQ

Qu’est-ce que le développement piloté par spécification avec des agents de codage IA ?

C’est un flux de travail où vous écrivez d’abord une spécification — exigences, histoires utilisateur et critères d’acceptation en tant que scénarios concrets — et l’agent de codage génère le plan, la liste de tâches et le code à partir de ce document. Vous examinez la spécification avant que le code n’existe, au lieu d’examiner un diff après que l’agent ait déjà deviné votre intention.

En quoi OpenSpec diffère-t-il de GitHub Spec Kit ?

OpenSpec s’expédie en tant que binaire unique avec une boucle légère par défaut : proposer, appliquer, archiver. GitHub Spec Kit est un CLI Python (installé avec uv) avec un flux plus long et gâté par phases — constitution, spécifier, planifier, tâches, implémenter, converger — plus les portes de qualité optionnelles clarifier, checklist et analyser. OpenSpec favorise l’itération sur n’importe quel artefact à n’importe quel moment ; Spec Kit favorise une séquence plus stricte et vérifiée.

Qu’est-ce que la commande OpenSpec exacte pour démarrer un nouveau changement ?

Dans le chat de l’agent, tapez /opsx:propose <change-name> (Cursor et GitHub Copilot l’épellent /opsx-propose, Amazon Q utilise @opsx-propose, Codex utilise $openspec-propose). Depuis un terminal au lieu de l’agent, openspec new change <change-name> crée le même dossier sans passer par l’agent.

Quelle commande Spec Kit écrit réellement le code ?

/speckit-implement est la seule commande qui exécute tasks.md et produit du code, exécutant chaque phase dans l’ordre de dépendance. /speckit-specify, /speckit-plan et /speckit-tasks produisent seulement des artefacts Markdown (spec.md, plan.md, tasks.md) ; /speckit-converge vérifie le résultat après et n’ajoute jamais que de nouvelles tâches, il n’édite jamais le code.

Ai-je besoin de Python pour OpenSpec ou Spec Kit ?

GitHub Spec Kit a besoin de Python 3.11+ et de l’outil uv, installé avec uv tool install specify-cli. Le programme d’installation autonome d’OpenSpec est un binaire unique sans exigence Node.js ; son chemin d’installation npm (npm install -g @fission-ai/openspec@latest) a besoin de Node.js 20.19.0 ou supérieur, et une formule Homebrew est aussi disponible.