OpenSpec en toute rapidité : installation, flux de travail et pièges fréquents

Les spécifications sous forme de deltas, pas d’un PRD de 40 pages.

Sommaire

OpenSpec est une interface en ligne de commande (CLI) gratuite et open source de Fission AI qui permet à vous et à votre agent de codage de vous mettre d’accord sur une modification en Markdown pur avant la rédaction de n’importe quel code, sans la cérémonie rigide des phases imposée par les cadres de développement dirigé par des spécifications plus lourds.

La plupart des équipes qui tentent le développement dirigé par des spécifications (Spec-Driven Development) se bloquent sur le même compromis : assez de processus pour empêcher l’agent de deviner, sans autant d’infrastructure qu’une correction de bug de cinquante lignes nécessite un document de proposition. La réponse d’OpenSpec est de passer entièrement à côté de l’instinct de « documenter d’abord tout le système » et d’écrire des spécifications uniquement pour ce que la modification touche réellement, en utilisant des deltas ADDED, MODIFIED et REMOVED au lieu d’une réécriture complète à chaque fois.

Workflow de développement dirigé par des spécifications OpenSpec avec un assistant de codage IA

C’est aussi cette conception centrée sur les modifications qui explique pourquoi OpenSpec apparaît souvent à côté de GitHub Spec Kit, Kiro et Superpowers dans la comparaison des catégories d’outils SDD — c’est généralement le choix retenu lorsqu’une équipe souhaite des spécifications révisables sans une phase de planification de 800 lignes. Ce guide couvre l’installation de la CLI, le workflow à quatre commandes utilisé au quotidien, l’apparence d’une modification sur disque et les questions et plaintes les plus fréquentes sur Reddit et dans le propre suivi de problèmes d’OpenSpec.

Qu’est-ce qu’OpenSpec ?

OpenSpec décrit sa propre philosophie en quatre lignes : fluide et non rigide, itératif et non en cascade (waterfall), simple et non complexe, conçu pour le brownfield et non seulement le greenfield. En pratique, cela signifie qu’il n’y a pas de phases verrouillées — vous pouvez éditer une proposition, une spécification ou une liste de tâches à tout moment d’une modification, plutôt que d’être forcé de suivre un ordre strict de spécifier-ensuite-planifier-ensuite-implementer comme le décrit le workflow SDD neutre en outils.

Une modification dans OpenSpec produit jusqu’à quatre artefacts Markdown dans son propre dossier :

Artefact But
proposal.md Pourquoi la modification existe et ce qu’elle change, en langage clair
specs/ Exigences delta et scénarios — la spécification testable pour cette modification
design.md Approche technique optionnelle, pour les modifications qui en ont besoin
tasks.md La liste de contrôle d’implémentation sur laquelle l’agent travaille

Une fois une modification implémentée et archivée, ses spécifications delta fusionnent dans openspec/specs/, qui devient la description durable et à jour de votre système — la même idée de « spécification comme source de vérité » couverte dans Qu’est-ce que le développement dirigé par des spécifications ?, mais limitée à une modification à la fois au lieu d’être écrite d’un coup.

Installer OpenSpec

OpenSpec est une CLI Node.js, vous avez donc besoin de Node 20.19.0 ou plus récent sur votre machine.

node --version

Installez la CLI globalement avec npm, puis vérifiez qu’elle est bien sur votre PATH :

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

Deno, pnpm, yarn, bun et nix sont également des voies d’installation supportées si cela correspond mieux à votre configuration que npm. Une fois installé, initialisez-le dans un projet :

cd votre-projet
openspec init

openspec init demande quels outils IA vous utilisez et écrit les fichiers de compétences et de commandes correspondants — OpenSpec supporte plus de 30 assistants, y compris Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro et OpenCode. Pour une CI ou une installation scriptée, sautez entièrement le sélecteur :

openspec init --tools claude,cursor   # configurer des outils spécifiques
openspec init --tools all             # tous les outils supportés
openspec init --tools none            # seulement la structure openspec/, pas de fichiers d'outils

Redémarrez votre IDE par la suite pour qu’il récupère les compétences et commandes nouvellement écrites. Si vous préférez que votre assistant fasse toute l’installation pour vous, OpenSpec fournit un prompt de configuration que vous pouvez coller dans Claude Code ou un autre agent, qui exécute l’installation, lance openspec init et rapporte ce qu’il a configuré.

Le workflow principal : Explorer, Proposer, Appliquer, Archiver

C’est la seule chose qui pose problème à presque tout le monde le premier jour : les commandes openspec s’exécutent dans votre terminal, mais les commandes /opsx: s’exécutent dans la fenêtre de chat de votre assistant IA. Il n’y a pas de « mode interactif » séparé à activer — taper la commande slash dans le chat est la façon de commencer.

flowchart LR A["/opsx:explore (optionnel)"] --> B["/opsx:propose nom-du-changement"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs fusionnées| E["openspec/specs/"]
  • /opsx:explore est un partenaire de réflexion sans enjeu. Il lit la partie pertinente de votre base de code, présente des options et élabore un plan avant que quoi que ce soit soit écrit sur disque — une habitude à prendre spécifiquement parce qu’elle empêche un agent zélé de construire confiante le mauvais truc.
  • /opsx:propose <nom> crée openspec/changes/<nom>/ et rédige la proposition, les spécifications delta, la conception optionnelle et la liste des tâches en une seule étape. Vous révisez le plan ici, avant le début de l’implémentation.
  • /opsx:apply travaille sur la liste des tâches, cochant les éléments au fur et à mesure. Comme la progression réside dans les fichiers et non seulement dans l’historique du chat, vous pouvez effacer votre fenêtre de contexte ou démarrer une nouvelle session et reprendre exactement là où /opsx:apply s’était arrêté.
  • /opsx:archive archive la modification terminée dans openspec/changes/archive/AAAA-MM-JJ-<nom>/ et fusionne ses spécifications delta dans l’arbre canonique openspec/specs/.

Le profil core par défaut installe exactement ces quatre commandes ainsi que update et sync. Un profil élargi ajoute new, continue, ff, verify, bulk-archive et onboard pour les équipes qui souhaitent créer un artefact à la fois au lieu de tout d’un coup — passez-y avec openspec config profile suivi de openspec update.

Chaque outil orthographie la même commande différemment selon la façon dont il charge les instructions personnalisées : /opsx:propose dans Claude Code, /opsx-propose dans Cursor et GitHub Copilot, @opsx-propose dans Amazon Q, ou $openspec-propose dans Codex. openspec init affiche la forme exacte pour les outils que vous avez choisis, donc le correctif le plus rapide pour « rien ne s’est passé quand j’ai tapé la commande » est généralement de relire cette indication affichée plutôt que de deviner.

À quoi ressemble une modification sur disque

Un dossier de modification sous openspec/changes/add-dark-mode/ contient typiquement une proposition, une spécification delta et une liste de tâches comme celle-ci :

## Exigences ADDED

### Exigence : Sélection du thème
L'application doit (SHALL) permettre aux utilisateurs de basculer entre les thèmes clair et sombre,
en utilisant la préférence système par défaut.

#### Scénario : L'utilisateur active le mode sombre
- **QUAND** l'utilisateur clique sur le sélecteur de thème
- **ALORS** l'application passe en mode sombre et persiste le choix

Ce format de delta ADDED/MODIFIED/REMOVED est le mécanisme qui permet à OpenSpec d’éviter de réécrire un fichier de spécification entier pour une modification d’un champ. C’est aussi pourquoi OpenSpec est explicitement tourné vers le brownfield en premier plutôt que le greenfield : vous ne documentez jamais votre application entière avant d’en tirer une valeur, vous documentez juste la tranche touchée par chaque modification réelle, et openspec/specs/ se remplit naturellement au fil de mois de travail normal.

Commandes CLI utiles pour vérifier cet état sans quitter le terminal :

openspec list                 # modifications actives
openspec show add-dark-mode   # afficher les artefacts d'une modification
openspec validate --all       # vérifier le formatage des specs dans tout le projet
openspec view                 # tableau de bord interactif

Commitez tout le dossier openspec/ dans git. Les modifications actives et l’archive sont censées devenir un enregistrement durable et versionné de ce que votre système fait et pourquoi il a changé — et non un brouillon que vous supprimez après fusion.

Adopter OpenSpec sur une base de code existante

La préoccupation la plus courante des équipes évaluant OpenSpec sur un projet réel est une version de « mon application a 80 000 lignes d’âge, dois-je tout spécifier d’abord ? » Non. Les conseils d’OpenSpec sont directs à ce sujet : choisissez quelque chose de petit et réel que vous alliez déjà construire cette semaine, lancez /opsx:explore sur la zone que vous allez toucher pour que l’agent cartographie comment les choses fonctionnent réellement d’abord, puis /opsx:propose une modification limitée à cette tranche uniquement.

Si vous avez déjà des PRDs, documents SRS ou documents de conception dans Notion ou Confluence, traitez-les comme matière source pour l’exploration plutôt que comme quelque chose à convertir en masse en spécifications. Collez la section pertinente dans une session /opsx:explore et laissez l’agent en dégager un delta ciblé ; une conversion mécanique unique d’un PRD de quarante pages tend à produire une spécification que personne ne fait confiance six mois plus tard. Pour les équipes qui souhaitent une première exécution guidée et narrée au lieu de sauter directement sur une modification réelle, la commande élargie /opsx:onboard scanne votre base de code pour une petite amélioration sûre et parcourt la boucle complète dessus.

Questions et problèmes courants

Voici les problèmes qui apparaissent régulièrement sur le Discord d’OpenSpec, les issues GitHub et les fils Reddit sur des sous-reddits comme r/cursor, r/RooCode et r/opencodeCLI.

« J’ai tapé la commande slash et rien ne s’est passé. » Presque toujours l’un de ces cas : vous l’avez tapée dans le terminal au lieu du chat de votre assistant, votre IDE n’a pas redémarré depuis que openspec init s’est exécuté, ou la version de la CLI est assez vieille pour que openspec update signale que tout est à jour sans jamais écrire les fichiers de workflow plus récents. Exécutez openspec update, redémarrez l’IDE et confirmez que les dossiers de compétences existent (.claude/skills/openspec-* pour Claude Code, ou l’équivalent de votre outil dans la liste des outils supportés).

« L’IA génère beaucoup plus de spécifications que ce dont j’ai besoin. » C’est la plainte la plus citée dans les articles plus longs : un agent peut transformer une fonctionnalité de trente minutes en une spécification de 800 lignes. OpenSpec limite le champ context: injecté dans chaque requête à 50 Ko spécifiquement pour forcer la discipline, mais les spécifications delta elles-mêmes n’ont pas de limite stricte, donc réduire les spécifications générées à ce qui est réellement porteur est une habitude que vous devez maintenir vous-même, et non quelque chose que l’outil impose pour vous.

« Deux modifications ont touché la même exigence et l’une a silencieusement supprimé le scénario de l’autre. » C’est un cas limite réel et documenté : l’archivage applique un delta MODIFIED comme un remplacement de bloc entier clé sur le nom de l’exigence, donc si deux modifications en cours modifient toutes deux la même exigence, l’archivage de la seconde surécrivait autrefois les scénarios de la première sans avertissement. Les versions actuelles ajoutent une vérification de dérive qui annule l’archivage et vous dit de rafraîchir la spécification de la modification d’abord — mais il vaut toujours la peine de connaître ce mode d’échec si vous exécutez plusieurs modifications sur la même zone en parallèle.

« Quel modèle IA devrais-je vraiment utiliser avec ? » Les propres documents d’OpenSpec recommandent des modèles de haute raisonnement pour la planification et l’implémentation — les modèles de classe Opus et de classe Codex sont cités spécifiquement — et d’effacer votre fenêtre de contexte avant l’implémentation, car un contexte propre produit des résultats mesurables meilleurs qu’une session longue et accumulée.

« En quoi est-ce différent de Spec Kit, Kiro, Superpowers ou BMAD ? » C’est la question Reddit la plus fréquente de loin, et la réponse honnête est « le poids du processus ». Le README d’OpenSpec cadre la comparaison directement : Spec Kit est rigoureux mais plus lourd, avec plus de Markdown et des portails de phases rigides ; Kiro est puissant mais vous verrouille dans l’IDE d’AWS et les modèles Claude ; OpenSpec échange une partie de cette structure initiale pour la capacité d’itérer librement et de travailler avec n’importe quel assistant que vous avez déjà ouvert. Pour le détail complet contre Spec Kit, Kiro, les compétences Claude Code, BMAD-METHOD et Superpowers, voir la comparaison d’outils SDD dédiée.

« L’IA suit-elle vraiment la spécification qu’elle vient d’écrire ? » Pas toujours, et c’est un problème documenté dans les outils SDD en général, pas unique à OpenSpec — une grande fenêtre de contexte ne signifie pas que l’agent accorde une attention égale à chaque partie de celle-ci. La commande /opsx:verify existe spécifiquement pour attraper le code généré qui contredit sa propre spécification, et il vaut la peine de l’exécuter sur n’importe quoi non trivial plutôt que de faire aveuglément confiance à l’implémentation.

« En ai-je besoin pour une correction d’une ligne ? » Non. Les propres FAQ d’OpenSpec le disent : utilisez-le là où l’accord importe, c’est-à-dire la plupart des travaux non triviaux multi-fichiers, et sautez-le pour une correction de faute de frappe ou un prototype jetable que vous supprimerez dans une semaine.

« Comment empêcher un agent de reproposer quelque chose que nous avons déjà rejeté ? » /opsx:archive n’a pas de statut dédié pour une modification rejetée, donc rien ne dit à une proposition future qu’une idée a déjà été investiguée et refusée. Voir Propositions rejetées OpenSpec : une convention de mémoire de décision pour le motif decision.md et la règle de configuration qui fait chercher un agent dans l’archive avant de proposer à nouveau.

Quand OpenSpec convient et quand il ne convient pas

Bonne correspondance :

  • Bases de code brownfield où vous voulez des spécifications révisables sans documenter l’ensemble du système au préalable.
  • Développeurs solos et petites équipes qui veulent moins de cérémonie que Spec Kit tout en obtenant un plan écrit avant le code.
  • Travail qui s’étend sur plusieurs fichiers, un changement de schéma, ou n’importe quoi pour lequel un ingénieur junior voudrait raisonnablement un court document de conception.
  • Équipes déjà engagées à réviser les plans dans les demandes de tirage (pull requests) — les spécifications delta se différentient proprement car elles décrivent seulement ce qui a changé.

Correspondance plus faible :

  • Corrections de bug d’une ligne et prototypes jetables, où l’étape de révision de la proposition coûte plus qu’elle n’économise.
  • Équipes qui ont besoin de la structure plus lourde et plus prescriptive de Spec Kit ou d’une expérience native AWS et intégrée à l’IDE comme Kiro — voir le cadre de décision dans la comparaison des outils pour savoir où chaque outil gagne.
  • Fonctionnalités inter-repos aujourd’hui, à moins que vous ne soyez prêt à essayer la fonctionnalité beta stores d’OpenSpec, qui déplace la planification dans un dépôt partagé propre pour que plusieurs bases de code et agents puissent lire le même plan.
  • Quiconque est encore en train de décider si une fonctionnalité donnée mérite une spécification du tout — lisez Développement dirigé par des spécifications vs Vibe Coding d’abord, car OpenSpec n’aide que si vous avez déjà décidé que la structure vaut le surcroît.

Conclusion

Le pari d’OpenSpec est que la plupart des douleurs du développement dirigé par des spécifications proviennent de la cérémonie, et non de l’idée sous-jacente de se mettre d’accord sur un plan avant que le code n’existe. Des deltas au lieu de réécritures complètes, pas de phases verrouillées et un workflow brownfield-first le rendent notablement plus léger à adopter sur une base de code que vous n’avez pas construite de zéro que Spec Kit ou Kiro. Les compromis sont réels aussi — l’obésité de spécifications est un risque réel sans discipline, la gestion des conflits autour de modifications simultanées d’une même exigence est encore en maturation, et l’écosystème est plus jeune que les outils de GitHub eux-mêmes. Installez-le sur un projet réel, faites passer une petite modification par explorer-proposer-appliquer-archiver de bout en bout, et décidez à partir de là si la cérémonie plus légère vaut le coup par rapport à votre charge de travail réelle.

Liens utiles

S'abonner

Recevez de nouveaux articles sur les systèmes, l'infrastructure et l'ingénierie IA.