Configurez votre projet

Ajoutez OpenSpec à un projet : exécutez init, consultez ce qui a été écrit, puis ajustez-le.

Choisissez l'emplacement d'OpenSpec

• Dans votre dépôt (par défaut) : les specs et les changements se trouvent à côté du code qu'ils décrivent et sont versionnés avec lui. Le reste de cette page suit cette voie.
• Dans un store : un dépôt de planification distinct partagé par les dépôts qui l'utilisent, pour les configurations multi-dépôts ou pour garder la planification hors du dépôt. Stores (bêta) couvre quand cela vaut le coup et comment en configurer un.

Initialisez votre projet

Avec la CLI installée (Installation), exécutez init à la racine de votre projet. Dans votre terminal :

cd <your-project>
openspec init

Init vous demande quels outils IA vous utilisez, écrit les fichiers de workflow pour ceux que vous choisissez, et rapporte ce que vous avez obtenu :

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Redémarrez votre IDE pour que les nouvelles commandes prennent effet.

Réexécuter init est sans risque :

• Les outils que vous avez déjà configurés affichent Refreshed au lieu de Created.
• Réexécuter init avec un nouvel outil sélectionné ajoute cet outil.
• L'option --tools ignore le sélecteur (référence CLI).

Migrer un project.md existant

Init ne copie pas l'ancien openspec/project.md dans config.yaml. Il conserve le fichier et affiche une demande de migration assistée par IA.

Dans votre chat IA :

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Vérifiez config.yaml, puis supprimez project.md lorsque vous êtes prêt.

Ce qu'init installe

L'exécution d'init crée deux éléments dans votre projet :

• Un dossier openspec/ à la racine du dépôt
• Des fichiers de workflow (skills et commandes) ajoutés au dossier de votre outil IA (.agents/, .claude/, etc.)

Commitez tout cela comme le reste de votre code source. Init ne modifie rien d'autre dans votre dépôt (s'il trouve des restes d'une ancienne version d'OpenSpec, il demande avant de les nettoyer).

Le dossier openspec/

Chaque artefact OpenSpec se trouve ici, à la racine de votre projet. Voici à quoi cela ressemble :

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

Configuration du projet couvre config.yaml.

Les fichiers de workflow (skills et commandes)

Ce sont les workflows OpenSpec, les actions que vous utiliserez en travaillant. Les voici sous forme de skills installés, dans le dossier partagé .agents/ que la plupart des outils utilisent :

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

Ceci est l'ensemble par défaut plus deux workflows optionnels. Profils listent les douze.

Par défaut, chaque workflow s'installe sous deux formes :

• Skill (openspec-apply-change) : des instructions que votre agent récupère de lui-même lorsque vous demandez le travail.
• Commande (/opsx:apply dans Claude Code) : un point d'entrée tapé pour le même workflow, sous un nom plus court.

Les deux sont fonctionnellement identiques. Le skill d'un workflow et sa commande portent les mêmes instructions.

Pourquoi deux : les commandes sont arrivées en premier, et chaque outil les écrit à sa manière. Les skills sont le standard plus récent partagé entre les outils, mais tous les outils ne peuvent pas invoquer un skill directement, donc les commandes restent le point d'entrée de ces outils.

Certains outils s'installent uniquement sous forme de skill. Là où l'outil exécute les skills directement, init ignore les commandes et l'indique (Commands skipped for: codex (uses skills)).

Nous préférons les skills et prévoyons de retirer les commandes à terme.

Modifier ce qui est installé

Le sélecteur interactif modifie la forme de distribution et l'ensemble de workflows (Profils). Dans votre terminal :

openspec config profile

Voici comment passer aux skills uniquement :

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Répondre oui l'applique au projet actuel immédiatement. Les autres projets le prendront en compte lors de leur prochaine openspec update. Le paramètre est global, par machine.

Claude Code n'affiche pas les workflows

Claude Code charge les workflows OpenSpec depuis l'un ou l'autre de ces chemins de projet, selon votre paramètre de distribution :

• Skills : .claude/skills/openspec-*/SKILL.md
• Commandes : .claude/commands/opsx/<id>.md

Si les fichiers sont manquants, rafraîchissez le projet. Dans votre terminal :

openspec update

Si les fichiers de commandes existent mais que /opsx: n'affiche aucune commande OpenSpec, mettez à jour Claude Code et redémarrez-le. Si les commandes ne se chargent toujours pas, activez aussi les skills. Dans votre terminal :

openspec config set delivery both
openspec update

Redémarrez Claude Code, puis exécutez /openspec-propose dans son chat. S'il ne manque que certains workflows, modifiez votre profil.

La configuration est terminée. Le Quickstart vous accompagne pour votre premier changement à partir d'ici.