Project configuration

Stuur de workflows hoe wijzigingen worden gepland, met een paar regels in config.yaml.

openspec/config.yaml vertelt de workflows hoe wijzigingen gepland moeten worden.

Bijvoorbeeld, de volgende configuratie atualiseert de creatieregels voor het tasks.md-artefact:

rules:
  tasks:
    - End every task with a commit

Wanneer de agent wordt uitgevoerd, haalt deze informatie uit deze regels en zorgt ervoor dat elke taak eindigt met een commit-stap.

Houd regels kort. Alles hier komt in de context van de agent terecht, en uitgebreide regels kunnen de output verslechteren.

Hoe het werkt

config.yaml bevat instructies die de agent ontvangt wanneer het artefacten aanmaakt of door de workflow werkt.

Dit is wat er gebeurt bij elke uitvoering:

1. Je voert een workflow uit (bijv. /openspec-propose).
2. De agent roept de openspec instructions-opdracht aan.
3. De opdracht leest je context en regels uit config.yaml.
4. De ingebouwde instructies van OpenSpec en jouw aanpassingen worden gecombineerd tot één enkele prompt voor de agent.
5. De agent volgt die prompt om het artefact te schrijven.

Bijvoorbeeld, met een context-veld en de regel bovenaan deze pagina, dit is wat openspec instructions retourneert voor tasks.md (beknipt en aangevuld met commentaar):

<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>

Jouw configuratie arriveert als eerste, gevolgd door de ingebouwde instructie en sjabloon van OpenSpec. Regels worden toegevoegd aan de ingebouwde instructies en vervangen deze nooit. Wijzigingen in config.yaml bereiken de agent bij de volgende uitvoering.

De velden

Drie velden bepalen wat de agent ontvangt. De exacte specificatie (types, limieten, validatie) van elk veld staat in Project configuration (config.yaml).

Veld	Wat het doet	Gecombineerd met
context	Instructies die de agent altijd ontvangt	Alles: elk artefact, apply, archive
rules	Bijkomende instructies voor één artefact	Alleen de creatie van dat artefact
operations	Richtlijnen voor hoe een workflowstap wordt uitgevoerd	Alleen apply en archive

De andere velden van config.yaml (schema, store, references) selecteren welk schema en welke OpenSpec-basis een project gebruikt. Het specificatiepagina dekt deze velden.

De laatste kolom is exact, dus een veld bereikt alleen de daarin genoemde stappen. Met name, verify ontvangt nooit rules. Het controleert de implementatie op basis van de artefacten zoals ze zijn geschreven.

context

context is achtergrondinformatie die de agent ontvangt wanneer het een artefact aanmaakt, taken toepast of een wijziging opbergt.

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

Gebruik context voor feiten en beperkingen die de workflowoutput moeten vormgeven. Houd duurzame projectdocumentatie in de documentatiebestanden van het project, en laat alles weg wat de agent kan leren door de code te lezen.

Andere taal: omdat context elk artefact bereikt, kun je Write all artifacts in Spanish. toevoegen om de agent te instrueren om voorstel-, specificatie-, ontwerp- en taakartefacten in het Spaans te schrijven.

rules

rules worden gekoppeld aan één artefact, geïndexeerd op artefact-id. Elke regel wordt toegevoegd aan de ingebouwde richtlijnen voor dat artefact:

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

Vorstellen blijven nu kort en tasks.md plant altijd browsertests. Elk ander artefact blijft onaangetast.

operations

operations stuurt aan hoe de agent apply en archive uitvoert, in plaats van wat de artefacten zeggen:

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

Tijdens apply lints de agent terwijl het taken afrondt. Tijdens archive sluit het af met een samenvatting.

Wanneer config.yaml niet genoeg is

Config voegt instructies toe bovenop de standaardworkflow, maar het kan niet wijzigen welke artefacten bestaan of hoe ze gestructureerd zijn. Wanneer je die mate van controle wilt, of regels het gedrag niet consistent sturen, fork een schema.