OpenSpec

Glossaire ​

Tous les termes OpenSpec réunis en un seul endroit, définis en langage clair. Parcourez-le une fois et le reste de la documentation se lira plus vite.

Les termes sont regroupés par sujet, puis classés alphabétiquement au sein de chaque groupe.

Les noms principaux ​

Spécification. Un document décrivant le comportement d'une partie de votre système. Les spécifications se trouvent dans openspec/specs/, sont organisées par domaine et sont composées de exigences et de scénarios. La spécification est la réponse consensuelle à la question « que fait ce logiciel ? » Voir Concepts.

Source de vérité. l'ensemble du répertoire openspec/specs/. Il contient le comportement actuel et consensuel de votre système. Les changements proposent des modifications ; l'archivage les applique.

Changement. Une unité de travail, emballée sous forme de dossier dans openspec/changes/<name>/. Un changement contient tout ce qui concerne cette tâche : sa proposition, sa conception, ses tâches et les modifications de spécification qu'il introduit. Un changement, une fonctionnalité ou un correctif.

Artefact. Un document à l'intérieur d'un changement. Les artefacts standard sont la proposition, les spécifications delta, la conception et les tâches. Ils sont créés dans l'ordre des dépendances et se nourrissent mutuellement.

Spécification delta. Une spécification à l'intérieur d'un changement qui ne décrit que ce qui change, en utilisant des sections ADDED, MODIFIED et REMOVED, plutôt que de réénoncer l'ensemble de la spécification. C'est ce qui permet à OpenSpec de modifier proprement les systèmes existants. Voir Concepts.

Domaine. Un regroupement logique pour les spécifications, comme auth/, payments/ ou ui/. Vous choisissez des domaines qui correspondent à votre façon de penser votre système.

À l'intérieur d'une spécification ​

Exigence. Un comportement unique que le système doit posséder, généralement rédigé avec un mot-clé RFC 2119 : « Le système SHALL expirer les sessions après 30 minutes. » Les exigences énoncent le quoi, pas le comment.

Scénario. Un exemple concret et testable d'une exigence en action, généralement sous la forme Given/When/Then. Les scénarios rendent une exigence vérifiable : vous pourriez écrire un test automatisé à partir d'un seul.

Mots-clés RFC 2119. Les mots MUST, SHALL, SHOULD et MAY, qui portent une signification standardisée quant à l'exigence d'une règle. MUST et SHALL sont absolus. SHOULD est recommandé avec possibilité d'exceptions. MAY est optionnel. Le nom provient du document de normes internet qui les a définis.

Les artefacts ​

Proposition (proposal.md). Le pourquoi et le quoi d'un changement : son intention, son périmètre et son approche de haut niveau. Le premier artefact que vous créez.

Conception (design.md). Le comment : approche technique, décisions d'architecture et fichiers que vous prévoyez de modifier. Optionnel pour les changements simples.

Tâches (tasks.md). La liste de contrôle de l'implémentation, avec des cases à cocher. l'IA la parcourt pendant /opsx:apply et coche les éléments au fur et à mesure.

Le cycle de vie ​

Archivage. L'acte de terminer un changement. Ses spécifications delta fusionnent avec les spécifications principales et le dossier du changement est déplacé vers openspec/changes/archive/YYYY-MM-DD-<name>/. Après archivage, vos spécifications décrivent la nouvelle réalité. Voir Concepts.

Synchronisation. Fusionner les spécifications delta d'un changement dans les spécifications principales sans archiver le changement. Généralement automatique (l'archivage propose de le faire), mais disponible seul via /opsx:sync pour les changements de longue durée. Voir Commands.

Flux de travail et commandes ​

OPSX. Le flux de travail OpenSpec standard actuel, construit autour d'actions fluides plutôt que de phases rigides. Ses commandes slash commencent toutes par /opsx:. Voir OPSX Workflow.

Commande slash. Une commande que vous tapez dans le chat de votre assistant IA, comme /opsx:propose. Les commandes slash pilotent le flux de travail. Ce ne sont pas des commandes de terminal. Voir How Commands Work.

Explorer (/opsx:explore). La commande partenaire de réflexion. Elle lit votre base de code, compare les options et clarifie une idée vague en un plan concret, sans créer d'artefacts ni écrire de code. Le point de départ recommandé dès que vous avez un problème mais pas encore de plan. Voir Explore First.

CLI. Le programme openspec que vous exécutez dans votre terminal. Il configure les projets, liste et valide les changements, ouvre le tableau de bord et archive. La moitié terminal d'OpenSpec. Voir CLI.

Compétence. Un dossier d'instructions (.../skills/openspec-*/SKILL.md) que votre assistant IA détecte automatiquement et suit. Les compétences sont le standard émergent inter-outils pour livrer le flux de travail OpenSpec à votre assistant.

Fichier de commande. Un fichier de commande slash par outil (.../commands/opsx-*). Le mécanisme de livraison plus ancien, toujours pris en charge aux côtés des compétences. Vous n'y touchez presque jamais directement.

Profil. L'ensemble des commandes slash installées dans votre projet. Core (par défaut) comprend propose, explore, apply, update, sync, archive. L'ensemble étendu ajoute new, continue, ff, verify, bulk-archive, onboard. Modifiez-le avec openspec config profile.

Livraison. Indique si OpenSpec installe des compétences, des fichiers de commande ou les deux pour vos outils. Configuré globalement et appliqué avec openspec update.

Personnalisation ​

Schéma. La définition des artefacts dont dispose un flux de travail et de leurs dépendances mutuelles. Le défaut intégré est spec-driven (proposition → spécifications → conception → tâches). Vous pouvez le forker ou en écrire un vous-même. Voir Customization.

Gabarit. Un fichier Markdown à l'intérieur d'un schéma qui façonne ce que l'IA génère pour un artefact donné. Modifier un gabarit change immédiatement la sortie de l'IA, sans reconstruction.

Configuration du projet (openspec/config.yaml). Paramètres par projet : le schéma par défaut, le context: injecté dans chaque demande de planification et les rules: par artefact. La façon la plus simple d'enseigner à OpenSpec votre pile technique et vos conventions. Voir Customization.

Injection de contexte. Placer le contexte du projet dans le champ context: de config.yaml afin qu'il soit automatiquement ajouté à chaque artefact généré par l'IA. Plus fiable que d'espérer que l'IA lise un fichier séparé.

Graphe de dépendances. Le graphe orienté formé par les relations requires: des artefacts. C'est un DAG (graphe orienté acyclique : les flèches ne pointent que vers l'avant, jamais en boucle), et OpenSpec l'utilise pour savoir ce que vous pouvez créer ensuite.

Facilitateurs, non barrières. Le principe selon lequel les dépendances entre artefacts indiquent ce qui devient possible ensuite, et non ce qui est requis ensuite. Vous pouvez réviser et modifier n'importe quel artefact à tout moment. Voir Core Concepts at a Glance.

Coordination entre dépôts (bêta) ​

Ces termes ne s'appliquent que si votre planification s'étend à plus d'un dépôt. Ils sont en bêta. La plupart des utilisateurs peuvent les ignorer. Voir le Stores User Guide.

Store. Un dépôt autonome dont le seul rôle est la planification. Il a la même structure openspec/ que vous connaissez déjà (spécifications et changements) plus un petit fichier d'identité. Vous l'enregistrez une fois sur votre machine, par nom, et ensuite n'importe quelle commande OpenSpec peut y travailler depuis n'importe où.

Référence. Une déclaration, dans le openspec/config.yaml d'un dépôt de code, d'un store dont ce dépôt se sert. Les références sont en lecture seule : le dépôt conserve sa propre racine et openspec instructions obtient un index des spécifications du store référencé, chacune avec la commande exacte pour la récupérer.

Contexte de travail. Ce que openspec context assemble pour le dépôt actuel : sa racine OpenSpec plus chaque store qu'il référence, chacun avec la façon de le récupérer. La réponse à la question « avec quoi travaille-je ? »

Workset. Un ensemble personnel de dossiers locaux que vous ouvrez ensemble (un store aux côtés des dépôts de code sur lesquels vous travaillez). Créé explicitement avec openspec workset create ; rien concernant ces chemins locaux n'est commité dans le dépôt de planification partagé.

Voir aussi ​