Personnalisation

OpenSpec offre trois niveaux de personnalisation :

Niveau	Ce qu'il fait	Idéal pour
Configuration de projet	Définir des valeurs par défaut, injecter le contexte/les règles	La plupart des équipes
Schémas personnalisés	Définir vos propres artefacts de flux de travail	Équipes ayant des processus uniques
Remplacements globaux	Partager des schémas entre tous les projets	Utilisateurs avancés

---

Configuration de projet

Le fichier openspec/config.yaml est le moyen le plus simple de personnaliser OpenSpec pour votre équipe. Il vous permet :

• Définir un schéma par défaut - Éviter d'utiliser --schema à chaque commande
• Injecter le contexte du projet - L'IA voit votre pile technique, vos conventions, etc.
• Ajouter des règles par artefact - Règles personnalisées pour des artefacts spécifiques
• Ajouter des conseils par opération - Préférences de conseil pour les opérations apply et archive
• Mémoriser les choix d'intégration - par exemple l'option d'activation du GitHub Copilot cloud coding agent

Configuration rapide

openspec init

Cela vous guide à travers la création d'une configuration de manière interactive. Ou vous pouvez en créer une manuellement :

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Comment ça fonctionne

Schéma par défaut :

# Sans configuration
openspec new change my-feature --schema spec-driven

# Avec configuration - le schéma est automatique
openspec new change my-feature

Injection du contexte et des règles :

Lors de la génération d'un artefact, votre contexte et vos règles sont injectés dans l'invite IA :

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Le contexte apparaît dans TOUS les artefacts
• Les règles n'apparaissent QUE pour l'artefact correspondant

Conseils d'opération :

operations.apply.guidance et operations.archive.guidance sont des tableaux optionnels d'instructions de conseil décrivant comment un agent doit mener ces opérations. Ils sont distincts des rules : les conseils d'opération ne contraignent pas le contenu des artefacts, et les règles d'artefact ne sont jamais reclassées comme conseils d'opération.

Apply et archive récupèrent ces entrées au moment de l'exécution :

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Les deux surfaces renvoient le contexte actuel du projet et le operationGuidance correspondant comme champs optionnels distincts. Chaque appel lit un instantané frais depuis la racine résolue. Lorsque --store <id> est sélectionné, le changement, le contexte et les conseils proviennent tous de ce store plutôt que du dépôt actuel. La commande d'instructions d'archive est en lecture seule : elle n'inspecte ni ne fusionne les specs delta, ne rédige pas les specs principales, ne déplace pas le changement, ni n'exécute le flux de travail d'archive statique.

Le contexte du projet est une entrée requise au niveau de l'invite. Les workflows générés le lisent et appliquent les faits, conventions et contraintes pertinents du projet. Les conseils d'opération sont des conseils additifs facultatifs : les workflows considèrent chaque entrée et suivent celles qui sont applicables et compatibles avec le workflow intégré.

Les deux champs restent distincts de l'état contrôlé par la CLI, des chemins résolus, des étapes intégrées, des choix explicites de l'utilisateur et des règles d'artefact. Un workflow signale les conflits de contexte tout en préservant la valeur de contrôle. Il ne suit pas les conseils inapplicables ou conflictuels et en explique la raison. Aucun de ces champs n'est une vérification contraignante, et les workflows ne copient pas leur texte dans les fichiers d'implémentation, les specs, les artefacts de changement ou les résumés, sauf si l'utilisateur demande séparément ce contenu.

Sécurité des entrées de l'archive et de la synchronisation des specs :

L'archive, l'archive en masse et la synchronisation autonome utilisent artifactPaths.specs.existingOutputPaths de openspec status --json comme seule source de specs delta. Un schéma sans artefact specs, ou un changement dont la liste de sortie concrète est vide, n'a rien à synchroniser ; les autres artefacts ne sont pas utilisés pour déduire des specs delta.

Avant qu'une fusion sémantique écrive une spec principale, le workflow consomme la sortie actuelle de openspec instructions specs --change <name> --json. Les règles specs renvoyées ne contraignent que les specs principales produites par cette fusion. L'archive unique passe cet instantané à la synchronisation intégrée, la synchronisation autonome le récupère directement, et l'archive en masse obtient chaque instantané requis avant sa première écriture de spec. Une réponse JSON non nulle ou invalide des instructions d'archive/specs est un échec de recherche, pas une entrée vide : le workflow s'arrête avant l'écriture de la spec affectée ou le déplacement du changement (pour l'archive en masse, avant toute écriture ou déplacement par lot).

Cette configuration ne modifie pas les phases d'exécution de l'archive, les invites utilisateur, les opérations du système de fichiers, la propriété de la fusion sémantique, la commande directe openspec archive, ni la structure et le résultat des rules d'artefact.

Ordre de résolution du schéma

Lorsqu'OpenSpec a besoin d'un schéma, il vérifie dans cet ordre :

1. Option CLI : --schema <name>
2. Métadonnées du changement (.openspec.yaml dans le dossier du changement)
3. Configuration du projet (openspec/config.yaml)
4. Valeur par défaut (spec-driven)

---

Schémas personnalisés

Lorsque la configuration du projet ne suffit pas, créez votre propre schéma avec un workflow entièrement personnalisé. Les schémas personnalisés se trouvent dans le répertoire openspec/schemas/ de votre projet et sont versionnés avec votre code.

your-project/
├── openspec/
│   ├── config.yaml        # Configuration du projet
│   ├── schemas/           # Les schémas personnalisés se trouvent ici
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Vos modifications
└── src/

Forker un schéma existant

Le moyen le plus rapide de personnaliser est de forker un schéma intégré :

openspec schema fork spec-driven my-workflow

Ceci copie l'intégralité du schéma spec-driven vers openspec/schemas/my-workflow/ où vous pouvez le modifier librement.

Ce que vous obtenez :

openspec/schemas/my-workflow/
├── schema.yaml           # Définition du workflow
└── templates/
    ├── proposal.md       # Modèle pour l'artefact de proposition
    ├── spec.md           # Modèle pour les spécifications
    ├── design.md         # Modèle pour la conception
    └── tasks.md          # Modèle pour les tâches

Modifiez maintenant schema.yaml pour changer le workflow, ou modifiez les modèles pour changer ce que l'IA génère.

Créer un schéma de zéro

Pour un workflow entièrement nouveau :

# Interactif
openspec schema init research-first

# Non interactif
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Structure du schéma

Un schéma définit les artefacts de votre workflow et leurs dépendances mutuelles :

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: Workflow personnalisé de mon équipe

artifacts:
  - id: proposal
    generates: proposal.md
    description: Document de proposition initiale
    template: proposal.md
    instruction: |
      Créer une proposition qui explique POURQUOI ce changement est nécessaire.
      Concentrez-vous sur le problème, pas sur la solution.
    requires: []

  - id: design
    generates: design.md
    description: Conception technique
    template: design.md
    instruction: |
      Créer un document de conception expliquant COMMENT implémenter.
    requires:
      - proposal    # Impossible de créer la conception tant que la proposition n'existe pas

  - id: tasks
    generates: tasks.md
    description: Liste de contrôle de mise en œuvre
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Champs clés :

Champ	Objectif
id	Identifiant unique, utilisé dans les commandes et les règles
generates	Nom du fichier de sortie (prend en charge les globs comme specs/**/*.md)
template	Fichier de modèle dans le répertoire templates/
instruction	Instructions IA pour la création de cet artefact
requires	Dépendances - quels artefacts doivent exister en premier

Listez les artefacts dans l'ordre dans lequel vous voulez qu'ils soient écrits. requires décide ce qui est possible ; l'ordre de la liste artifacts: décide ce qui vient en premier lorsque plusieurs artefacts sont prêts en même temps.

Modèles

Les modèles sont des fichiers markdown qui guident l'IA. Ils sont injectés dans le prompt lors de la création de cet artefact.

<!-- templates/proposal.md -->
## Pourquoi

<!-- Expliquez la motivation de ce changement. Quel problème cela résout-il ? -->

## Ce qui change

<!-- Décrivez ce qui va changer. Soyez précis sur les nouvelles capacités ou modifications. -->

## Impact

<!-- Code, API, dépendances, systèmes affectés -->

Les modèles peuvent inclure :

• En-têtes de section que l'IA doit remplir
• Commentaires HTML avec des instructions pour l'IA
• Exemples de formats montrant la structure attendue

Valider votre schéma

Avant d'utiliser un schéma personnalisé, validez-le :

openspec schema validate my-workflow

Ceci vérifie :

• La syntaxe de schema.yaml est correcte
• Tous les modèles référencés existent
• Aucune dépendance circulaire
• Les identifiants d'artefacts sont valides

Utiliser votre schéma personnalisé

Une fois créé, utilisez votre schéma avec :

# Spécifiez en ligne de commande
openspec new change feature --schema my-workflow

# Ou définissez-le comme défaut dans config.yaml
schema: my-workflow

Déboguer la résolution de schéma

Vous n'êtes pas sûr du schéma utilisé ? Vérifiez avec :

# Voir d'où provient un schéma spécifique
openspec schema which my-workflow

# Lister tous les schémas disponibles
openspec schema which --all

La sortie indique s'il provient de votre projet, du répertoire utilisateur ou du package :

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Remarque : OpenSpec prend également en charge les schémas au niveau utilisateur dans ~/.local/share/openspec/schemas/ pour un partage entre projets, mais les schémas au niveau projet dans openspec/schemas/ sont recommandés car ils sont versionnés avec votre code.

---

Exemples

Workflow d'itération rapide

Un workflow minimal pour des itérations rapides :

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Itération rapide avec un minimum de surcharge

artifacts:
  - id: proposal
    generates: proposal.md
    description: Proposition rapide
    template: proposal.md
    instruction: |
      Créez une brève proposition pour ce changement.
      Concentrez-vous sur le quoi et le pourquoi, ignorez les spécifications détaillées.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Liste de contrôle de mise en œuvre
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Ajout d'un artefact de révision

Forkez le schéma par défaut et ajoutez une étape de révision :

openspec schema fork spec-driven with-review

Modifiez ensuite schema.yaml pour ajouter :

  - id: review
    generates: review.md
    description: Liste de contrôle de révision avant implémentation
    template: review.md
    instruction: |
      Créez une liste de contrôle de révision basée sur la conception.
      Incluez des considérations de sécurité, de performance et de test.
    requires:
      - design

  - id: tasks
    # ... configuration existante des tâches ...
    requires:
      - specs
      - design
      - review    # Maintenant, les tâches nécessitent aussi une révision

---

Schémas communautaires

OpenSpec prend également en charge les schémas maintenus par la communauté et distribués via des dépôts autonomes. Ceux-ci fournissent des workflows opiniâtres qui intègrent OpenSpec avec d'autres outils ou systèmes, de manière similaire au catalogue d'extensions communautaires de github/spec-kit pour spec-kit.

Les schémas communautaires ne sont pas intégrés dans le cœur d'OpenSpec — ils vivent dans leurs propres dépôts avec leur propre cadence de publication. Pour en utiliser un, copiez le bundle de schéma dans le répertoire openspec/schemas/<schema-name>/ de votre projet (le README de chaque dépôt contient des instructions d'installation).

Schéma	Mainteneur	Référentiel	Description
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Capture l'intention du changement, le comportement observable, la conception technique et les décisions architecturales durables avant l'implémentation. Ajoute un manifeste de révision ADR local au changement et écrit les décisions à longue durée de vie éligibles comme des ADR immuables et remplaçables.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Intègre la gouvernance des artefacts d'OpenSpec avec les compétences d'exécution de obra/superpowers (brainstorming, rédaction de plans, TDD via sous-agents, revue de code, finition). Ajoute un artefact retrospective axé sur les preuves pour combler une lacune que Superpowers ne couvre pas nativement.
nanopm	@nmrtn	nmrtn/nanopm	Workflow PM-first. Exécute le pipeline de planification de nanopm (audit → stratégie → feuille de route → PRD) en amont de l'implémentation. Relie la planification produit au workflow d'ingénierie piloté par spécifications d'OpenSpec. Les artefacts proviennent de .nanopm/ s'ils sont présents — la proposition provient de l'audit, la conception de la stratégie et les tâches de la répartition du PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbooks de tests de bout en bout au niveau des capacités. Chaque capacité obtient une spécification immuable, un modèle de tâches immuable et un enregistrement d'exécution horodaté par exécution. Les assertions ne portent que sur le comportement observable (statut HTTP, corps de réponse, état persistant — jamais de sous-chaînes de journaux) ; chaque exécution enregistre le début/fin UTC, la durée et la consommation estimée de jetons LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Workflow piloté par spécifications avec discipline TDD et une étape de révision contradictoire. Flux : proposal → specs → design → review → test-plan → tasks → apply → verify. review est rédigé par un relecteur en contexte neuf, en lecture seule (un deuxième modèle lorsque disponible) et émet une ligne VERDICT: indiquant à l'agent de contrôler test-plan, tasks et apply ; OpenSpec ne vérifie que l'existence des artefacts, donc imposez ce contrôle avec votre propre CI ou hook. test-plan mappe chaque scénario de spécification à un test nommé et sert de registre rouge/vert que verify audite.

Vous souhaitez contribuer un schéma communautaire ? Ouvrez une issue avec un lien vers votre dépôt, ou soumettez une PR ajoutant une ligne à ce tableau.

---

Voir aussi

• Référence CLI : Commandes de schéma - Documentation complète des commandes