Personalizzazione

OpenSpec offre tre livelli di personalizzazione:

Livello	Cosa fa	Ideale per
Configurazione di Progetto	Imposta i default, inietta contesto/regole	La maggior parte dei team
Schemi Personalizzati	Definisci i tuoi artefatti di workflow	Team con processi unici
Override Globali	Condividi schemi tra tutti i progetti	Utenti esperti

---

Configurazione del Progetto

Il file openspec/config.yaml è il modo più semplice per personalizzare OpenSpec per il tuo team. Ti consente di:

• Impostare uno schema predefinito - Evita di dover usare --schema su ogni comando
• Iniettare il contesto del progetto - L'IA vede il tuo stack tecnologico, le convenzioni, ecc.
• Aggiungere regole per artefatto - Regole personalizzate per artefatti specifici
• Aggiungere una guida per operazione - Preferenze consultive per il lavoro di apply e archive
• Ricordare le scelte di integrazione - ad es. l'agente di codifica cloud di GitHub Copilot opzionale

Configurazione Rapida

openspec init

Questo ti guida nella creazione interattiva di una configurazione. Oppure creane una manualmente:

# 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

# Impostato da `openspec init` quando scegli (o rifiuti) l'agente di codifica
# cloud di GitHub Copilot; controlla se `init`/`update` generano i relativi file.
githubCopilot:
  cloudAgent: false

Come Funziona

Schema predefinito:

# Senza config
openspec new change my-feature --schema spec-driven

# Con config - lo schema è automatico
openspec new change my-feature

Iniezione di contesto e regole:

Quando si genera un qualsiasi artefatto, il contesto e le regole vengono iniettati nel prompt dell'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>

• Il contesto appare in TUTTI gli artefatti
• Le regole appaiono SOLO per l'artefatto corrispondente

Guida alle operazioni:

operations.apply.guidance e operations.archive.guidance sono array opzionali di istruzioni consultive su come un agente dovrebbe condurre tali operazioni. Sono separati dalle rules: la guida alle operazioni non vincola il contenuto dell'artefatto, e le regole degli artefatti non vengono mai ri-etichettate come guida alle operazioni.

Le operazioni apply e archive recuperano questi input al momento dell'esecuzione:

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

Entrambe le superfici restituiscono il context del progetto corrente e la operationGuidance corrispondente come campi opzionali separati. Ogni invocazione legge uno snapshot fresco dalla root risolta. Quando viene selezionato --store <id>, la modifica, il contesto e la guida provengono tutti da quello store anziché dal repository corrente. Il comando di istruzioni per l'archivio è di sola lettura: non ispeziona né unisce le specifiche delta, non scrive le specifiche principali, non sposta la modifica e non esegue il workflow statico di archiviazione.

Il contesto di progetto è un input richiesto a livello di prompt. I workflow generati lo leggono e applicano fatti, convenzioni e vincoli rilevanti del progetto. La guida alle operazioni è un consiglio additivo opzionale: i workflow considerano ogni voce e seguono le voci che sono applicabili e compatibili con il workflow integrato.

Entrambi i campi rimangono separati dallo stato controllato dalla CLI, dai percorsi risolti, dai passi integrati, dalle scelte esplicite dell'utente e dalle regole degli artefatti. Un workflow segnala conflitti di contesto preservando il valore dominante. Non segue guide inapplicabili o in conflitto e spiega perché. Nessuno dei due campi è un controllo esecutivo, e i workflow non copiano il loro testo nei file di implementazione, nelle specifiche, negli artefatti di modifica o nei riassunti, a meno che l'utente non richieda separatamente quel contenuto.

Sicurezza degli input per archive e sync delle specifiche:

Archive, bulk archive e sync autonomo utilizzano artifactPaths.specs.existingOutputPaths da openspec status --json come unica sorgente di specifiche delta. Uno schema senza artefatto specs, o una modifica la cui lista di output concreti è vuota, non ha nulla da sincronizzare; altri artefatti non vengono usati per inferire specifiche delta.

Prima che un merge semantico scriva una specifica principale, il workflow consuma l'output corrente di openspec instructions specs --change <name> --json. Le regole specs restituite vincolano solo le specifiche principali prodotte da quel merge. L'archivio singolo passa quello snapshot nel sync inline, il sync autonomo lo recupera direttamente, e il bulk archive ottiene ogni snapshot richiesto prima della sua prima scrittura di specifica. Una risposta non-zero o JSON non valido per le istruzioni archive/specs è un errore di ricerca, non un input vuoto: il workflow si ferma prima della scrittura della specifica interessata o dello spostamento della modifica (per il bulk archive, prima di qualsiasi scrittura o spostamento batch).

Questa configurazione non cambia le fasi di esecuzione dell'archivio, i prompt utente, le operazioni sul filesystem, la proprietà del merge semantico, il comando diretto openspec archive, o la struttura e l'output delle rules degli artefatti.

Ordine di Risoluzione dello Schema

Quando OpenSpec ha bisogno di uno schema, controlla in questo ordine:

1. Flag CLI: --schema <name>
2. Metadati della modifica (.openspec.yaml nella cartella della modifica)
3. Configurazione di progetto (openspec/config.yaml)
4. Default (spec-driven)

Schemi Personalizzati

Quando la configurazione di progetto non è sufficiente, crea il tuo schema con un workflow completamente personalizzato. Gli schemi personalizzati risiedono nella directory openspec/schemas/ del tuo progetto e sono versionati con il tuo codice.

your-project/
├── openspec/
│   ├── config.yaml        # Configurazione di progetto
│   ├── schemas/           # Gli schemi personalizzati risiedono qui
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Le tue modifiche
└── src/

Creare una Copia di uno Schema Esistente

Il modo più rapido per personalizzare è creare una copia di uno schema integrato:

openspec schema fork spec-driven my-workflow

Questo copia l'intero schema spec-driven in openspec/schemas/my-workflow/, dove puoi modificarlo liberamente.

Cosa ottieni:

openspec/schemas/my-workflow/
├── schema.yaml           # Definizione del workflow
└── templates/
    ├── proposal.md       # Template per l'artefatto proposal
    ├── spec.md           # Template per le specifiche
    ├── design.md         # Template per il design
    └── tasks.md          # Template per i task

Ora modifica schema.yaml per cambiare il workflow, oppure modifica i template per cambiare ciò che l'IA genera.

Creare uno Schema da Zero

Per un workflow completamente nuovo:

# Interattivo
openspec schema init research-first

# Non interattivo
openspec schema init rapid \
  --description "Workflow di iterazione rapida" \
  --artifacts "proposal,tasks" \
  --default

Struttura dello Schema

Uno schema definisce gli artefatti del tuo workflow e come dipendono tra loro:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: Workflow personalizzato del mio team

artifacts:
  - id: proposal
    generates: proposal.md
    description: Documento di proposta iniziale
    template: proposal.md
    instruction: |
      Crea una proposta che spieghi PERCHÉ questa modifica è necessaria.
      Concentrati sul problema, non sulla soluzione.
    requires: []

  - id: design
    generates: design.md
    description: Design tecnico
    template: design.md
    instruction: |
      Crea un documento di design che spieghi COME implementare.
    requires:
      - proposal    # Non è possibile creare il design finché la proposta non esiste

  - id: tasks
    generates: tasks.md
    description: Lista di controllo per l'implementazione
    template: tasks.md
    requires:
      - design

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

Campi chiave:

Campo	Scopo
id	Identificatore univoco, utilizzato nei comandi e nelle regole
generates	Nome del file di output (supporta glob come specs/**/*.md)
template	File template nella directory templates/
instruction	Istruzioni AI per creare questo artefatto
requires	Dipendenze - quali artefatti devono esistere prima

Elenca gli artefatti nell'ordine in cui desideri che vengano scritti. requires determina cosa è possibile; l'ordine dell'elenco artifacts: decide cosa viene prima quando più artefatti sono pronti contemporaneamente.

Template

I template sono file Markdown che guidano l'IA. Vengono iniettati nel prompt quando si crea quell'artefatto.

<!-- templates/proposal.md -->
## Perché

<!-- Spiega la motivazione per questa modifica. Quale problema risolve? -->

## Cosa Cambia

<!-- Descrivi cosa cambierà. Sii specifico riguardo alle nuove capacità o modifiche. -->

## Impatto

<!-- Codice coinvolto, API, dipendenze, sistemi -->

I template possono includere:

• Intestazioni di sezione che l'IA deve compilare
• Commenti HTML con indicazioni per l'IA
• Formati di esempio che mostrano la struttura prevista

Validare il Tuo Schema

Prima di utilizzare uno schema personalizzato, validalo:

openspec schema validate my-workflow

Questo controlla:

• La sintassi di schema.yaml è corretta
• Tutti i template referenziati esistono
• Nessuna dipendenza circolare
• Gli ID degli artefatti sono validi

Utilizzare il Tuo Schema Personalizzato

Una volta creato, usa il tuo schema con:

# Specifica da riga di comando
openspec new change feature --schema my-workflow

# Oppure imposta come predefinito in config.yaml
schema: my-workflow

Debug della Risoluzione dello Schema

Non sei sicuro di quale schema viene utilizzato? Controlla con:

# Vedi da dove si risolve uno schema specifico
openspec schema which my-workflow

# Elenca tutti gli schemi disponibili
openspec schema which --all

L'output mostra se proviene dal tuo progetto, dalla directory utente o dal pacchetto:

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

---

Nota: OpenSpec supporta anche schemi a livello utente in ~/.local/share/openspec/schemas/ per la condivisione tra progetti, ma gli schemi a livello di progetto in openspec/schemas/ sono raccomandati poiché vengono versionati con il tuo codice.

---

Esempi

Workflow di Iterazione Rapida

Un workflow minimale per iterazioni veloci:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Iterazione veloce con overhead minimale

artifacts:
  - id: proposal
    generates: proposal.md
    description: Proposta rapida
    template: proposal.md
    instruction: |
      Crea una breve proposta per questa modifica.
      Concentrati su cosa e perché, salta specifiche dettagliate.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Lista di controllo per l'implementazione
    template: tasks.md
    requires: [proposal]

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

Aggiungere un Artefatto di Revisione

Crea una copia del predefinito e aggiungi una fase di revisione:

openspec schema fork spec-driven with-review

Poi modifica schema.yaml per aggiungere:

  - id: review
    generates: review.md
    description: Lista di controllo di revisione pre-implementazione
    template: review.md
    instruction: |
      Crea una lista di controllo di revisione basata sul design.
      Includi considerazioni su sicurezza, prestazioni e testing.
    requires:
      - design

  - id: tasks
    # ... configurazione dei task esistente ...
    requires:
      - specs
      - design
      - review    # Ora i task richiedono anche la revisione

---

Schemi della Comunità

OpenSpec supporta anche schemi mantenuti dalla comunità, distribuiti tramite repository standalone. Questi forniscono workflow opinionati che integrano OpenSpec con altri strumenti o sistemi, in modo simile a come catalogo delle estensioni della comunità di github/spec-kit funziona per spec-kit.

Gli schemi della comunità non sono inclusi nel core di OpenSpec — vivono nei propri repository con il proprio ciclo di rilascio. Per usarne uno, copia il bundle dello schema nella directory openspec/schemas/<nome-schema>/ del tuo progetto (il README di ogni repository contiene le istruzioni di installazione).

Schema	Manutentore	Repository	Descrizione
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Cattura l'intento della modifica, il comportamento osservabile, il design tecnico e le decisioni architetturali durevoli prima dell'implementazione. Aggiunge un manifest di revisione ADR locale alla modifica e scrive decisioni di lunga durata qualificanti come ADR immutabili e sostituibili.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integra la governance degli artefatti di OpenSpec con le competenze di esecuzione di obra/superpowers (brainstorming, stesura di piani, TDD tramite sub-agenti, revisione del codice, completamento). Aggiunge un artefatto retrospective basato sull'evidenza che colma una lacuna non coperta nativamente da Superpowers.
nanopm	@nmrtn	nmrtn/nanopm	Workflow PM-first. Esegue la pipeline di pianificazione di nanopm (audit → strategia → roadmap → PRD) prima dell'implementazione. Collega la pianificazione del prodotto al workflow di ingegneria spec-driven di OpenSpec. Gli artefatti leggono da .nanopm/ se presente — la proposta trae l'audit, il design la strategia e i task la suddivisione del PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbook di test end-to-end a livello di capacità. Ogni capacità ottiene una specifica immutabile, un template di task immutabile e un record di esecuzione con timestamp per ogni esecuzione. Le asserzioni sono solo comportamento osservabile (stato HTTP, corpo della risposta, stato persistito — mai sottostringhe di log); ogni esecuzione registra inizio/fine UTC, durata e una stima del consumo di token LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Workflow spec-driven con disciplina TDD e una fase di revisione avversaria. Flusso: proposal → specs → design → review → test-plan → tasks → apply → verify. review è scritto da un revisore con contesto nuovo e sola lettura (un secondo modello quando disponibile) ed emette una riga VERDICT: che dice all'agente di bloccare test-plan, tasks e apply; OpenSpec verifica solo che gli artefatti esistano, quindi applica il blocco con il tuo CI o hook. test-plan mappa ogni scenario di specifica a un test nominato e funge anche da registro rosso/verde che verify controlla.

Vuoi contribuire con uno schema della comunità? Apri un issue con un link al tuo repository, oppure invia una PR aggiungendo una riga a questa tabella.

---

Vedi Anche

• Riferimento CLI: Comandi Schema - Documentazione completa dei comandi