OpenSpec

Prise en main ​

Ce guide explique le fonctionnement d'OpenSpec après l'installation et l'initialisation. Pour les instructions d'installation, consultez le README principal ou le guide d'installation. Nouveau dans l'ensemble de la documentation ? La page d'accueil de la documentation présente tout l'ensemble.

Où taper ces commandes ? Deux endroits, et les confondre est l'erreur la plus courante au début.

  • Les commandes openspec ... (comme openspec init) s'exécutent dans votre terminal.
  • Les commandes /opsx:... (comme /opsx:propose) s'exécutent dans la discussion de votre assistant IA, la même zone où vous lui demanderiez d'écrire du code.

Il n'y a pas de « mode interactif » séparé à démarrer. Vous tapez simplement la commande slash dans la discussion et votre assistant prend le relais. Explication complète : Comment fonctionnent les commandes.

Vos premières cinq minutes ​

La boucle complète, chaque étape étant étiquetée selon l'endroit où elle se déroule :

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (facultatif : réfléchir d'abord)
AI CHAT      /opsx:propose add-dark-mode      (l'IA rédige le plan ; vous le révisez)
AI CHAT      /opsx:apply                      (l'IA le construit)
AI CHAT      /opsx:archive                    (spécifications mises à jour, changement archivé)

Deux étapes dans le terminal pour la configuration, puis vous travaillez dans la discussion. Le reste de ce guide détaille ce que fait chaque étape et ce que vous verrez.

Vous ne voulez pas faire la partie terminal vous-même ? Collez le prompt de configuration dans votre assistant et il gère les deux lignes, puis rapporte ce qu'il a créé.

Vous ne savez pas encore quoi construire ? Commencez par /opsx:explore. C'est un partenaire de réflexion sans risque qui lit votre base de code, pèse les options et affine une idée vague en un plan concret, le tout avant qu'aucun artefact ou code n'existe. Quand la vision est claire, il transmet à /opsx:propose. C'est la meilleure habitude pour travailler avec une IA qui autrement construirait confiantement la mauvaise chose. Consultez le guide Explore.

Comment ça fonctionne ​

OpenSpec vous aide vous et votre assistant de codage IA à vous mettre d'accord sur ce qu'il faut construire avant d'écrire le moindre code.

Chemin rapide par défaut (profil core) :

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (facultatif)

Commencez par /opsx:explore quand vous cherchez à déterminer quoi faire, ou passez directement à /opsx:propose si vous le savez déjà. Explore est inclus dans le profil par défaut, il est donc toujours disponible quand vous en avez besoin.

Chemin étendu (sélection de flux de travail personnalisé) :

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Le profil global par défaut est core, qui inclut propose, explore, apply, update, sync et archive. Vous pouvez activer les commandes de flux de travail étendu avec openspec config profile puis openspec update.

Ce que crée OpenSpec ​

Après l'exécution de openspec init, votre projet a cette structure :

openspec/
├── specs/              # Source de vérité (comportement de votre système)
│   └── <domain>/
│       └── spec.md
├── changes/            # Modifications proposées (un dossier par changement)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Spécifications delta (ce qui change)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Configuration du projet (facultatif)

Deux répertoires clés :

  • specs/ - La source de vérité. Ces spécifications décrivent comment votre système se comporte actuellement. Organisées par domaine (par ex. specs/auth/, specs/payments/).

  • changes/ - Modifications proposées. Chaque changement a son propre dossier avec tous les artefacts associés. Quand un changement est terminé, ses spécifications fusionnent dans le répertoire principal specs/.

Comprendre les artefacts ​

Chaque dossier de changement contient des artefacts qui guident le travail :

ArtefactRôle
proposal.mdLe « pourquoi » et le « quoi » - capture l'intention, la portée et l'approche
specs/Spécifications delta montrant les exigences AJOUTÉES/MODIFIÉES/SUPPRIMÉES
design.mdLe « comment » - approche technique et décisions d'architecture
tasks.mdListe de contrôle d'implémentation avec cases à cocher

Les artefacts se construisent les uns sur les autres :

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            mettre à jour au fur et à mesure que vous apprenez

Vous pouvez toujours revenir en arrière et affiner les artefacts antérieurs au fur et à mesure que vous en apprenez plus pendant l'implémentation.

Comment fonctionnent les spécifications delta ​

Les spécifications delta sont le concept clé d'OpenSpec. Elles montrent ce qui change par rapport à vos spécifications actuelles.

Le format ​

Les spécifications delta utilisent des sections pour indiquer le type de changement :

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

Ce qui se passe lors de l'archivage ​

Quand vous archivez un changement :

  1. Les exigences AJOUTÉES sont ajoutées à la spécification principale
  2. Les exigences MODIFIÉES remplacent la version existante
  3. Les exigences SUPPRIMÉES sont supprimées de la spécification principale

Le dossier de changement est déplacé vers openspec/changes/archive/ pour l'historique d'audit.

Exemple : votre premier changement ​

Parcourons l'ajout du mode sombre à une application.

1. Démarrer le changement (par défaut) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Si vous avez activé le profil de flux de travail étendu, vous pouvez aussi le faire en deux étapes : /opsx:new puis /opsx:ff (ou /opsx:continue de manière incrémentale).

2. Ce qui est créé ​

proposal.md - Capture l'intention :

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - Delta montrant les nouvelles exigences :

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - Liste de contrôle d'implémentation :

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. Implémenter ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

Pendant l'implémentation, si vous découvrez que la conception nécessite un ajustement, mettez simplement à jour l'artefact et continuez.

4. Archiver ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Vos spécifications delta font désormais partie des spécifications principales, documentant le fonctionnement de votre système.

Vérification et revue ​

Utilisez l'interface en ligne de commande pour suivre vos changements :

bash
# Lister les changements actifs
openspec list

# Afficher les détails d'un changement
openspec show add-dark-mode

# Valider le formatage des spécifications
openspec validate add-dark-mode

# Tableau de bord interactif
openspec view

Étapes suivantes ​