OpenSpec : présentation, installation et workflows

OpenSpec est un framework léger de développement piloté par les spécifications (Spec-Driven Development). Il ajoute une couche d’accord entre vous et votre assistant de programmation IA : on écrit d’abord ce qu’il faut construire, on relit le plan, puis seulement on écrit le code, au lieu de laisser les exigences dans le seul historique de conversation. Il est sous licence MIT, prend en charge plus de 30 outils de programmation IA, et le workflow de HagiCode lui-même repose dessus. Cette page est le chemin le plus court pour l’installer et mener un premier changement complet ; les guides complets sont maintenus sur un site dédié.

Concepts clés

OpenSpec repose sur cinq idées :

1. Les specs sont la source de vérité. Elles décrivent le comportement du système actuel, se trouvent dans openspec/specs/, sont organisées par domaine et se composent d’exigences et de scénarios.
2. Un changement (change) est une unité de travail. Pour ajouter, modifier ou supprimer un comportement, vous créez un dossier sous openspec/changes/ qui regroupe la proposition, la conception, la liste de tâches et les modifications de specs de ce travail.
3. Les specs delta décrivent uniquement ce qui change. Dans un changement, vous ne réécrivez pas toute la spec : vous écrivez ADDED, MODIFIED et REMOVED, ce qui rend OpenSpec efficace pour modifier des systèmes existants.
4. Les artefacts s’appuient les uns sur les autres. proposal (pourquoi) → specs (quoi) → design (comment) → tasks (étapes) → implémentation. Ce sont des appuis, pas des verrous, et vous pouvez revenir à n’importe lequel.
5. L’archivage réintègre le changement dans la vérité. Une fois le travail terminé, les specs delta sont fusionnées dans les specs principales et le dossier du changement est déplacé dans changes/archive/ avec une date.

Installation

Il faut Node.js 20.19.0 ou supérieur (pour les autres composants de HagiCode, 24 ou supérieur est recommandé ; voir Installation de Node.js).

npm install -g @fission-ai/openspec@latest
openspec --version

Sous macOS et Linux, vous pouvez aussi utiliser Homebrew : brew install openspec. pnpm, yarn (1.x) et bun peuvent également l’installer globalement, mais OpenSpec s’exécute toujours sur Node.js.

Placez-vous ensuite dans le répertoire de votre projet et initialisez :

cd your-project
openspec init

L’initialisation demande quels outils d’IA vous utilisez et génère pour eux des fichiers de skills ou de commandes. Pour éviter les questions, utilisez openspec init --tools claude,cursor ; les identifiants d’outils figurent dans Outils pris en charge.

Votre premier changement complet

Les commandes slash se saisissent dans le chat de votre assistant IA, pas dans le terminal :

/opsx:explore            # pas encore sûr ? L'IA lit le code et pèse les options
/opsx:propose add-dark-mode   # crée le dossier du changement : proposal, specs, design, tasks
/opsx:apply              # implémente la liste de tâches
/opsx:archive            # archive ; les specs delta sont fusionnées dans les specs principales

/opsx:propose crée openspec/changes/add-dark-mode/ avec proposal.md, specs/, design.md et tasks.md. Les specs sont du Markdown simple, sans syntaxe particulière :

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

C’est l’IA qui les rédige, et vous relisez le plan avant que le moindre code ne soit écrit. Le profil par défaut comprend propose, explore, apply, update, sync et archive. Pour le flux étendu (new, continue, ff, verify, bulk-archive et d’autres), choisissez-le avec openspec config profile puis appliquez-le avec openspec update.

Les noms de commandes varient légèrement selon l’assistant

/opsx:propose est l’écriture canonique. C’est /opsx-propose dans Cursor et GitHub Copilot, @opsx-propose dans Amazon Q et $openspec-propose dans Codex. openspec init affiche la bonne forme pour les outils que vous avez choisis.

Mise à jour

npm install -g @fission-ai/openspec@latest   # met à jour le paquet
openspec update                              # rafraîchit les fichiers d'instructions IA dans chaque projet

Si vous avez installé avec Homebrew, utilisez brew upgrade openspec.

Problèmes courants

• openspec: command not found : le répertoire global de npm n’est pas dans le PATH. Exécutez npm prefix -g ; sous macOS et Linux, ajoutez au PATH le sous-répertoire bin/ de ce répertoire, et sous Windows le répertoire lui-même.
• « Requires Node.js 20.19.0 or higher » : vérifiez la version avec node --version et mettez Node.js à jour.
• /opsx:propose n’apparaît pas dans le chat : vérifiez que vous le saisissez dans l’assistant et non dans le terminal, exécutez openspec update pour régénérer les fichiers, puis redémarrez l’assistant. Les outils qui ne gèrent que les skills, comme Codex, demandent plutôt la forme $openspec-propose.
• L’initialisation n’a pas configuré votre outil : relancez openspec init ou passez --tools.

Documentation complète

Ouvrir la documentation OpenSpec en français

• Installer OpenSpec
• Premiers pas
• Workflows
• Dépannage

Pour aller plus loin

• Pour choisir entre OpenSpec et Spec Kit de GitHub, lisez Spec Kit ou OpenSpec.
• La pratique de HagiCode autour d’OpenSpec : Optimiser l’efficacité des différentes phases d’OpenSpec avec différents agents : Résumé des pratiques HagiCode et MonoSpecs qu’est-ce que c’est : pourquoi c’est une évolution et une extension supplémentaire d’OpenSpec.