Démystifier OpenSpec

Je suis entré dans OpenSpec en m'attendant à quelques commandes et un peu de Markdown. C'est du moins l'impression que j'avais eue en l'essayant à ses débuts.

Puis j'ai ouvert la documentation et j'ai trouvé des profils, des schémas, des artefacts, des fichiers de config, des flux d'archive, OPSX et des delta specs. J'ai passé plus de temps que je ne veux l'admettre à passer d'un onglet à l'autre, à essayer de tout garder en tête. Qu'est-ce exactement qu'un artefact ? Pourquoi y a-t-il des profils et des schémas ? Si les deux affectent le workflow, pourquoi les deux doivent-ils exister ?

C'est l'explication que j'aurais aimé avoir au lieu de ces onglets.

Qu'est-ce qu'OpenSpec ?

OpenSpec est un framework de développement spec-driven. Il vit dans votre dépôt aux côtés de votre code, et il fonctionne avec la plupart des agents de code : Claude Code, Cursor, Codex, GitHub Copilot, OpenCode et d'autres. On l'installe avec npm install -g @fission-ai/openspec@latest, et il ajoute des commandes de planification à votre agent.

L'idée est simple. Avant d'écrire du code, on décrit le changement qu'on veut faire. OpenSpec génère une proposition, un document de design, une décomposition des tâches et un delta spec montrant comment les exigences vont changer. On révise ce plan, on l'affine, puis on implémente. Quand le changement est terminé, le delta spec est appliqué aux specs canoniques, de sorte que les exigences dans le dépôt restent à jour.

Ce dernière partie est ce qui le distingue du mode plan intégré à l'agent. Le mode plan disparaît quand la session de chat se termine. Les specs d'OpenSpec restent dans le dépôt comme documentation vivante, commitées dans git, vérifiables dans les PRs.

Le projet est open source sur openspec.dev.

La version courte

OpenSpec est devenu beaucoup plus facile pour moi une fois réduit à quatre questions :

Les artefacts sont les sorties produites par ce système : propositions, specs, designs, tâches ou toute autre chose que votre schéma définit.

Pourquoi la terminologie donne l'impression d'être en couches

Une partie de la confusion a plus de sens quand on regarde comment OpenSpec a évolué.

Le workflow de départ était intentionnellement petit :

propose -> apply -> archive

L'étape de proposition créait les documents de planification, l'agent implémentait le changement, et archive repliait le résultat dans les specs du projet.

Ensuite OPSX a rendu le système plus flexible. La planification est devenue un ensemble d'artefacts discrets reliés par des dépendances. On pouvait les créer de façon incrémentale, les réviser au fur et à mesure, et personnaliser le graphe au lieu d'accepter un processus figé.

Cette flexibilité a introduit plus d'actions :

new -> continue or ff -> apply -> verify -> archive

OpenSpec 1.2 a ensuite introduit les profils. Le but n'était pas d'ajouter une autre abstraction de planification. Les profils contrôlent quelles skills et commandes de workflow sont installées, pour que les gens qui veulent le chemin court n'aient pas besoin de chaque commande étendue dans le contexte de leur agent.

Le profil core actuel donne le chemin rapide :

explore -> propose -> apply -> sync -> archive

Le workflow étendu expose des actions comme new, continue, ff et verify quand on veut un contrôle plus fin.

Cette histoire compte. Les profils et les schémas peuvent ressembler à deux générations de la même idée. Ce n'est pas le cas, et cette confusion est où j'ai perdu le plus de temps.

Profils vs. Schémas

C'est là que je suis resté bloqué le plus longtemps. J'ai supposé que les profils et les schémas étaient des façons concurrentes de définir un workflow.

Ils sont orthogonaux.

Un profil contrôle les actions disponibles. Un schéma contrôle la structure de planification sur laquelle ces actions opèrent.

J'ai relu cette phrase dans la doc trois fois avant qu'elle ne prenne, donc je vais y passer un peu de temps.

Les profils choisissent les contrôles

Un profil ne définit pas proposal.md, design.md ou tasks.md. Il décide quelles actions de workflow OpenSpec installe pour l'outil d'IA.

Avec le profil core, /opsx:propose donne l'expérience simple : on décrit le changement et on génère les artefacts de planification en une seule passe.

Avec une sélection étendue, on peut être plus délibéré :

• /opsx:new crée l'échafaudage du changement.
• /opsx:continue crée l'artefact disponible suivant.
• /opsx:ff crée tous les artefacts de planification qui peuvent être générés.
• /opsx:verify compare l'implémentation avec les artefacts avant l'archive.

Mon raccourci de départ était proche mais pas tout à fait juste. Le profil ne dit pas « tout générer » ni « une seule chose ». Le profil rend ces actions disponibles ; la commande qu'on choisit décide de ce qui se passe ensuite.

Les schémas définissent le graphe de planification

Les schémas répondent à une autre question : que devrait contenir ce changement ?

Le schéma par défaut spec-driven contient des artefacts comme proposition, specs, design et tâches. Il décrit aussi leurs dépendances. Une vue simplifiée ressemble à ça :

              proposal
              /      \
           specs    design
              \      /
                tasks

Ce graphe est la raison pour laquelle /opsx:continue peut dire quel artefact est prêt et quel artefact reste bloqué. OpenSpec vérifie ce qui existe sur le disque et suit les règles de dépendance du schéma.

Un schéma personnalisé pourrait ajouter un artefact de recherche ou de revue de sécurité :

research -> proposal -> specs -> security-review -> tasks

Le profil n'a pas besoin de changer. La même action continue ou ff peut traverser un schéma différent.

C'est là que profils et schémas se sont enfin séparés dans ma tête : le profil donne les contrôles ; le schéma donne à ces contrôles quelque chose sur quoi opérer.

Ce qu'OpenSpec veut dire par « Artefact »

Le mot artefact a fait paraître le système plus abstrait qu'il ne l'est.

Un artefact est une sortie définie par le schéma. La plupart sont des fichiers Markdown ou un groupe de fichiers Markdown :

proposal.md
design.md
tasks.md
specs/<capability>/spec.md

Il n'y a pas d'objet artefact spécial qui tourne en arrière-plan. OpenSpec détermine l'état en grande partie depuis le système de fichiers : si la sortie requise existe, cet artefact est fait et ses dépendants peuvent devenir disponibles.

Le terme compte quand même parce qu'un schéma peut définir plus d'une forme de fichier. L'artefact specs, par exemple, peut générer un répertoire de delta specs plutôt qu'un seul fichier fixe. Mais en tant qu'utilisateur, la traduction utile est :

Artefact = une sortie de planification produite pendant un changement.

Proposition, Specs, Design et Tâches en termes familiers

Je les ai trouvés beaucoup plus faciles à comprendre à travers le langage ordinaire de projet :

Une fois que j'ai arrêté de les traiter comme des inventions spécifiques à OpenSpec, le workflow a paru familier. Ce sont simplement les documents qu'une équipe correcte produirait de toute façon, sauf qu'ici le tooling les connaît.

Main Specs vs. Delta Specs

Il y a une distinction que j'ai manquée pendant un moment : OpenSpec gère deux types de spécification.

Les specs sous openspec/specs/ décrivent le système tel qu'il se comporte maintenant. Ils sont la source canonique de vérité, organisés par capacité.

Les specs à l'intérieur d'un changement décrivent uniquement ce que ce changement ajoute, modifie ou retire. Ce sont des delta specs.

openspec/specs/                 current system
openspec/changes/add-2fa/specs/ proposed difference

C'est pourquoi le changement peut être révisé sans réécrire toute la spécification. Les relecteurs voient la différence, pas une seconde copie de tout.

Quand le changement est synchronisé ou archivé, ces deltas sont appliqués aux specs canoniques. Les exigences ajoutées sont annexées, les exigences modifiées remplacent leurs versions précédentes, les exigences retirées sont supprimées.

C'est ce qu'OpenSpec veut dire quand il parle de préserver les spécifications comme documentation vivante.

Ce que config.yaml fait réellement

Je m'attendais à ce que openspec/config.yaml définisse le workflow. Ce n'est pas le cas.

Il configure le projet autour du workflow :

schema: spec-driven

context: |
  Stack: TypeScript, React, PostgreSQL
  Public APIs must remain backwards compatible

rules:
  proposal:
    - Include a rollback plan
  tasks:
    - Include tests for every requirement

Le fichier a trois travaux principaux :

1. Sélectionner le schéma par défaut.
2. Injecter le contexte du projet dans les instructions de chaque artefact.
3. Injecter des règles supplémentaires dans des artefacts spécifiques par ID.

Il n'ajoute pas de nouveaux artefacts et ne change pas leurs dépendances. Ça appartient à un schéma.

Cette distinction donne une règle utile :

• Si on veut changer quels fichiers existent, on change le schéma.
• Si on veut changer ce que les fichiers générés doivent prendre en compte, on change la config.

Schémas vs. Skills

C'est là que je me suis trompé ensuite. Je pensais que les schémas étaient aussi l'endroit où tout le comportement de l'agent devait vivre.

Les schémas peuvent contenir des modèles et des instructions pour générer leurs artefacts, mais ils ne remplacent pas les skills.

Un schéma décrit le modèle de planification : les IDs d'artefact, les chemins de sortie, les modèles et les dépendances. Les skills OpenSpec générées apprennent à l'outil d'IA comment réaliser des actions comme propose, continue, apply, sync et archive.

Donc si je veux un nouveau security-review.md avant les tâches, c'est un changement de schéma.

Si je veux que mon agent de code suive TDD pendant l'implémentation, ça appartient à une skill d'implémentation ou à une instruction de projet. Si je veux simplement que chaque liste de tâches générée mentionne des tests, une règle tasks dans config.yaml peut suffire.

Ce sont des préoccupations liées, mais elles se situent à des couches différentes, et les mélanger a été la source de la plupart de ma confusion.

Est-ce qu'Archive empêche la documentation obsolète ?

C'est la dernière chose que je n'arrivais pas à évacuer.

Archive fait deux choses utiles : il déplace le changement terminé dans l'historique et s'assure que les delta specs peuvent être synchronisés dans les specs canoniques. Ça évite de laisser plusieurs versions concurrentes des exigences dispersées dans les dossiers de changements actifs.

Ce qu'Archive ne fait pas, c'est prouver que le code correspond à la spécification.

L'action étendue /opsx:verify vérifie l'exhaustivité, l'exactitude et la cohérence entre l'implémentation et les artefacts de planification. Même là, le processus dépend toujours de la revue et de la discipline d'ingénierie. Aucune commande archive ne peut rendre vraie une spec inexacte.

OpenSpec réduit donc un type de dérive de documentation : les documents d'exigences abandonnés ou concurrents. Il ne comble pas de lui-même l'écart entre l'intention écrite et le logiciel réel. Cette partie reste à votre charge.

Le modèle mental qui a fini par s'éclairer

Voici la version que je garde maintenant en tête :

Profile -> chooses the available workflow actions
Schema  -> defines the artifact dependency graph
Config  -> injects project context and artifact-specific rules
Skills  -> teach the agent how to perform those actions
Files   -> record the state of the change

Ou, en une phrase :

OpenSpec installe un ensemble d'actions d'agent, les exécute sur un graphe défini par schéma, façonne leur sortie avec la config du projet et enregistre la progression sous forme de fichiers dans le dépôt.

Une fois que j'ai vu ça comme ça, les termes comme profil, schéma et artefact ont arrêté de se faire concurrence. Chacun avait une frontière claire.

Le plus dur dans OpenSpec n'est pas le nombre de commandes. C'est que les mots familiers portent des significations très spécifiques dans le système, et la documentation ne rend pas toujours ces frontières évidentes. Si vous êtes bloqué sur la terminologie, vous n'êtes pas seul, ça m'a pris un moment, et la plupart de ce post est le chemin que j'ai pris pour arriver ici.

Pour aller plus loin

• Getting Started
• Workflows
• OPSX Workflow
• Customization