Configuration du projet

Faites en sorte que les workflows planifient les changements comme vous le souhaitez avec quelques lignes dans config.yaml.

openspec/config.yaml indique aux workflows comment vous souhaitez que les changements soient planifiés.

Par exemple, la configuration suivante met à jour les règles de création de l'artefact tasks.md :

rules:
  tasks:
    - End every task with a commit

Lorsque l'agent s'exécute, il récupère ces règles et s'assure que chaque tâche se termine par une étape de commit.

Gardez les règles courtes. Tout ce qui se trouve ici est intégré au contexte de l'agent, et des règles trop verbeuses peuvent dégrader la qualité des résultats.

Comment ça fonctionne

config.yaml contient des instructions que l'agent reçoit lorsqu'il crée des artefacts ou parcourt le workflow.

Voici ce qui se passe à chaque exécution :

1. Vous lancez un workflow (par exemple /openspec-propose).
2. L'agent appelle la commande openspec instructions.
3. La commande lit votre contexte et vos règles depuis config.yaml.
4. Les instructions intégrées d'OpenSpec et vos personnalisations sont combinées en une seule invite pour l'agent.
5. L'agent suit cette invite pour rédiger l'artefact.

Par exemple, avec un champ context et la règle du haut de cette page, voici ce que openspec instructions renvoie pour tasks.md (extrait annoté) :

<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- From your config.yaml: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- From your config.yaml: rules for tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- From OpenSpec: the built-in guidance -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

  <template>
    ...the tasks.md structure to fill in...
  </template>

</artifact>

Votre configuration arrive en premier, puis l'instruction et le modèle intégrés d'OpenSpec. Les règles s'ajoutent aux instructions intégrées et ne les remplacent jamais. Les modifications apportées à config.yaml parviennent à l'agent lors de l'exécution suivante.

Les champs

Trois champs déterminent ce que l'agent reçoit. Le contrat exact de chaque champ (types, limites, validation) se trouve dans Configuration du projet (config.yaml).

Champ	Rôle	Injecté dans
context	Instructions que l'agent reçoit toujours	Tout : chaque artefact, apply, archive
rules	Instructions supplémentaires pour un artefact	Uniquement la création de cet artefact
operations	Directives sur la manière dont une étape du workflow est exécutée	Uniquement apply et archive

Les autres champs de config.yaml (schema, store, references) sélectionnent le schéma et la racine OpenSpec utilisés par un projet. La page de contrat les couvre.

La dernière colonne est exacte : un champ n'atteint que les étapes qui y sont listées. En particulier, verify ne reçoit jamais les rules. Il vérifie l'implémentation par rapport aux artefacts tels qu'ils sont rédigés.

context

context est le contexte de fond que l'agent reçoit lorsqu'il crée un artefact, applique des tâches ou archive un changement.

context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

Utilisez context pour les faits et les contraintes qui doivent orienter les résultats du workflow. Conservez la documentation durable du projet dans les fichiers de documentation du projet, et excluez tout ce que l'agent peut apprendre en lisant le code.

Une autre langue : comme le contexte atteint chaque artefact, vous pouvez ajouter Write all artifacts in Spanish. pour demander à l'agent de rédiger les artefacts proposal, spec, design et tasks en espagnol.

rules

Les rules s'attachent à un artefact, indexées par identifiant d'artefact. Chaque ligne est ajoutée aux instructions intégrées de cet artefact :

rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

Les propositions restent désormais concises et tasks.md planifie toujours les tests de navigateur. Tous les autres artefacts ne sont pas affectés.

operations

operations guide la manière dont l'agent exécute apply et archive, plutôt que ce que contiennent les artefacts :

operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

Pendant apply, l'agent exécute le linter au fur et à mesure qu'il termine les tâches. Pendant archive, il conclut par un résumé.

Quand config.yaml ne suffit pas

La configuration ajoute des instructions par-dessus le workflow standard, mais elle ne peut pas modifier les artefacts existants ni leur structure. Lorsque vous souhaitez ce niveau de contrôle, ou lorsque les règles ne dirigent pas le comportement de manière cohérente, forkez un schéma.