Découvrir OpenSpec : délimiter clairement le cadre de collaboration IA grâce aux documents de spécifications

Niveau débutant | ~15 minutes | Vous maîtriserez les concepts clés d’OpenSpec (Delta Specs, graphe des dépendances d’Artifacts), le processus d’initialisation, le workflow OPSX (propose → apply → archive), ainsi que la gestion parallèle de plusieurs changements

---

Présentation du projet

Commenceons par admettre une réalité : lorsque vous utilisez un assistant de programmation IA, est-ce que vous avez déjà rencontré l’une de ces situations — l’IA modifie des parties que vous ne vouliez pas changer ; ou bien vous changez de contexte de discussion et l’IA oublie complètement ce qui avait été dit auparavant ; ou encore, à chaque fois que vous demandez à l’IA d’écrire une nouvelle fonctionnalité, le résultat n’a en fait rien à voir avec ce que vous vouliez.

Ces problèmes ne viennent pas du fait que l’IA est trop « bête », mais parce que les besoins n’ont jamais fait l’objet d’un « visa » explicite. Ils n’existent que dans l’historique de chat — et l’espace de liberté de l’IA est bien trop grand.

OpenSpec fait quelque chose de très simple : avant d’écrire du code, aligner humain et IA sur un document de spécifications, puis laisser l’IA agir conformément à cette spécification. Développé par Fission-AI, il prend en charge 20+ outils de programmation IA (Claude Code, Cursor, Windsurf, etc.) et, fondamentalement, ajoute une couche légère de gestion de spécifications pour les assistants de programmation.

---

Public cible

• Développeurs qui utilisent au quotidien des assistants de programmation IA
• Ingénieurs qui, en collaboration d’équipe, peinent à aligner la compréhension des besoins entre humains et IA
• Product managers qui veulent des livraisons par IA plus contrôlables

Dépendances clés et environnement

• Node.js 20.19.0+

Arborescence complète du projet

openspec/
├── specs/                    # Spécifications du comportement actuel du système (par domaine)
│   └── <domain>/spec.md
├── changes/                  # Propositions de changement (un dossier par changement)
│   ├── <change-name>/
│   │   ├── proposal.md       # Motivation + périmètre + approche
│   │   ├── specs/             # Delta Specs (ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # Conception technique
│   │   └── tasks.md          # Liste de contrôle pour l’implémentation
│   └── archive/               # Historique archivé
└── config.yaml               # Configuration du projet (optionnel)

---

Étapes pas à pas

Étape 1 : installer OpenSpec à l’échelle globale

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

Vérifiez l’installation :

openspec --version
# 1.2.0

Étape 2 : initialiser le projet

Entrez dans le répertoire de votre projet et lancez la commande d’initialisation :

cd your-project
openspec init

Cette commande fait trois choses :

1. Créer la structure du répertoire openspec/
2. Générer les fichiers de compétences sous .claude/ (pour que l’assistant IA reconnaisse les commandes /opsx:*)
3. Vous demander s’il faut créer un fichier de configuration config.yaml (optionnel, pour injecter le contexte du projet)

Une fois l’initialisation terminée, votre projet contient ces répertoires :

openspec/
├── specs/       # Spécifications du comportement actuel du système (dossier vide, en attente de contenu)
├── changes/     # Dossier des propositions de changement (dossier vide)
└── config.yaml  # Configuration du projet (si vous avez choisi de la créer)

Étape 3 : activer le workflow étendu OPSX

Les nouvelles installations d’OpenSpec fonctionnent par défaut en mode core, avec seulement 4 commandes : propose, explore, apply, archive. Si vous souhaitez utiliser le workflow complet (y compris new, continue, ff, verify, bulk-archive, etc.), exécutez :

openspec config profile
# Choisir expanded ou full
openspec update

openspec update régénère les fichiers de compétences IA selon le profile choisi, afin que vous puissiez utiliser davantage de commandes dans vos conversations avec l’IA.

Étape 4 : créer votre premier changement — ajouter le mode sombre

Demandez maintenant à l’IA de vous aider à créer un changement. Prenons l’exemple : « ajouter un mode sombre à l’application ». Dites simplement à l’IA :

/opsx:propose add-dark-mode

L’IA crée automatiquement quatre fichiers Artifact sous openspec/changes/add-dark-mode/ :

openspec/changes/add-dark-mode/
├── proposal.md     # À quoi sert ce changement ? Périmètre ? Approche ?
├── specs/
│   └── ui/spec.md  # Delta Specs pour le domaine UI
├── design.md       # Comment concevoir la solution ?
└── tasks.md        # Concrètement, quoi faire ? Listez les étapes

proposal.md ressemble à ceci (généré automatiquement par l’IA ; vous et l’IA pouvez le modifier ensemble) :

# Proposal : Ajouter le mode sombre

## Intent
L’utilisateur demande d’ajouter un mode sombre afin de réduire la fatigue oculaire lors de l’usage nocturne.

## Scope
- Ajouter un bouton pour basculer le thème dans les paramètres
- Prendre en charge la détection des préférences système
- Persister les préférences dans localStorage

## Approach
Utiliser des variables CSS pour gérer le thème, avec React Context pour piloter l’état.

specs/ui/spec.md est la spécification Delta clé, avec le format suivant :

# Delta pour l’UI

## ADDED Exigences

### Requirement : Sélection du thème
Le système SHALL permettre à l’utilisateur de basculer entre un thème clair et un thème sombre.

#### Scénario : Bascule manuelle
- GIVEN l’utilisateur se trouve sur n’importe quelle page
- WHEN l’utilisateur clique sur le bouton de basculement du thème
- THEN le thème change immédiatement, et la préférence est persistée entre sessions

#### Scénario : Préférence système
- GIVEN l’utilisateur n’a pas de préférence enregistrée
- WHEN l’application se charge
- THEN utiliser le schéma de couleurs préféré du système

tasks.md est la checklist d’implémentation :

# Tasks

## 1. Infrastructure du thème
- [ ] 1.1 Créer ThemeContext (états light/dark)
- [ ] 1.2 Ajouter les définitions de variables CSS pour les couleurs
- [ ] 1.3 Implémenter la persistance localStorage

## 2. Composants UI
- [ ] 2.1 Créer le composant ThemeToggle
- [ ] 2.2 Ajouter le bouton de basculement dans la page de paramètres
- [ ] 2.3 Ajouter un accès rapide dans le Header

## 3. Styles
- [ ] 3.1 Définir la palette du thème sombre
- [ ] 3.2 Faire en sorte que les composants existants utilisent les variables CSS

Étape 5 : exécuter les tâches d’implémentation

Une fois la documentation de spécification confirmée comme correcte, lancez l’implémentation :

/opsx:apply

L’IA vérifie chaque tâche dans tasks.md ; pour chaque tâche terminée, elle coche. Vous constaterez que le comportement de l’IA a changé : elle ne « brode » plus librement, elle progresse strictement selon tasks.md. Si, pendant l’implémentation, vous constatez un problème de conception, vous pouvez directement modifier design.md, puis relancer apply : l’IA s’ajustera automatiquement.

Étape 6 : valider et archiver le changement

Validation (optionnelle, mais recommandée) :

/opsx:verify

L’IA vérifie votre implémentation selon trois axes :

Archivage :

/opsx:archive

L’archivage effectue deux opérations :

1. Fusionner les Delta Specs dans la spécification principale openspec/specs/ui/spec.md
2. Déplacer le dossier du changement dans openspec/changes/archive/2026-04-11-add-dark-mode/

Une fois l’archivage terminé, le fichier de spécification du système est mis à jour et vous disposez d’un historique complet du changement.

Étape 7 : gérer plusieurs changements en parallèle

Dans le développement réel, il arrive souvent d’être interrompu à mi-parcours pour traiter d’autres problèmes. OpenSpec permet de gérer plusieurs changements en parallèle :

# Supposons que vous soyez en train de faire add-dark-mode, puis il faut soudain corriger un bug
/opsx:new fix-login-redirect

# Terminer normalement la correction du bug
/opsx:ff
/opsx:apply
/opsx:archive

# Revenir au travail sur le mode sombre
/opsx:apply add-dark-mode

Une fois tous vos changements terminés, ar visez-les ensemble :

/opsx:bulk-archive

OpenSpec détecte automatiquement les conflits de spécification (deux changements modifient specs/ui/ tous les deux) et fusionne dans l’ordre chronologique.

Étape 8 : personnaliser le Schema

Le workflow OPSX d’OpenSpec est basé sur un Schema : vous pouvez entièrement personnaliser le type d’Artifacts et les relations de dépendance. Par exemple, si vous voulez un workflow « d’abord étudier, ensuite proposer » :

# Dériver un nouveau schema à partir du schema par défaut
openspec schema fork spec-driven research-first

La structure de Schema générée :

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

Le graphe de dépendances correspondant devient :

research ──► proposal ──► tasks

Dans schema.yaml, vous définissez :

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

Étape 9 : mémo des commandes CLI les plus courantes

# Initialiser
openspec init

# Mettre à jour les fichiers de compétences IA (à exécuter à chaque mise à niveau ou après un changement de profile)
openspec update

# Voir la configuration actuelle
openspec config show

# Changer le profile du workflow
openspec config profile

# Voir les changements actifs
openspec list

# Voir le détail d’un changement
openspec show add-dark-mode

# Valider le format
openspec validate add-dark-mode

# Dashboard interactif
openspec view

# Gestion du Schema
openspec schemas              # Lister les schemas disponibles
openspec schema which --all   # Voir la source du schema
openspec schema validate my-schema  # Valider le schema

---

Dépannage des problèmes courants

1. L’IA ne trouve pas la commande /opsx:propose

C’est le problème le plus fréquent. Après avoir exécuté openspec init, l’assistant IA doit recharger les fichiers de compétences. Lancez :

openspec update

Puis rouvrez la conversation. Si l’IA ne reconnaît toujours pas, vérifiez manuellement si le répertoire .claude/ existe.

2. openspec init échoue avec une erreur de version de Node.js

node --version
# Confirmer >= 20.19.0

# Si la version est trop basse, mettez à niveau via nvm
nvm install 20 && nvm use 20

3. Conflit lors de la fusion des Delta Specs

Lors de /opsx:bulk-archive, si deux changements modifient le même fichier de spécification, OpenSpec le détectera et vous en informera. La fusion dans l’ordre chronologique est le comportement par défaut ; si vous devez traiter manuellement :

# Archiver d’abord un changement
/opsx:archive fix-login-redirect

# Puis archiver l’autre
/opsx:archive add-dark-mode

4. Échec du chargement d’un Schema personnalisé

En général, c’est dû à une erreur de syntaxe dans schema.yaml. Vérifiez :

openspec schema validate my-schema

Erreurs fréquentes : indentation YAML incorrecte, et champ requires d’un artifact qui référence un ID inexistant (dépendance circulaire).

5. Le format de spécification généré par l’IA ne respecte pas les exigences

Vous pouvez ajouter des règles dans openspec/config.yaml :

rules:
  specs:
    - Décrire chaque scénario au format GIVEN/WHEN/THEN
    - Chaque Requirement doit contenir au moins un Scenario

Ces règles sont injectées dans les instructions pour la génération de specs par l’IA.

6. Pendant /opsx:apply, l’IA saute certaines tâches

Dites directement à l’IA :

Veuillez exécuter les tâches dans l’ordre de tasks.md ; la tâche 1.3 n’est pas encore terminée, ne la sautez pas.

La fonctionnalité fluid d’OpenSpec vous permet de modifier à tout moment un Artifact : après avoir mis à jour tasks.md, relancez apply, et l’IA reprendra à l’endroit où elle s’était arrêtée.

---

Pour aller plus loin / Pistes avancées

Plonger dans le format des Delta Specs : les trois types de changements ADDED/MODIFIED/REMOVED ont chacun leur sémantique — ADDED pour de nouvelles exigences, MODIFIED pour remplacer des exigences existantes, REMOVED pour supprimer des exigences obsolètes. Maîtriser leurs règles de fusion est la clé pour bien utiliser OpenSpec.

Comparaison OPSX vs workflow Legacy : OpenSpec v1.x utilise le workflow Legacy ( /openspec:proposal ), tandis que v1.2+ met surtout en avant OPSX. La différence fondamentale est la suivante : Legacy est phase-locked (tout ou rien), OPSX est fluid (n’importe quel Artifact peut être modifié à tout moment).

Guide d’intégration des 20+ outils IA : OpenSpec génère des fichiers de compétences via le répertoire .claude/skills/, et est compatible avec des outils populaires comme Claude Code, Cursor, Windsurf et Copilot. Voir docs/supported-tools.md.

Intégration Slack en équipe : les équipes en entreprise peuvent contacter [email protected] pour obtenir un canal Slack dédié, adapté aux scénarios de collaboration à plusieurs, pour la gestion et la revue des spécifications.

Personnalisation approfondie de la configuration du projet : en plus de context et rules, vous pouvez aussi configurer un Schema par défaut via config.yaml et injecter des informations sur la stack technique du projet (par exemple : framework de tests, conventions de style de code), pour rendre les spécifications générées par l’IA davantage fidèles à votre projet.