Concepts
Ce guide explique les idées fondamentales d'OpenSpec et leur articulation. Pour une utilisation pratique, consultez Démarrage rapide et Workflows.
Philosophie
OpenSpec repose sur quatre principes :
fluide et non rigide — pas de portes de phase, travaillez sur ce qui a du sens
itératif et non en cascade — apprenez en construisant, affinez au fur et à mesure
simple et non complexe — configuration légère, cérémonies minimales
priorité aux projets existants (brownfield-first) — fonctionne avec les bases de code existantes, pas seulement avec des projets neufs (greenfield)Pourquoi ces principes sont importants
Fluide et non rigide. Les systèmes de spécification traditionnels vous enferment dans des phases : d'abord vous planifiez, ensuite vous implémentez, puis c'est terminé. OpenSpec est plus flexible : vous pouvez créer des artefacts dans n'importe quel ordre, selon ce qui est pertinent pour votre travail.
Itératif et non en cascade. Les exigences évoluent. La compréhension s'affine. Ce qui semblait être une bonne approche au départ pourrait ne pas se révéler viable après avoir examiné la base de code. OpenSpec intègre cette réalité.
Simple et non complexe. Certains cadres de spécification nécessitent une configuration extensive, des formats rigides ou des processus lourds. OpenSpec reste discret. Initialisez-le en quelques secondes, commencez à travailler immédiatement, personnalisez uniquement si nécessaire.
Priorité aux projets existants (brownfield-first). La plupart des travaux logiciels ne consistent pas à construire à partir de zéro, mais à modifier des systèmes existants. L'approche basée sur les deltas d'OpenSpec permet de spécifier facilement des modifications apportées au comportement existant, et pas seulement de décrire de nouveaux systèmes.
Vue d'ensemble
OpenSpec organise votre travail en deux domaines principaux :
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Les specs sont la source de vérité — elles décrivent comment votre système se comporte actuellement.
Les changes (modifications proposées) sont des modifications proposées — elles résident dans des dossiers séparés jusqu'à ce que vous soyez prêt à les fusionner.
Cette séparation est essentielle. Vous pouvez travailler sur plusieurs modifications en parallèle sans conflits. Vous pouvez examiner une modification avant qu'elle n'affecte les specs principales. Et lorsque vous archivez une modification, ses deltas fusionnent proprement avec la source de vérité.
Specs
Les specs décrivent le comportement de votre système à l'aide de exigences structurées et de scénarios.
Structure
openspec/specs/
├── auth/
│ └── spec.md # Comportement d'authentification
├── payments/
│ └── spec.md # Traitement des paiements
├── notifications/
│ └── spec.md # Système de notification
└── ui/
└── spec.md # Comportement de l'interface utilisateur et thèmesOrganisez les specs par domaine — des regroupements logiques qui ont du sens pour votre système. Modèles courants :
- Par zone fonctionnelle :
auth/,payments/,search/ - Par composant :
api/,frontend/,workers/ - Par contexte délimité :
ordering/,fulfillment/,inventory/
Format de Spec
Une spec contient des exigences, et chaque exigence a des scénarios :
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateÉléments clés :
| Élément | Objectif |
|---|---|
## Purpose | Description de haut niveau du domaine de cette spec |
### Requirement: | Un comportement spécifique que le système doit avoir |
#### Scenario: | Un exemple concret de l'exigence en action |
| SHALL/MUST/SHOULD | Mots-clés RFC 2119 indiquant la force de l'exigence |
Pourquoi structurer les specs ainsi ?
Les exigences sont le « quoi » — elles énoncent ce que le système doit faire sans spécifier l'implémentation.
Les scénarios sont le « quand » — ils fournissent des exemples concrets qui peuvent être vérifiés. De bons scénarios :
- Sont testables (vous pourriez écrire un test automatisé pour eux)
- Couvrent à la fois le chemin heureux et les cas limites
- Utilisent un format structuré Given/When/Then ou similaire
Les mots-clés RFC 2119 (SHALL, MUST, SHOULD, MAY) communiquent l'intention :
- MUST/SHALL — exigence absolue
- SHOULD — recommandé, mais des exceptions existent
- MAY — optionnel
Ce qu'est une Spec (et ce qu'elle n'est pas)
Une spec est un contrat de comportement, pas un plan d'implémentation.
Contenu approprié pour une spec :
- Comportement observable sur lequel les utilisateurs ou les systèmes en aval s'appuient
- Entrées, sorties et conditions d'erreur
- Contraintes externes (sécurité, confidentialité, fiabilité, compatibilité)
- Scénarios qui peuvent être testés ou explicitement validés
À éviter dans les specs :
- Noms de classes/fonctions internes
- Choix de bibliothèques ou de frameworks
- Détails étape par étape de l'implémentation
- Plans d'exécution détaillés (ceux-ci appartiennent à
design.mdoutasks.md)
Test rapide :
- Si l'implémentation peut changer sans modifier le comportement visible de l'extérieur, elle ne devrait probablement pas figurer dans la spec.
Gardez-le léger : Rigueur progressive
OpenSpec vise à éviter la bureaucratie. Utilisez le niveau de rigueur le plus léger qui rend toujours la modification vérifiable.
Lite spec (par défaut) :
- Exigences courtes axées sur le comportement
- Portée claire et non-objectifs définis
- Quelques critères d'acceptation concrets
Full spec (pour les risques plus élevés) :
- Modifications inter-équipes ou inter-dépôts
- Modifications d'API/contrat, migrations, préoccupations de sécurité/confidentialité
- Modifications où l'ambiguïté risque de provoquer des retours en arrière coûteux
La plupart des modifications doivent rester en mode Lite.
Collaboration Humain + Agent
Dans de nombreuses équipes, les humains explorent et les agents rédigent les artefacts. La boucle prévue est la suivante :
- L'humain fournit l'intention, le contexte et les contraintes.
- L'agent convertit cela en exigences et scénarios axés sur le comportement.
- L'agent conserve les détails d'implémentation dans
design.mdettasks.md, et non dansspec.md. - La validation confirme la structure et la clarté avant l'implémentation.
Cela garde les specs lisibles pour les humains et cohérentes pour les agents.
Changes
Un change est une modification proposée de votre système, emballée sous forme de dossier contenant tout ce qui est nécessaire pour le comprendre et l'implémenter.
Structure d'un Change
openspec/changes/add-dark-mode/
├── proposal.md # Pourquoi et quoi
├── design.md # Comment (approche technique)
├── tasks.md # Liste de contrôle d'implémentation
├── .openspec.yaml # Métadonnées du change (optionnel) : schema, created, skip_specs, retire_capabilities
└── specs/ # Specs delta
└── ui/
└── spec.md # Ce qui change dans ui/spec.mdChaque change est autonome. Il comprend :
- Artefacts — documents capturant l'intention, la conception et les tâches
- Specs delta — spécifications de ce qui est ajouté, modifié ou supprimé
- Métadonnées — configuration optionnelle pour ce change spécifique
Pourquoi les Changes sont des Dossiers
L'emballage d'un change sous forme de dossier présente plusieurs avantages :
Tout ensemble. Proposition, conception, tâches et specs vivent au même endroit. Plus besoin de chercher dans différents emplacements.
Travail parallèle. Plusieurs changes peuvent exister simultanément sans conflit. Travaillez sur
add-dark-modependant quefix-auth-bugest également en cours.Historique propre. Lorsqu'ils sont archivés, les changes sont déplacés vers
changes/archive/avec leur contexte complet préservé. Vous pouvez revenir en arrière et comprendre non seulement ce qui a changé, mais aussi pourquoi.Facile à examiner. Un dossier de change est facile à examiner — ouvrez-le, lisez la proposition, vérifiez la conception, voyez les deltas des specs.
Artefacts
Les artefacts sont les documents au sein d'un change qui guident le travail.
Le Flux des Artefacts
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeLes artefacts s'appuient les uns sur les autres. Chaque artefact fournit un contexte pour le suivant.
Types d'Artefacts
Proposition (proposal.md)
La proposition capture l'intention, la portée et l'approche à un niveau élevé.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Quand mettre à jour la proposition :
- Changements de portée (rétrécissement ou expansion)
- Clarification de l'intention (meilleure compréhension du problème)
- L'approche change fondamentalement
Specs (specs delta dans specs/)
Les specs delta décrivent ce qui change par rapport aux specs actuelles. Voir Delta Specs ci-dessous.
Conception (design.md)
La conception capture l'approche technique et les décisions architecturales.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Quand mettre à jour la conception :
- L'implémentation révèle que l'approche ne fonctionnera pas
- Meilleure solution découverte
- Les dépendances ou contraintes changent
Tâches (tasks.md)
Les tâches constituent la liste de contrôle d'implémentation — des étapes concrètes avec des cases à cocher.
# 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
- [ ] 1.4 Add system preference detection
## 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.3 Test contrast ratios for accessibilityBonnes pratiques pour les tâches :
- Regroupez les tâches connexes sous des titres
- Utilisez une numérotation hiérarchique (1.1, 1.2, etc.)
- Gardez les tâches suffisamment petites pour être complétées en une seule session
- Cochez les tâches au fur et à mesure de leur achèvement
Delta Specs
Les delta specs sont le concept clé qui permet à OpenSpec de fonctionner pour le développement brownfield (sur code existant). Elles décrivent ce qui change plutôt que de réécrire entièrement la spec.
Le Format
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Sections Delta
| Section | Signification | Que se passe-t-il lors de l'archive ? |
|---|---|---|
## ADDED Requirements | Nouveau comportement | Ajouté à la spec principale |
## MODIFIED Requirements | Comportement modifié | Remplace l'exigence existante |
## REMOVED Requirements | Comportement déprécié | Supprimé de la spec principale ; supprimer la dernière exigence retire la capacité et supprime son fichier spec, lorsque le change déclare retire_capabilities: true |
## Purpose | À quoi sert une nouvelle capacité | Initialise le Purpose de la spec principale en cours de création ; ignoré si la spec existe déjà |
Pourquoi des Deltas plutôt que des Specs Complètes ?
Clarté. Un delta montre exactement ce qui change. En lisant une spec complète, vous devriez la comparer mentalement à la version actuelle.
Évitement des conflits. Deux changes peuvent toucher le même fichier spec sans entrer en conflit, tant qu'ils modifient différentes exigences.
Efficacité de l'examen. Les examinateurs voient le changement, pas le contexte inchangé. Concentrez-vous sur l'essentiel.
Adaptation au brownfield. La plupart des travaux modifient le comportement existant. Les deltas rendent les modifications prioritaires, et non une pensée après coup.
Schémas
Les schémas définissent les types d'artefacts et leurs dépendances pour un workflow.
Fonctionnement des schémas
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Aucune dépendance, peut être créé en premier
- id: specs
generates: specs/**/*.md
requires: [proposal] # Nécessite une proposition avant d'être créé
- id: design
generates: design.md
requires: [proposal] # Peut être créé en parallèle avec les spécifications
- id: tasks
generates: tasks.md
requires: [specs, design] # Nécessite les spécifications et la conception en premierLes artefacts forment un graphe de dépendances :
proposal
(nœud racine)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(nécessite : (nécessite :
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(nécessite :
specs, design)Les dépendances sont des facilitateurs, pas des portes. Elles indiquent ce qu'il est possible de créer, pas ce que vous devez créer ensuite. Vous pouvez ignorer la conception si vous n'en avez pas besoin. Vous pouvez créer les spécifications avant ou après la conception — les deux dépendent uniquement de la proposition.
Schémas intégrés
spec-driven (par défaut)
Le flux de travail standard pour le développement piloté par les spécifications :
proposal → specs → design → tasks → implementIdéal pour : la plupart des travaux sur les fonctionnalités où vous souhaitez vous accorder sur les spécifications avant l'implémentation.
Schémas personnalisés
Créez des schémas personnalisés pour le workflow de votre équipe :
# Créer à partir de zéro
openspec schema init research-first
# Ou faire un fork d'un schéma existant
openspec schema fork spec-driven research-firstExemple de schéma personnalisé :
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Faire la recherche en premier
- id: proposal
generates: proposal.md
requires: [research] # Proposition éclairée par la recherche
- id: tasks
generates: tasks.md
requires: [proposal] # Ignorer les spécifications/la conception, aller directement aux tâchesVoir Personnalisation pour plus de détails sur la création et l'utilisation de schémas personnalisés.
Archivage
L'archivage termine une modification en fusionnant ses spécifications delta dans les spécifications principales et en préservant la modification pour l'historique.
Ce qui se passe lors de l'archivage
Avant l'archivage :
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Après l'archivage :
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Contient désormais les exigences 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Conservé pour l'historique
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdLe processus d'archivage
Fusion des deltas. Chaque section de spécification delta (ADDED/MODIFIED/REMOVED) est appliquée à la spécification principale correspondante.
Déplacement vers l'archive. Le dossier de modification est déplacé vers
changes/archive/avec un préfixe de date pour un ordre chronologique.Préservation du contexte. Tous les artefacts restent intacts dans l'archive. Vous pouvez toujours revenir en arrière pour comprendre pourquoi une modification a été apportée.
Pourquoi l'archivage est important
État propre. Les modifications actives (changes/) ne montrent que le travail en cours. Le travail terminé est mis de côté.
Piste d'audit. L'archive préserve le contexte complet de chaque modification — non seulement ce qui a changé, mais aussi la proposition expliquant pourquoi, la conception expliquant comment, et les tâches montrant le travail effectué.
Évolution des spécifications. Les spécifications évoluent de manière organique au fur et à mesure que les modifications sont archivées. Chaque archivage fusionne ses deltas, construisant une spécification complète au fil du temps.
Comment tout s'emboîte
┌──────────────────────────────────────────────────────────────────────────────┐
│ FLUX OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. DÉBUT DE │ /opsx:propose (core) ou /opsx:new (expanded) │
│ │ LA MODIFICATION│ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CRÉER LES │ /opsx:ff ou /opsx:continue (workflow étendu) │
│ │ ARTEFACTS │ Crée la proposition → spécifications → conception │
│ │ │ → tâches (selon les dépendances du schéma) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLÉMENTER│ /opsx:apply │
│ │ LES TÂCHES │ Travailler sur les tâches, les cocher │
│ │ │◄──── Mettre à jour les artefacts au fur et à mesure │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VÉRIFIER LE│ /opsx:verify (optionnel) │
│ │ TRAVAIL │ Vérifier que l'implémentation correspond aux specs │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVER LA│────►│ Les spécifications delta fusionnent dans les │ │
│ │ MODIFICATION│ │ spécifications principales │ │
│ └────────────────┘ │ Le dossier de modification est déplacé dans │ │
│ │ archive/ │ │
│ │ Les spécifications sont désormais la source │ │
│ │ de vérité mise à jour │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Le cercle vertueux :
- Les spécifications décrivent le comportement actuel
- Les modifications proposent des changements (sous forme de deltas)
- L'implémentation rend les modifications réelles
- L'archivage fusionne les deltas dans les spécifications
- Les spécifications décrivent désormais le nouveau comportement
- La modification suivante s'appuie sur les spécifications mises à jour
Glossaire
| Terme | Définition |
|---|---|
| Artifact | Un document au sein d'une modification (proposition, conception, tâches ou spécifications delta) |
| Archive | Le processus de terminer une modification et de fusionner ses deltas dans les spécifications principales |
| Change | Une proposition de modification du système, regroupée dans un dossier avec des artefacts |
| Delta spec | Une spécification qui décrit les modifications (ADDED/MODIFIED/REMOVED) par rapport aux spécifications actuelles |
| Domain | Un regroupement logique pour les spécifications (par exemple, auth/, payments/) |
| Requirement | Un comportement spécifique que le système doit avoir |
| Scenario | Un exemple concret d'une exigence, généralement au format Given/When/Then |
| Schema | Une définition des types d'artefacts et de leurs dépendances |
| Spec | Une spécification décrivant le comportement du système, contenant des exigences et des scénarios |
| Source of truth | Le répertoire openspec/specs/, contenant le comportement actuellement convenu |
Prochaines étapes
- Premiers pas - Premières étapes pratiques
- Workflows - Modèles courants et quand les utiliser
- Commandes - Référence complète des commandes
- Personnalisation - Créer des schémas personnalisés et configurer votre projet