Configurazione del progetto

Rendi le modifiche al piano dei workflow come desideri con poche righe in config.yaml.

openspec/config.yaml indica ai workflow come vuoi che vengano pianificate le modifiche.

Ad esempio, la seguente configurazione aggiorna le regole di creazione per l'artifact tasks.md:

rules:
  tasks:
    - End every task with a commit

Quando l'agente viene eseguito, utilizza queste regole e si assicura che ogni task termini con un passaggio di commit.

Mantieni le regole brevi. Tutto ciò che è presente qui finisce nel contesto dell'agente e regole verbose possono peggiorare l'output.

Come funziona

config.yaml contiene istruzioni che l'agente riceve quando crea artifact o esegue il workflow.

Ecco cosa succede a ogni esecuzione:

1. Esegui un workflow (ad esempio /openspec-propose).
2. L'agente richiama il comando openspec instructions.
3. Il comando legge il contesto e le regole da config.yaml.
4. Le istruzioni integrate di OpenSpec e le tue personalizzazioni vengono combinate in un unico prompt per l'agente.
5. L'agente segue quel prompt per scrivere l'artifact.

Ad esempio, con un campo context e la regola dall'inizio di questa pagina, ecco cosa openspec instructions restituisce per tasks.md (ridotto e annotato):

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

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

  <!-- Dal tuo config.yaml: regole per tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- Da OpenSpec: la guida integrata -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

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

</artifact>

La tua configurazione arriva per prima, poi l'istruzione integrata e il template di OpenSpec. Le regole si aggiungono agli elementi integrati e non li sostituiscono mai. Le modifiche a config.yaml raggiungono l'agente alla successiva esecuzione.

I campi

Tre campi definiscono ciò che l'agente riceve. Il contratto esatto di ciascun campo (tipi, limiti, validazione) si trova in Configurazione del progetto (config.yaml).

Campo	Cosa fa	Iniettato in
context	Istruzioni che l'agente riceve sempre	Tutto: ogni artifact, apply, archive
rules	Istruzioni aggiuntive per un artifact	Solo la creazione di quell'artifact
operations	Guida su come viene eseguito un passaggio del workflow	Solo apply e archive

Gli altri campi di config.yaml (schema, store, references) selezionano quale schema e quale root di OpenSpec utilizza un progetto. La pagina del contratto li tratta.

L'ultima colonna è precisa, quindi un campo raggiunge solo i passaggi elencati lì. In particolare, verify non riceve mai rules. Verifica l'implementazione rispetto agli artifact così come sono scritti.

context

context è il contesto di sfondo che l'agente riceve quando crea un artifact, applica task o archivia una modifica.

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

Usa context per fatti e vincoli che dovrebbero plasmare l'output del workflow. Mantieni la documentazione duratura del progetto nei file di documentazione del progetto e escludi tutto ciò che l'agente può imparare leggendo il codice.

Un'altra lingua: poiché il contesto raggiunge ogni artifact, puoi aggiungere Write all artifacts in Spanish. per istruire l'agente a scrivere gli artifact di proposal, spec, design e tasks in spagnolo.

rules

rules si collega a un artifact, indicizzato dall'id dell'artifact. Ogni riga viene aggiunta alla guida integrata di quell'artifact:

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

Le proposal ora rimangono brevi e tasks.md pianifica sempre test del browser. Ogni altro artifact rimane invariato.

operations

operations guida come l'agente esegue apply e archive, piuttosto che ciò che gli artifact dicono:

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

Durante apply, l'agente esegue il linting mentre completa i task. Durante archive, conclude con un riepilogo.

Quando config.yaml non è sufficiente

La configurazione aggiunge istruzioni al workflow standard, ma non può cambiare quali artifact esistono o come sono strutturati. Quando desideri quel livello di controllo, o le regole non guidano il comportamento in modo coerente, forka uno schema.