Prise en main rapide d’OpenSpec : installation, flux de travail et erreurs courantes

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

Sommaire

OpenSpec est un outil CLI gratuit et open source de Fission AI qui permet à vous et votre agent de codage de convenir d’un changement en Markdown brut avant que du code soit écrit, sans la cérémonie à phases bloquantes des frameworks plus lourds pilotés par spécifications.

La plupart des équipes qui tentent le Développement Piloté par Spécifications (Spec-Driven Development) butent sur le même arbitrage : assez de processus pour empêcher un agent de deviner, mais sans tant de structure qu’une correction de bug de cinquante lignes nécessite un document de proposition. La réponse d’OpenSpec est de sauter entièrement l’instinct de « documenter d’abord tout le système » et d’écrire des spécifications uniquement pour ce qu’un changement touche réellement, en utilisant des deltas ADDED, MODIFIED et REMOVED plutôt qu’une réécriture complète à chaque fois.

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

Cette conception centrée sur le changement est aussi la raison pour laquelle OpenSpec apparaît souvent à côté de GitHub Spec Kit, Kiro et Superpowers dans la comparaison des catégories d’outils SDD – c’est souvent le choix privilégié 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 que vous utilisez réellement au quotidien, à quoi ressemble un changement sur le disque, ainsi que les questions et les plaintes qui apparaissent le plus souvent sur Reddit et dans le suiveur de problèmes d’OpenSpec lui-même.

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 pas seulement pour le greenfield. Concrètement, cela signifie qu’il n’y a pas de phases verrouillées – vous pouvez modifier une proposition, une spécification ou une liste de tâches à n’importe quel point d’un changement, plutôt que d’être forcé de suivre l’ordre strict de spécifier-ensuite-planifier-ensuite-implémenter, comme le décrit le workflow SDD neutre en outils.

Un changement dans OpenSpec produit jusqu’à quatre artefacts Markdown dans son propre dossier :

Artefact Objectif
proposal.md Pourquoi le changement existe et ce qu’il modifie, en langage clair
specs/ Exigences et scénarios delta – la spécification testable pour ce changement
design.md Approche technique optionnelle, pour les changements qui en nécessitent une
tasks.md La liste de vérification d’implémentation sur laquelle l’agent travaille

Une fois un changement implémenté et archivé, 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é » traitée dans Qu’est-ce que le Développement Piloté par Spécifications ?, mais limitée à un changement à la fois au lieu d’être écrite d’un coup.

Installation d’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 présente dans votre PATH :

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

Deno, pnpm, yarn, bun et nix sont également des chemins d’installation pris en charge si cela convient mieux à votre configuration que npm. Une fois installé, initialisez-le dans un projet :

cd your-project
openspec init

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

openspec init --tools claude,cursor   # configure des outils spécifiques
openspec init --tools all             # tous les outils pris en charge
openspec init --tools none            # uniquement la structure openspec/, pas de fichiers d'outils

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

Le Workflow Central : Explorer, Proposer, Appliquer, Archiver

C’est la chose qui fait trébucher 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 discussion de votre assistant IA. Il n’y a pas de mode « interactif » séparé à entrer – taper la commande avec slash dans le chat est la façon de démarrer.

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, expose les options et forme un plan avant que quoi que ce soit soit écrit sur le disque – c’est une habitude à prendre, spécifiquement parce qu’elle empêche un agent enthousiaste de construire confamment la mauvaise chose.
  • /opsx:propose <nom> crée openspec/changes/<nom>/ et rédige la proposition, les spécifications delta, le design optionnel et la liste des tâches en une seule étape. Vous révisez le plan ici, avant que l’implémentation ne commence.
  • /opsx:apply travaille sur la liste des tâches, cochant les éléments au fur et à mesure. Comme les progrès vivent dans des fichiers plutôt que seulement dans l’historique du chat, vous pouvez vider 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 le changement terminé dans openspec/changes/archive/AAAA-MM-JJ-<nom>/ et fusionne ses spécifications delta dans l’arborescence canonique openspec/specs/.

Le profil core par défaut installe exactement ces quatre commandes plus update et sync. Un profil étendu ajoute new, continue, ff, verify, bulk-archive et onboard pour les équipes qui souhaitent créer un artefact à la fois plutôt que tous d’un coup – basculez-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 cet indice affiché plutôt que de deviner.

À quoi ressemble un changement sur le disque

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

## Exigences AJOUTÉES

### Exigence : Sélection du thème
L'application DOIT 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 basculement de thème
- **ALORS** l'application passe en mode sombre et persiste le choix

Ce format delta ADDED/MODIFIED/REMOVED est le mécanisme qui permet à OpenSpec d’éviter de réécrire un fichier de spécification entier pour un changement à un seul champ. C’est aussi la raison pour laquelle OpenSpec est explicitement orienté brownfield d’abord plutôt que greenfield d’abord : vous ne documentez jamais toute votre application avant d’obtenir de la valeur, vous ne documentez que la tranche que chaque changement réel touche, 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                 # changements actifs
openspec show add-dark-mode   # afficher les artefacts d'un changement
openspec validate --all       # vérifier le formatage des specs dans tout le projet
openspec view                 # tableau de bord interactif

Committez tout le dossier openspec/ dans git. Les changements actifs et l’archive sont censés devenir un enregistrement durable et versionné de ce que votre système fait et pourquoi il a changé – pas un brouillon que vous supprimez après la 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 variante de « mon application a 80 000 lignes, dois-je d’abord spécifier tout cela ? » Non. Les propres directives d’OpenSpec sont claires à ce sujet : choisissez quelque chose de petit et de réel que vous alliez de toute façon construire cette semaine, exécutez /opsx:explore sur la zone que vous allez toucher pour que l’agent cartographie comment les choses fonctionnent réellement d’abord, puis proposez avec /opsx:propose un changement limité à cette seule tranche.

Si vous avez déjà des PRD, des documents SRS ou des documents de design dans Notion ou Confluence, traitez-les comme matière première 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 façonner un delta ciblé à partir de cela ; une conversion mécanique ponctuelle d’un PRD de quarante pages a tendance à produire une spécification dont personne ne se fait confiance six mois plus tard. Pour les équipes qui veulent une première exécution guidée et narrée plutôt que de sauter directement dans un changement réel, la commande étendue /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 problèmes GitHub et les fils Reddit dans des sous-rédits comme r/cursor, r/RooCode et r/opencodeCLI.

« J’ai tapé la commande slash et rien ne s’est passé. » Presque toujours l’une de ces raisons : vous l’avez tapée dans le terminal au lieu du chat de votre assistant, votre IDE n’a pas redémarré depuis l’exécution de openspec init, ou la version de la CLI est assez ancienne pour que openspec update déclare tout à 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 depuis la liste des outils pris en charge).

« L’IA génère beaucoup plus de spécification que je n’en 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 plafonne 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, pas quelque chose que l’outil impose pour vous.

« Deux changements ont touché la même exigence et l’un a silencieusement supprimé le scénario de l’autre. » C’est un cas de bord réel et documenté : l’archivage applique un delta MODIFIED comme un remplacement de bloc entier indexé par le nom de l’exigence, donc si deux changements en cours modifient tous les deux la même exigence, l’archivage du second écrasait auparavant les scénarios du premier sans avertissement. Les versions actuelles ajoutent une vérification de dérive qui interrompt l’archivage et vous indique de rafraîchir d’abord la spécification du changement – mais il vaut toujours la peine de connaître ce mode de défaillance si vous exécutez plusieurs changements sur la même zone en parallèle.

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

« En quoi est-ce différent de Spec Kit, Kiro, Superpowers ou BMAD ? » C’est la question Reddit la plus fréquente, et la réponse honnête est « le poids du processus ». Le README d’OpenSpec présente la comparaison directement : Spec Kit est rigoureux mais plus lourd, avec plus de Markdown et des portes de phase 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 contre la capacité d’itérer librement et de travailler avec l’assistant que vous avez déjà ouvert. Pour le découpage complet face à Spec Kit, Kiro, les compétences Claude Code, BMAD-METHOD et Superpowers, consultez la comparaison des outils SDD dédiée.

« L’IA suit-elle réellement la spécification qu’elle vient d’écrire ? » Pas toujours, et c’est un problème documenté à travers les outils SDD en général, pas spécifique à OpenSpec – une grande fenêtre de contexte ne signifie pas que l’agent accorde une attention égale à chaque partie. 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 tout ce qui n’est pas trivial plutôt que de faire aveuglément confiance à l’implémentation.

« Est-ce que j’en ai besoin pour une correction d’une ligne ? » Non. La FAQ d’OpenSpec dit autant : utilisez-le là où l’accord compte, c’est-à-dire la plupart des travaux non triviaux et multi-fichiers, et passez-le pour une correction de faute de frappe ou un prototype jetable que vous supprimerez dans une semaine.

Quand OpenSpec Convient et Quand Non

Bonne adéquation :

  • Bases de code brownfield où vous voulez des spécifications révisables sans documenter l’ensemble du système au préalable.
  • Développeurs solo et petites équipes qui veulent une cérémonie plus légère que Spec Kit tout en obtenant un plan écrit avant le code.
  • Travaux qui s’étendent sur plusieurs fichiers, un changement de schéma, ou tout ce pour quoi un ingénieur junior raisonnablement voudrait un court document de design.
  • Équipes déjà engagées à revoir les plans dans les pull requests – les spécifications delta se diffusent proprement car elles ne décrivent que ce qui a changé.

Adéquation plus faible :

  • Corrections de bugs d’une ligne et prototypes jetables, où l’étape proposition-révision coûte plus qu’elle ne sauve.
  • É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 décisionnel dans la comparaison des outils pour savoir où chaque outil gagne.
  • Fonctionnalités inter- dépôt aujourd’hui, à moins que vous ne soyez disposé à essayer la fonctionnalité bêta stores d’OpenSpec, qui déplace la planification dans son propre dépôt partagé afin 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 Piloté par Spécifications vs Vibe Coding d’abord, car OpenSpec n’aide qu’une fois que vous avez déjà décidé que la structure vaut l’effort.

Conclusion

Le pari d’OpenSpec est que la plupart des douleurs du Développement Piloté par Spécifications proviennent de la cérémonie, pas de l’idée sous-jacente de convenir d’un plan avant que le code n’existe. Les deltas plutôt que les réécritures complètes, l’absence de phases verrouillées et un workflow brownfield d’abord le rendent nettement 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 – la gonflement des spécifications est un risque réel sans discipline, la gestion des conflits autour des changements simultanés d’une même exigence est encore en cours de 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 un petit changement à travers explore-propose-apply-archive de bout en bout, et décidez à partir de là si la cérémonie plus légère vaut son poids dans l’or 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.