OpenSpec – Présentation des fonctionnalités de base

Dans le développement logiciel moderne, la collaboration avec des assistants de code basés sur l’Intelligence Artificielle (comme Claude Code, Gemini CLI, Copilot, etc.) est devenue courante. Cependant, le plus grand défi a évolué: le problème n’est pas tant l’écriture du code elle-même, mais de s’assurer que vous et l’IA soyez d’accord sur ce qui doit être construit avant que la première ligne de code ne soit générée.

L’OpenSpec a été créé exactement pour combler cette lacune. Il agit comme une spécification open source pour gérer le comportement du système et les propositions de changement de manière structurée.

1. Comment le OpenSpec fonctionne

Le principe fondamental d’OpenSpec est d’établir une « source de vérité » (source de vérité) partagée entre le développeur humain et l’agent IA.

Flux de travail (Workflows)

OpenSpec opère à travers des profils de commandes. Le profil standard et recommandé est le Core Profile, qui utilise des commandes abrégées débutant par des barres (/).

Chemin rapide standard (Core Profile):

/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive

Chemin étendu (Personnalisé):

Pour des flux nécessitant davantage de contrôle, de sélection de workflows personnalisés ou d’itérations incrémentales, OpenSpec propose une approche étendue :

/opsx:new ──► /opsx:ff ou /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Note : Le profil global par défaut est le core (qui inclut les commandes propose, explore, apply, sync et archive). Il est possible d’activer le profil étendu en utilisant la commande de configuration openspec config profile suivie de openspec update.

2. La Structure des Répertoires d’OpenSpec

En lançant la commande d’initialisation openspec init dans votre projet, la structure de fichiers suivante est créée à la racine du dépôt :

openspec/
├── specs/                  # Source de vérité (comportement actuel du système)
│   └── <domain>/
│       └── spec.md
├── changes/                # Mises à jour proposées (un dossier par modification)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/          # Spécifications Delta (ce qui change)
│           └── <domain>/
│               └── spec.md
└── config.yaml             # Configuration optionnelle du projet

Les Deux Répertoires Clés :

1. specs/ (Source de Vérité) : Ce répertoire décrit le comportement actuel de votre système. Il est rigidement organisé par domaines ou contextes délimités (ex: specs/auth/, specs/payments/).

2. changes/ (Modifications Proposées) : Chaque nouvelle fonctionnalité, refactorisation ou correctif obtient un dossier isolé contenant tous les artefacts relatifs à ce changement. Lorsque le cycle de développement se termine, ces spécifications locales sont fusionnées dans la source de vérité principale.

3. Compréhension des Artefacts

À l’intérieur de chaque dossier de modification dans changes/, il existe des artefacts spécifiques qui guident le cycle de développement :

Les artefacts sont construits de façon itérative et incrémentale, alimentant l’étape suivante du flux :

proposal ──► specs ──► design ──► tasks ──► implement
    ▲          ▲         ▲         ▲            │
    └──────────┴─────────┴─────────┴────────────┘
               (Actualiser selon les apprentissages)

Pendant l’implémentation, si vous ou l’IA découvrez des contraintes techniques inattendues, le flux permet de revenir en arrière et de raffiner les artefacts antérieurs, en maintenant la documentation vivante et précise.

4. Le Concept des Spécifications Delta (Delta Specs)

Les Spécifications Delta représentent le cœur même de la mécanique d’OpenSpec. Plutôt que de réécrire une spécification entière du système à chaque modification, on décrit uniquement le différentiel (delta) en utilisant trois sections principales en Markdown : ## ADDED Requirements, ## MODIFIED Requirements et ## REMOVED Requirements.

Exemple de Formattage d’une Delta Spec (spec.md):

# Delta pour l’Auth

## EXIGENCES AJOUTÉES
### Exigence : Authentification à deux facteurs
L’utilisateur DOIT être invité à fournir une authentification à deux facteurs lors de la connexion.

#### Scénario : OTP requis
- GIVEN un utilisateur avec 2FA activé
- WHEN l’utilisateur soumet des identifiants valides
- THEN un défi OTP doit être présenté

## EXIGENCES MODIFIÉES
### Exigence : Délai de session
Le système DOIT expirer les sessions après 30 minutes d’inactivité. (Auparavant: 60 minutes)

#### Scénario : Timeout inactif
- GIVEN une session authentifiée
- WHEN il ne se passe plus 30 minutes d’activité
- THEN la session est invalide

## EXIGENCES SUPPRIMÉES
### Exigence : Remember Me (abandonné au profit du 2FA)

Que se passe-t-il lors de l’archivage (/opsx:archive) ?

Lorsque la commande d’archivage est déclenchée avec succès :

• Les exigences marquées comme ADDED sont attachées au fichier de spécification principal de ce domaine.

• Les exigences marquées comme MODIFIED remplacent les versions anciennes correspondantes dans la source de vérité.

• Les exigences marquées comme REMOVED sont exclues de la spécification principale.

• Le répertoire temporaire de la modification est déplacé vers openspec/changes/archive/ pour des fins d’historique et d’audit.

5. Exemple pratique : Implémentation de la fonctionnalité « Mode sombre »

Pour comprendre le cycle de bout en bout, suivez les étapes pour ajouter le mode sombre à une application :

Étape 1 : Lancer le changement

Vous saisissez la commande pour proposer la nouvelle fonctionnalité :

/opsx:propose add-dark-mode

L’IA analyse le dépôt et crée automatiquement la structure dansopenspec/changes/add-dark-mode/ :

• ✓ proposal.md — Intention et périmètre définis.

• ✓ specs/ — Exigences et scénarios Gherkin/BDD mappés.

• ✓ design.md — Approche technique (par exemple : CSS Custom Properties + React Context).

• ✓ tasks.md — Liste des tâches générée.

Étape 2 : Valider les artefacts générés

Le développeur passe en revue les fichiers créés par l’IA. Le fichier tasks.md, par exemple, contiendra des étapes claires :

# Tasks
## 1. Infrastructure du Thème
- [ ] 1.1 Créer ThemeContext avec l’état clair/sombre
- [ ] 1.2 Ajouter des propriétés CSS personnalisées pour les couleurs
- [ ] 1.3 Implémenter la persistance dans le localStorage
## 2. Composants d'Interface
- [ ] 2.1 Créer le composant ThemeToggle

Étape 3 : Implémenter le code

Une fois la planification approuvée, vous exécutez :

/opsx:apply

L’IA commence à traiter la liste des tâches successivement, en écrivant le code correspondant et en marquant les tâches terminées dans le fichier tasks.md.

Étape 4 : Archiver le changement

Après vérification que tout fonctionne et que les tests sont passés, vous fermez le cycle :

/opsx:archive

OpenSpec consolide le delta d’UI dans openspec/specs/ui/spec.md, nettoie le répertoire des modifications actives et le déplace dans l’historique d’audit. La documentation du système est à jour et synchronisée avec le code produit.