Quickstart

Votre première modification, de l'idée à l'archivage, dans un projet nouveau ou existant.

Avant de commencer, vous avez besoin de la CLI sur votre machine (Installation) et d'OpenSpec initialisé dans votre projet (Configurer votre projet).

Commencer à partir d'un projet vide

Vous pouvez commencer sans stack choisie ni architecture complète. Initialisez OpenSpec dans votre dossier de projet, puis demandez à votre agent d'explorer les options avec vous. Dans votre chat IA :

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

Décidez de ce dont la première modification a besoin et laissez les choix d'architecture ultérieurs ouverts. Demandez à votre agent de proposer ce changement unique, puis suivez les étapes ci-dessous. Vous pourrez revenir sur l'architecture à mesure que le projet grandit.

La boucle en un coup d'œil

Chaque modification passe par les mêmes cinq étapes : vous réfléchissez à l'idée avec votre agent, il rédige un plan, vous corrigez le plan avant qu'aucun code n'existe, l'agent le met en œuvre, et l'archivage met à jour vos specs avec ce qui a été livré.

flowchart LR
    explore["1 · Explorer<br/>réfléchir ensemble"] --> propose["2 · Proposer<br/>l'agent rédige le plan"]
    propose --> review["3 · Réviser<br/>vous corrigez le plan"]
    review --> apply["4 · Appliquer<br/>l'agent met en œuvre, tâche par tâche"]
    apply --> archive["5 · Archiver<br/>les specs absorbent la modification"]
    archive -. "prochaine modification" .-> explore

Chaque invite ci-dessous va dans votre chat IA, au même endroit que là où vous demandez du code. Les exemples utilisent un langage simple pour fonctionner avec tous les outils. Vous pouvez également invoquer une compétence directement ; la syntaxe varie selon l'outil (outils pris en charge).

Étape 1 : Explorer

Réfléchissez à l'idée avec votre agent avant de demander un plan. Dans votre chat IA :

Help me explore how rate limiting should work in this app.

Explorer est un mode de réflexion. L'agent examine votre base de code, pose les questions qui comptent, esquisse des options et remet en question les hypothèses. Il n'écrit jamais de code. Il n'écrit rien d'autre à moins que vous ne lui demandiez de consigner ce que vous avez décidé, ou que vous ne disiez oui quand il le propose. Le résultat est une idée plus claire.

Restez ici aussi longtemps que le problème le nécessite. Quand la forme vous semble bonne, transmettez :

Propose the change we just discussed.

Cette ligne lance proposer pour vous, transportant tout ce que vous avez réglé. Ignorez la première invite de l'étape 2.

Étape 2 : Proposer

Proposer transforme l'idée en un plan révisable. Venant d'explorer, il est déjà en cours. En partant de zéro, quand le changement est clair dans votre tête, demandez directement. Dans votre chat IA :

Propose a change to add rate limiting.

L'agent demande ce dont il a besoin, puis écrit un dossier de modification :

openspec/changes/add-rate-limiting/
├── proposal.md    pourquoi, et ce qui change
├── specs/         ce que « terminé » signifie, sous forme d'exigences testables
├── design.md      décisions techniques (seulement quand la modification en nécessite une)
└── tasks.md       la liste de contrôle d'implémentation

Pas encore de code. Proposer s'arrête au plan.

Étape 3 : Réviser et corriger le plan

Corrigez le plan tant qu'il n'est que des mots et que rien n'est encore construit. Lisez dans cet ordre :

• proposal.md : est-ce le bon problème, à la bonne échelle ?
• specs/ : la lecture la plus précieuse. Accepteriez-vous ces exigences comme terminées ?
• tasks.md : les tâches couvrent-elles les specs, et rien de plus ?

Pour corriger quelque chose, les deux méthodes fonctionnent :

• Modifiez le fichier vous-même. Les artefacts sont du simple markdown, et les fichiers sont le plan.
• Dites à votre agent ce qui ne va pas (« le spec manque le cas non authentifié »). Il révise les artefacts.

Étape 4 : Appliquer

Appliquer transforme le plan en code. Démarrez une nouvelle session de chat, car l'implémentation se passe mieux sur une fenêtre de contexte propre. Dans votre chat IA :

Apply the add-rate-limiting change.

L'agent lit le dossier de modification, puis parcourt tasks.md, cochant chaque tâche au fur et à mesure.

• Interrompu, ou hors contexte ? Ouvrez une nouvelle session et demandez-lui d'appliquer à nouveau. Il reprend à la première tâche non cochée.
• Le plan s'est avéré faux ? Corrigez les artefacts (de la manière de l'étape 3), puis continuez l'application.
• Progression se trouve dans les cases à cocher de tasks.md. Il n'y a pas d'état caché.

Étape 5 : Archiver

L'archivage fait deux choses : il met à jour vos specs principales avec les exigences de la modification, et il déplace le dossier de modification dans le dossier d'archive (dans /openspec/changes/archive/*).

Quand chaque case de tasks.md est cochée, dans votre chat IA :

Archive the add-rate-limiting change.

Voici ce que fait l'archivage :

## La modification terminée
> L'implémentation est terminée. La spec delta (ce que cette modification ajoute) se trouve encore dans le dossier de modification ; specs/ ne connaît pas encore le rate limiting.
  openspec/
  ├── specs/                                   (pas encore de spec rate-limiting)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         chaque case cochée
          └── specs/
              └── rate-limiting/
                  └── spec.md                  le delta : exigences AJOUTÉES

## Les exigences arrivent dans specs/
> Chaque exigence du delta arrive dans la spec principale : celles ajoutées s'appendent, celles modifiées remplacent leur ancienne version. Une nouvelle capacité obtient un nouveau fichier de spec.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gagne « Exigence : Rate limiting »
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  le delta, source de la fusion

## Le dossier passe dans archive/
> Tout le dossier de modification, delta inclus, passe dans l'archive sous un préfixe de date. Rien n'est supprimé.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Les specs décrivent le système tel que construit
> changes/ est dégagé pour la prochaine modification. specs/ est la source de vérité pour ce que fait le système ; archive/ est l'historique de comment il y est arrivé.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          la spec telle que construite
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git est une préoccupation distincte. Committez le dossier de modification avec le code, et rien d'autre dans votre flux de travail ne change.

Conserver ou élaguer les modifications archivées

openspec/changes/archive/ conserve la proposition, le design, les tâches et le delta pour chaque modification terminée. Dans le flux d'archivage ci-dessus, le delta a déjà mis à jour openspec/specs/.

• Conservez tout le dossier de modification quand vous voulez un enregistrement autonome dans le checkout actuel.
• Supprimez le dossier specs/ d'une modification archivée quand Git est votre historique de specs. Committez d'abord l'archive, puis supprimez openspec/changes/archive/<change>/specs/. La proposition, le design et les tâches restent dans le checkout. openspec validate --archived fonctionne toujours car il vérifie l'achèvement des tâches, pas les deltas appliqués.
• Supprimez tout le dossier de modification seulement quand vous n'avez plus besoin de sa proposition, de son design ou de son historique de tâches dans le checkout. Les specs actuelles ne changent pas, mais openspec validate --archived et les recherches dans le checkout n'incluent plus cette modification.

WARNING

Conservez le commit d'archive dans l'historique de votre dépôt si vous voulez que Git conserve les fichiers supprimés. Écraser les commits d'archive et de nettoyage ensemble supprime cet instantané intermédiaire.

OpenSpec n'élaguer pas automatiquement les modifications archivées et ne fournit pas de paramètre de rétention.

Aller plus loin

• Specs delta : comment écrire les changements de comportement dans une spec delta.
• Profils : flux de travail optionnels au-delà de l'ensemble de base (vérifier avant archivage, planification incrémentale).

Guides avancés

Pas encore écrits ; guides que nous prévoyons d'ajouter :

• Prototype d'abord : spiker le code avant toute spec, puis remplir la proposition à partir de ce que le prototype vous a appris.
• Construire itérativement : une séquence de petites modifications au lieu d'une grande proposition.
• Réviser une modification implémentée : le plan doit bouger à nouveau après apply, mais la modification n'a pas encore été fusionnée ou archivée.