FAQ

Réponses rapides aux questions les plus fréquemment posées. Si votre question concerne plutôt un problème de fonctionnement (« quelque chose ne marche pas »), la page Dépannage est plus adaptée. Si vous souhaitez définir un terme, consultez le Glossaire.

Les bases

Qu'est-ce qu'OpenSpec, en une phrase ?

Une couche légère qui permet à vous et à votre assistant de codage IA de convenir par écrit de ce qu'il faut construire, avant toute écriture de code.

Pourquoi voudrais-je l'utiliser ?

Parce que les assistants IA sont confiants, même lorsqu'ils ont tort. Lorsque les exigences résident uniquement dans un fil de discussion, l'IA comble les lacunes avec des suppositions, et vous vous rendez compte du problème après la génération du code. OpenSpec anticipe cet accord, là où les erreurs sont moins coûteuses à corriger. Consultez Les concepts clés en un coup d'œil pour connaître tous les arguments.

Dois-je l'utiliser pour tout ?

Non. Utilisez-le lorsque l'accord est important, c'est-à-dire pour la plupart des travaux non triviaux. Pour une correction de typo d'un seul caractère, la procédure n'est probablement pas justifiée, et c'est tout à fait acceptable.

Puis-je l'utiliser sur un gros codebase existant, ou seulement sur de nouveaux projets ?

Les codebases existants sont le cas principal. OpenSpec est conçu prioritairement pour les environnements brownfield : vous ne documentez pas toute votre application dès le départ. Vous rédigez des spécifications uniquement pour ce que chaque modification touche, et vos spécifications se complètent au fil du temps autour du travail que vous effectuez réellement. Un guide dédié existe : Utiliser OpenSpec dans un projet existant.

Est-il lié à un seul outil IA ?

Non. OpenSpec fonctionne avec plus de 30 assistants, y compris Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex, et bien d'autres. La liste complète et les détails par outil se trouvent dans Outils pris en charge.

Exécution des commandes

Où dois-je taper /opsx:propose ?

Dans le chat de votre assistant IA, et non dans votre terminal. C'est le point de confusion le plus courant, il dispose donc de sa propre page : Comment fonctionnent les commandes. En bref : openspec ... s'exécute dans le terminal, /opsx:... s'exécute dans le chat.

Comment « démarrer le mode interactif » ?

Il n'y a pas de mode séparé à démarrer. Ouvrez simplement votre assistant IA comme d'habitude et tapez une commande slash dans son chat. La commande slash est la manière dont vous « entrez » dans OpenSpec. (La seule véritable fonctionnalité interactive du terminal est openspec view, un tableau de bord pour parcourir les spécifications et les modifications.) Explication complète dans Comment fonctionnent les commandes.

J'ai tapé une commande slash et rien ne s'est passé. Pourquoi ?

Le plus souvent, vous l'avez tapée dans le terminal au lieu de votre chat IA, vous avez utilisé une orthographe que votre outil ne reconnaît pas, ou les commandes ne sont pas encore installées. Si les fichiers manquent — ou si vous n'avez jamais configuré l'outil — exécutez openspec init ; openspec update ne met à jour que les fichiers qui existent déjà. Redémarrez ensuite votre assistant et utilisez la forme indiquée sous « Premiers pas » — voir Comment invoquer. Dépannage contient la liste de contrôle complète.

Pourquoi la syntaxe est-elle /opsx:propose dans un outil et /opsx-propose dans un autre ?

Chaque outil IA expose les commandes personnalisées légèrement différemment, et OpenSpec les écrit selon la façon dont votre outil charge le fichier qu'il a généré. Un fichier de commande nommé opsx-propose.md s'écrit /opsx-propose ; un fichier placé sous commands/opsx/ s'écrit /opsx:propose. Les outils qui utilisent des compétences (skills) au lieu de commandes utilisent le nom de la compétence — Codex nécessite $openspec-propose, Kimi Code /skill:openspec-propose. La ligne « Premiers pas » de openspec init affiche déjà la bonne forme pour les outils que vous avez sélectionnés ; le tableau complet se trouve dans Comment invoquer.

Quelle est la différence entre une compétence (skill) et une commande ?

Ce sont tous deux des fichiers qu'OpenSpec génère afin que votre assistant puisse exécuter le flux de travail. Les compétences (.../skills/openspec-*/SKILL.md) constituent la nouvelle norme transversale ; les commandes (.../commands/opsx-*) sont les anciens fichiers slash spécifiques à chaque outil. Vous n'avez pas besoin de choisir. Il vous suffit de taper la commande slash, et OpenSpec installera celle que votre outil utilise.

Le flux de travail

Par où commencer si je ne sais pas quoi construire ?

Avec /opsx:explore. C'est un partenaire de réflexion sans risque qui lit votre codebase, présente les options et transforme un problème vague en un plan concret, avant toute modification ou écriture de code. Il est inclus dans le profil par défaut, il est donc toujours disponible. Une fois le plan clair, il transmet le relais à /opsx:propose. C'est la meilleure habitude à adopter, car elle empêche un IA zélé de construire confidentiellement la mauvaise chose. Voir Explorer d'abord.

Quel est le flux de travail le plus simple possible ?

/opsx:explore (optionnel)   puis   /opsx:propose <ce que vous voulez>   puis   /opsx:apply   puis   /opsx:archive

Explorez pour réfléchir, proposez pour rédiger le plan, appliquez pour le construire, archivez pour le classer. Sautez l'étape explore lorsque vous savez exactement ce que vous voulez.

Quelle est la différence entre /opsx:propose et /opsx:new ?

/opsx:propose est la commande par défaut en une étape : elle crée la modification et rédige tous les artefacts de planification simultanément. /opsx:new fait partie de l'ensemble étendu de commandes et ne scaffolde qu'une modification vide, vous laissant créer les artefacts un par un avec /opsx:continue (ou tous ensemble avec /opsx:ff). Utilisez propose sauf si vous souhaitez un contrôle étape par étape. Voir Commandes.

Que sont les profils core et expanded ?

Un profil détermine quelles commandes slash sont installées. Core (le défaut) vous donne propose, explore, apply, update, sync, archive. L'ensemble expanded ajoute new, continue, ff, verify, bulk-archive et onboard pour un contrôle plus fin. Changez avec openspec config profile, puis appliquez avec openspec update.

Dois-je exécuter /opsx:sync ?

Habituellement non. Sync fusionne les spécifications delta d'une modification dans vos spécifications principales, et /opsx:archive proposera de le faire pour vous. Exécutez sync manuellement uniquement lorsque vous souhaitez que les spécifications soient fusionnées avant l'archivage, par exemple pour une modification longue. Voir Commandes.

Comment modifier une proposition, une spécification ou une tâche après avoir commencé ?

Modifiez simplement le fichier. Chaque artefact est du Markdown brut dans openspec/changes/<name>/, et il n'y a ni phase verrouillée ni mode d'édition spécial. Modifiez-le à la main, ou demandez à votre IA de le réviser (« mettez à jour la conception pour utiliser une file d'attente »), puis continuez. L'IA travaille toujours à partir du contenu actuel du fichier. Guide complet : Modifier et itérer sur une modification.

Puis-je revenir en arrière et changer le plan après avoir implémenté une partie de celui-ci ?

Oui, à tout moment. Le flux de travail est fluide, donc la révision et l'édition ne sont pas des phases dont vous êtes exclu. Modifiez l'artefact, puis continuez. Si vous souhaitez une vérification structurée que le code correspond toujours au plan, exécutez /opsx:verify. Voir Modifier et itérer sur une modification.

J'ai modifié le code à la main. Comment le réconcilier avec la spécification ?

Rétablissez la synchronisation avant d'archiver, car l'archivage fait de vos spécifications la référence unique. Si le code est désormais correct, mettez à jour la spécification delta pour qu'elle corresponde à ce qui a été livré ; si la spécification est correcte, continuez à développer jusqu'à ce que le code soit conforme. /opsx:verify signale les écarts. Voir Modifier et itérer sur une modification.

Quand dois-je mettre à jour une modification existante plutôt que d'en commencer une nouvelle ?

Mettez à jour lorsqu'il s'agit du même travail, affiné. Commencez à neuf lorsque l'intention a fondamentalement changé ou que la portée a explosé vers un travail différent. Un diagramme décisionnel et des exemples se trouvent dans Flux de travail.

Que faire si ma session manque de contexte, ou si les exigences changent en cours d'implémentation ?

C'est là que les spécifications montrent leur utilité. Parce que le plan réside dans des fichiers (et pas seulement dans l'historique du chat), vous pouvez effacer votre contexte, démarrer une nouvelle session IA et reprendre avec /opsx:apply ; il lit les artefacts et reprend à la première tâche non cochée. Si les exigences changent, modifiez les artefacts pour qu'ils correspondent à la nouvelle réalité et continuez. Garder une fenêtre de contexte propre produit également de meilleurs résultats ; effacez-la avant l'implémentation.

Dois-je committer le dossier openspec/ dans git ?

Oui. Vos spécifications, modifications actives et archives font partie de l'historique de votre projet. Committez-les comme n'importe quelle autre source. L'archive devient en particulier un enregistrement durable expliquant pourquoi votre système fonctionne comme il le fait.

Spécifications et modifications

Que contient une spécification par rapport à une conception ?

Une spécification décrit le comportement observable : ce que fait le système, ses entrées, sorties et conditions d'erreur. Une conception décrit comment vous allez la construire : l'approche technique, les décisions architecturales, les changements de fichiers. Si l'implémentation peut changer sans modifier le comportement visible externalement, cela relève de la conception, pas de la spécification. Concepts approfondit ce sujet.

Qu'est-ce qu'une spécification delta ?

Une spécification qui décrit uniquement ce qui change, en utilisant les sections ADDED, MODIFIED et REMOVED, plutôt que de réécrire toute la spécification. C'est ainsi qu'OpenSpec gère proprement les modifications des systèmes existants. Voir Concepts.

Où vont les modifications archivées ?

Vers openspec/changes/archive/YYYY-MM-DD-<name>/, avec tous les artefacts de modification préservés. La modification sort de votre liste active. Une modification qui déclare explicitement retire_capabilities: true peut également supprimer une spécification de capacité principale lorsqu'elle retire la dernière exigence de cette capacité.

Configuration et personnalisation

Comment informer l'IA de ma pile technologique ?

Placez-la dans openspec/config.yaml sous context:. Ce texte est injecté dans chaque demande de planification, afin que l'IA connaisse toujours votre pile et vos conventions. Voir Personnalisation.

Puis-je générer des spécifications dans une langue autre que l'anglais ?

Oui. Ajoutez une instruction de langue au context: de votre configuration. Multi-Language fournit des extraits prêts à copier-coller pour plusieurs langues.

Puis-je modifier le flux de travail lui-même ?

Oui, avec des schémas personnalisés. Un schéma définit quels artefacts existent et comment ils dépendent les uns des autres. Forkez le défaut avec openspec schema fork spec-driven my-workflow, puis modifiez-le. Voir Personnalisation.

Modèles, confidentialité et mises à niveau

Quel modèle IA dois-je utiliser ?

OpenSpec fonctionne mieux avec des modèles à haute capacité de raisonnement. Le README recommande des modèles tels que Codex 5.5 et Opus 4.7 tant pour la planification que pour l'implémentation. Gardez également votre fenêtre de contexte propre : effacez-la avant l'implémentation pour de meilleurs résultats.

OpenSpec collecte-t-il des données ?

Il collecte des statistiques d'utilisation anonymes : noms des commandes et version uniquement. Aucun argument, chemin, contenu ou donnée personnelle, et cela est désactivé automatiquement en CI. Désactivez-le avec export OPENSPEC_TELEMETRY=0 ou export DO_NOT_TRACK=1.

Comment effectuer la mise à niveau ?

Deux étapes. Mettez à niveau le package (npm install -g @fission-ai/openspec@latest), puis exécutez openspec update dans chaque projet pour actualiser les compétences et commandes générées.

Comment désinstaller OpenSpec ?

Il n'y a pas de commande de désinstallation, car il s'agit simplement d'un package global plus des fichiers dans votre projet. Supprimez le package (npm uninstall -g @fission-ai/openspec), et éventuellement supprimez le répertoire openspec/ et les fichiers d'outil générés. Les étapes détaillées, y compris ce qu'il est sûr de conserver, se trouvent dans Installation : Désinstallation.

Obtenir de l'aide

Où poser des questions ou signaler des bugs ?

• Discord : discord.gg/YctCnvvshC
• Problèmes GitHub : github.com/Fission-AI/OpenSpec/issues
• Depuis votre terminal : openspec feedback "votre message" ouvre un problème GitHub pour vous.

Ces docs sont faux ou confuse. Que faire ?

Dites-le-nous, ou corrigez-les. Les PRs sur la documentation sont les bienvenues et appréciées. Ouvrez un problème ou envoyez une pull request.