Exemples et recettes

Des changements réels, du début à la fin. Chaque recette montre les commandes que vous saisiriez et ce que vous verriez en retour, afin que vous puissiez associer votre situation à un modèle et le copier. Elles utilisent les commandes core par défaut (propose, explore, apply, update, sync, archive) ; lorsque l'ensemble étendu s'avère utile, cela est indiqué.

Un rappel avant de commencer : les commandes slash comme /opsx:propose s'utilisent dans le chat de votre assistant IA, et les commandes openspec s'utilisent dans votre terminal. Si cela vous est nouveau, lisez d'abord Comment fonctionnent les commandes. Dans les transcriptions ci-dessous, Vous : et IA : correspondent au chat, et les lignes commençant par $ correspondent au terminal.

Vous n'êtes pas encore sûr de ce que vous construisez ? La plupart de ces recettes sont plus efficaces si vous commencez par /opsx:explore pour y réfléchir d'abord. La Recette 3 le montre en action, et le guide Explorer d'abord développe l'argument complet.

Recette 1 : Une petite fonctionnalité, le chemin rapide

Quand l'utiliser : vous savez ce que vous voulez, et il s'agit d'un travail isolé. C'est la recette la plus courante.

L'ensemble se compose de trois commandes. Proposer, construire, archiver.

Vous : /opsx:propose add-logout-button

IA :   Created openspec/changes/add-logout-button/
      ✓ proposal.md — pourquoi et quoi
      ✓ specs/      — la nouvelle exigence et ses scénarios
      ✓ design.md   — approche technique
      ✓ tasks.md    — liste de contrôle d'implémentation
      Prêt pour l'implémentation. Exécutez /opsx:apply.

Maintenant, lisez le plan. Ouvrez la proposition et le spécification delta (delta spec). C'est le moment où OpenSpec est conçu pour être utile : attraper une hypothèse erronée alors qu'elle ne tient toujours qu'à un paragraphe, et non à 400 lignes de code. Modifiez directement tout artefact si quelque chose ne va pas, puis continuez.

Vous : /opsx:apply

IA :   Working through tasks...
      ✓ 1.1 Add logout button to header
      ✓ 1.2 Clear session on click
      ✓ 1.3 Add confirmation dialog
      All tasks complete!

Vous : /opsx:archive

IA :   Archiving add-logout-button...
      ✓ Merged specs into openspec/specs/auth/spec.md
      ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
      Done. Ready for the next change.

C'est tout. Le comportement de déconnexion fait désormais partie de vos spécifications, et le changement est archivé avec tout son contexte.

Recette 2 : Correction d'un bug

Quand l'utiliser : quelque chose ne fonctionne pas et vous souhaitez que la correction soit enregistrée comme un changement délibéré de comportement, et non comme un commit mystérieux.

Les corrections de bugs fonctionnent exactement comme les fonctionnalités. La différence réside dans la manière dont vous présentez la proposition : décrivez le comportement correct, et non simplement « corriger le bug ».

Vous : /opsx:propose fix-login-redirect-loop

IA :   Created openspec/changes/fix-login-redirect-loop/
      The proposal captures the current broken behavior and the
      intended behavior. The delta spec MODIFIES the redirect
      requirement so it's now precise and testable.
      Ready for implementation.

Parce que la correction aboutit à une exigence MODIFIED avec un scénario frais, la prochaine personne (ou la prochaine session IA) verra non seulement que vous l'avez corrigé, mais aussi ce que signifie « correct ». Ensuite, exécutez /opsx:apply et /opsx:archive comme d'habitude.

Astuce : pour une correction, un bon scénario est le test de régression rédigé en prose. « ÉTANT DONNÉ un utilisateur déconnecté, QUAND il soumet des identifiants valides, ALORS il arrive sur le tableau de bord et n'est pas redirigé à nouveau. » Rédigez cela, et l'implémentation aura un objectif clair.

Recette 3 : Explorer avant de s'engager

Quand l'utiliser : vous avez un problème mais pas encore de plan. Vous n'êtes pas sûr de quoi construire, ou quelle approche est la bonne.

Commencez par /opsx:explore. C'est un partenaire de réflexion sans structure et sans création d'artefacts. Il lit votre base de code et vous aide à décider.

Vous : /opsx:explore

IA :   What would you like to explore?

Vous : Page loads feel slow but I don't know where the time goes.

IA :   Let me look... I found three likely culprits:
      1. Large unoptimized images on the product list
      2. Synchronous data fetching that blocks render
      3. Re-renders triggered by context changes
      Which should we tackle first?

Vous : The data fetching one.

Vous : /opsx:propose optimize-product-list-fetching

IA :   Created the change, with a proposal informed by what we just
      found. Ready for implementation.

L'exploration clarifie votre réflexion avant d'allouer un changement à celle-ci. Lorsque l'idée prend forme, proposez, et l'IA conserve le contexte pour la suite.

Recette 4 : Gérer deux changements simultanément

Quand l'utiliser : vous êtes en plein milieu d'une fonctionnalité et une correction urgente passe devant.

Les changements sont des dossiers indépendants, donc le travail parallèle ne crée pas de conflits. Commencez la correction, livrez-la, puis revenez à la fonctionnalité exactement là où vous vous étiez arrêté.

Vous : I'm partway through add-dark-mode, but I need to fix a login bug now.

Vous : /opsx:propose fix-login-redirect

IA :   Created openspec/changes/fix-login-redirect/. Ready for implementation.

Vous : /opsx:apply

IA :   Implemented the fix. All tasks complete.

Vous : /opsx:archive

IA :   ✓ Archived fix-login-redirect.

Vous : Back to dark mode.

Vous : /opsx:apply add-dark-mode

IA :   Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Nommer le changement dans /opsx:apply add-dark-mode est la manière d'indiquer à l'IA un changement spécifique lorsqu'il y en a plusieurs d'actifs. Parce que les tâches suivent leur achèvement dans tasks.md, l'IA sait exactement où vous vous êtes arrêté.

Lorsque plusieurs changements sont terminés en même temps, /opsx:bulk-archive les archive ensemble et résout les conflits de spécifications en vérifiant ce qui a réellement été implémenté. Voir Workflows.

Recette 5 : Un refactor sans changement de comportement

Quand l'utiliser : vous restructurez du code, et le comportement visible de l'extérieur doit rester identique.

C'est le cas intéressant, car un refactor pur n'a rien à ajouter à vos spécifications. Le contrat de comportement ne change pas ; seule l'implémentation change. Ainsi, le travail réside dans la conception et les tâches, et le delta de spécification est vide ou absent.

Vous : /opsx:propose refactor-payment-module

IA :   Created the change. The proposal states the goal (split the
      payment module, no behavior change) and the design captures
      the new structure. No spec changes, since behavior is identical.
      Ready for implementation.

Déclarez explicitement le delta vide en définissant skip_specs: true dans le .openspec.yaml du changement :

schema: spec-driven
skip_specs: true

Sans ce marqueur, openspec validate rejette un changement avec zéro deltas (ainsi, une phase de spécifications oubliée sera toujours détectée) ; avec lui, la validation réussit et openspec status indique que l'étape des spécifications a été explicitement ignorée plutôt qu'en attente. Si le refactor s'avère modifier le comportement après tout, supprimez skip_specs de .openspec.yaml et rédigez les spécifications delta — la validation traite le marqueur combiné aux fichiers de spécifications comme un conflit, de sorte que le marqueur périmé ne peut pas traîner silencieusement.

L'archivage d'un changement marqué ne nécessite aucun indicateur supplémentaire (il n'y a pas de deltas à fusionner). Indépendamment, l'indicateur --skip-specs indique à la commande terminal de sauter explicitement l'étape des spécifications :

$ openspec archive refactor-payment-module --skip-specs

Le même indicateur est pratique pour les outils, l'intégration continue (CI) et les changements uniquement documentaires. Le principe : les spécifications décrivent le comportement, donc si le comportement n'a pas changé, la spécification ne devrait pas non plus. Voir Concepts.

Recette 6 : Contrôle étape par étape (commandes étendues)

Quand l'utiliser : un changement complexe ou risqué où vous souhaitez examiner chaque artefact avant de passer à la suite.

Le /opsx:propose principal rédige tout d'un coup. Lorsque vous préférez procéder étape par étape, activez les commandes étendues :

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Maintenant, vous pouvez échafauder et construire de manière incrémentale :

Vous : /opsx:new add-2fa

IA :   Created openspec/changes/add-2fa/. Ready to create: proposal.

Vous : /opsx:continue

IA :   Created proposal.md. Now available: specs, design.

Vous : /opsx:continue

IA :   Created specs/auth/spec.md. Now available: design.

Examinez chaque artefact à mesure qu'il est créé, modifiez librement, et continuez lorsque vous êtes satisfait. Lorsque vous souhaitez que le reste soit rédigé d'un coup, /opsx:ff avance rapidement à travers les artefacts de planification restants. Avant l'archivage, /opsx:verify vérifie que l'implémentation correspond réellement aux spécifications. Voir Workflows.

Recette 7 : Apprendre la boucle complète en pratiquant

Quand l'utiliser : vous avez installé OpenSpec et souhaitez ressentir le flux de travail sur votre propre code, et non sur un exemple fictif.

Activez les commandes étendues (voir Recette 6), puis :

Vous : /opsx:onboard

IA :   Welcome to OpenSpec! I'll walk you through a complete change
      using your actual codebase. Let me scan for a small, safe
      improvement we can make together...

/opsx:onboard trouve une amélioration réelle (petite), crée un changement pour celle-ci, l'implémente et l'archive, en narrant chaque étape. Cela prend 15 à 30 minutes et vous laisse avec un changement réel que vous pouvez conserver ou rejeter. C'est la méthode la plus douce pour apprendre. Voir Commands.

Vérifier votre travail depuis le terminal

À tout moment, depuis votre terminal, vous pouvez inspecter l'état des choses :

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Ce sont des outils de lecture et d'inspection. La proposition et la construction se font toujours via les commandes slash dans le chat. Détails complets dans la référence CLI.

Où aller ensuite

• Explorer d'abord : la méthode recommandée pour démarrer lorsque vous hésitez
• Workflows : les modèles ci-dessus, avec des conseils décisionnels sur quand utiliser chacun
• Commands : chaque commande slash en détail
• Getting Started : le tutoriel canonique pour le premier changement
• Concepts : pourquoi les pièces s'emboîtent comme elles le font