OpenSpec

Migrazione a OPSX ​

Questa guida ti aiuta a passare dal vecchio workflow OpenSpec a OPSX. La migrazione è progettata per essere fluida: il tuo lavoro esistente viene preservato e il nuovo sistema offre maggiore flessibilità.

Cosa cambia? ​

OPSX sostituisce il vecchio workflow basato su fasi rigide con un approccio fluido e basato su azioni. Ecco il cambiamento chiave:

AspettoLegacyOPSX
Comandi/openspec:proposal, /openspec:apply, /openspec:archiveDefault: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (comandi workflow estesi opzionali)
WorkflowCrea tutti gli artefatti in una voltaCrea incrementalmente o tutto in una volta—a tua scelta
Tornare indietroFasi rigide e scomodeNaturale—aggiorna qualsiasi artefatto in qualsiasi momento
PersonalizzazioneStruttura fissaBasato su schema, completamente modificabile
ConfigurazioneCLAUDE.md con marcatori + project.mdConfig pulita in openspec/config.yaml

Il cambiamento di filosofia: Il lavoro non è lineare. OPSX smette di fingere che lo sia.

Prima di Iniziare ​

Il Tuo Lavoro Esistente è Al Sicuro ​

Il processo di migrazione è progettato con la preservazione come priorità:

  • Modifiche attive in openspec/changes/ — Completamente preservate. Puoi continuare con i comandi OPSX.
  • Modifiche archiviate — Intatte. La tua cronologia rimane intatta.
  • Spec principali in openspec/specs/ — Intatte. Queste sono la tua fonte di verità.
  • Il tuo contenuto in CLAUDE.md, AGENTS.md, ecc. — Preservato. Vengono rimossi solo i blocchi marker di OpenSpec; tutto ciò che hai scritto resta.

Cosa Viene Rimosso ​

Solo i file gestiti da OpenSpec che vengono sostituiti:

CosaPerché
Directory/file dei comandi slash legacySostituiti dal nuovo sistema di skills
openspec/AGENTS.mdTrigger di workflow obsoleto
Marker di OpenSpec in CLAUDE.md, AGENTS.md, ecc.Non più necessari

Posizioni dei comandi legacy per strumento (esempi—il tuo strumento può variare):

  • Claude Code: .claude/commands/openspec/
  • Cursor: .cursor/commands/openspec-*.md
  • Devin Desktop, precedentemente Windsurf: .windsurf/workflows/openspec-*.md
  • Cline: .clinerules/workflows/openspec-*.md
  • Roo: .roo/commands/openspec-*.md
  • GitHub Copilot: .github/prompts/openspec-*.prompt.md (solo estensioni IDE; non supportato in Copilot CLI)
  • Codex: OpenSpec ora utilizza il percorso canonico .agents/skills/openspec-*. I file SKILL.md gestiti da OpenSpec sotto il precedente percorso .codex/skills vengono riconciliati solo dopo che esistono i sostituti; i file personalizzati e le copie divergenti restano al loro posto. Se un albero .agents non marcato contiene già skills di OpenSpec, OpenSpec preserva il rendering esistente di Codex ($openspec-*) o generico (/openspec-*) invece di indovinare dalla directory legacy. Seleziona codex esplicitamente con openspec init per cambiare la proprietà. La pulizia dei prompt legacy riguarda ancora solo i nomi file approvati da OpenSpec in $CODEX_HOME/prompts o ~/.codex/prompts.
  • E altri (Augment, Continue, Amazon Q, ecc.)

La migrazione rileva quali strumenti hai configurato e pulisce i loro file legacy.

L'elenco delle rimozioni può sembrare lungo, ma si tratta di tutti file creati originariamente da OpenSpec. Il tuo contenuto personale non viene mai eliminato.

Cosa Richiede la Tua Attenzione ​

Un file richiede migrazione manuale:

openspec/project.md — Questo file non viene eliminato automaticamente perché potrebbe contenere contesto di progetto scritto da te. Dovrai:

  1. Rivederne il contenuto
  2. Spostare il contesto utile in openspec/config.yaml (vedi indicazioni sotto)
  3. Eliminare il file quando sei pronto

Perché abbiamo fatto questo cambiamento:

Il vecchio project.md era passivo—gli agenti potevano leggerlo, potevano non leggerlo, potevano dimenticare cosa avevano letto. Abbiamo riscontrato affidabilità incoerente.

Il nuovo contesto in config.yaml viene iniettato attivamente in ogni richiesta di pianificazione di OpenSpec. Questo significa che le tue convenzioni di progetto, lo stack tecnologico e le regole sono sempre presenti quando l'AI crea artefatti. Affidabilità superiore.

Il compromesso:

Poiché il contesto viene iniettato in ogni richiesta, vorrai essere conciso. Concentrati su ciò che conta davvero:

  • Stack tecnologico e convenzioni chiave
  • Vincoli non ovvi che l'AI deve conoscere
  • Regole che venivano frequentemente ignorate in passato

Non preoccuparti di renderlo perfetto. Stiamo ancora imparando cosa funziona meglio e miglioreremo il funzionamento dell'iniezione del contesto man mano che sperimentiamo.

Esecuzione della Migrazione ​

Sia openspec init che openspec update rilevano i file legacy e ti guidano attraverso lo stesso processo di pulizia. Usa quello che si adatta alla tua situazione:

  • Le nuove installazioni impostano di default il profilo core (propose, explore, apply, update, sync, archive).
  • Le installazioni migrate preservano i tuoi workflow precedentemente installati scrivendo un profilo custom quando necessario.

Uso di openspec init ​

Esegui questo se vuoi aggiungere nuovi strumenti o riconfigurare quali strumenti sono configurati:

bash
openspec init

Il comando init rileva i file legacy e ti guida attraverso la pulizia:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Cosa succede quando rispondi sì:

  1. Le directory dei comandi slash legacy vengono rimosse
  2. I marker di OpenSpec vengono rimossi da CLAUDE.md, AGENTS.md, ecc. (il tuo contenuto resta)
  3. openspec/AGENTS.md viene eliminato
  4. Le nuove skills vengono installate in .claude/skills/
  5. openspec/config.yaml viene creato con uno schema predefinito

Uso di openspec update ​

Esegui questo se vuoi solo migrare e aggiornare i tuoi strumenti esistenti all'ultima versione:

bash
openspec update

Il comando update rileva e pulisce anche gli artefatti legacy, quindi aggiorna le skills/comandi generati per corrispondere al tuo profilo attuale e alle impostazioni di consegna.

Ambienti Non Interattivi / CI ​

Per migrazioni scriptate:

bash
openspec init --force --tools claude

Il flag --force salta i prompt e accetta automaticamente la pulizia.

Questo include la pulizia dei file prompt di Codex gestiti da OpenSpec nella directory globale dei prompt di Codex. La pulizia riguarda solo i nomi file legacy approvati da OpenSpec, li rimuove solo dopo che esistono le skills sostitutive .agents/skills/openspec-*, e preserva tutti gli altri file.

Migrazione da project.md a config.yaml ​

Il vecchio openspec/project.md era un file markdown libero per il contesto di progetto. Il nuovo openspec/config.yaml è strutturato e—criticamente—iniettato in ogni richiesta di pianificazione in modo che le tue convenzioni siano sempre presenti quando l'AI lavora.

Prima (project.md) ​

markdown
# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Dopo (config.yaml) ​

yaml
schema: spec-driven

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

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Differenze Chiave ​

project.mdconfig.yaml
Markdown liberoYAML strutturato
Un unico blocco di testoContesto separato e regole per artefatto
Non chiaro quando viene usatoIl contesto appare in TUTTI gli artefatti; le regole appaiono solo negli artefatti corrispondenti
Nessuna selezione dello schemaIl campo esplicito schema: imposta il workflow predefinito

Cosa Tenere, Cosa Scartare ​

Durante la migrazione, sii selettivo. Chiediti: "L'AI ha bisogno di questo per ogni richiesta di pianificazione?"

Buoni candidati per context:

  • Stack tecnologico (linguaggi, framework, database)
  • Pattern architetturali chiave (monorepo, microservizi, ecc.)
  • Vincoli non ovvi ("non possiamo usare la libreria X perché...")
  • Convenzioni critiche che vengono spesso ignorate

Sposta in rules:

  • Formattazione specifica per artefatto ("usa Given/When/Then nelle specifiche")
  • Criteri di revisione ("le proposte devono includere piani di rollback")
  • Queste appaiono solo per l'artefatto corrispondente, mantenendo le altre richieste più leggere

Escludi completamente

  • Buone pratiche generali che l'AI già conosce
  • Spiegazioni verbose che potrebbero essere riassunte
  • Contesto storico che non influenza il lavoro attuale

Passi di Migrazione ​

  1. Crea config.yaml (se non è già stato creato da init):

    yaml
    schema: spec-driven

  2. Aggiungi il tuo contesto (sii conciso—questo va in ogni richiesta):

    yaml
    context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.

  3. Aggiungi regole per artefatto (facoltativo):

    yaml
    rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

  4. Elimina project.md una volta spostato tutto ciò che è utile.

Non ragionare troppo. Inizia con l'essenziale e itera. Se noti l'AI che manca di qualcosa di importante, aggiungilo. Se il contesto sembra gonfiato, riducilo. Questo è un documento vivente.

Hai Bisogno di Aiuto? Usa Questo Prompt ​

Se non sei sicuro come distillare il tuo project.md, chiedi al tuo assistente AI:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

L'AI ti aiuterà a identificare cosa è essenziale e cosa può essere ridotto.

I Nuovi Comandi ​

La disponibilità dei comandi dipende dal profilo:

Predefinito (profilo core):

ComandoScopo
/opsx:proposeCrea una modifica e genera gli artefatti di pianificazione in un solo passo
/opsx:exploreRifletti su idee senza struttura
/opsx:applyImplementa i task da tasks.md
/opsx:updateRivedi gli artefatti di pianificazione di una modifica e mantienili coerenti
/opsx:syncUnisci le specifiche delta nelle specifiche principali
/opsx:archiveFinalizza e archivia la modifica

Workflow espanso (selezione personalizzata):

ComandoScopo
/opsx:newAvvia un nuovo scaffold di modifica
/opsx:continueCrea il prossimo artefatto (uno alla volta)
/opsx:ffFast-forward—crea gli artefatti di pianificazione in un colpo solo
/opsx:verifyConvalida che l'implementazione corrisponda alle specifiche
/opsx:bulk-archiveArchivia più modifiche in un colpo solo
/opsx:onboardWorkflow di onboarding guidato end-to-end

Abilita i comandi espansi con openspec config profile, quindi esegui openspec update.

Mappatura dei Comandi dal Legacy ​

LegacyEquivalente OPSX
/openspec:proposal/opsx:propose (predefinito) o /opsx:new seguito da /opsx:ff (espanso)
/openspec:apply/opsx:apply
/openspec:archive/opsx:archive

Nuove Capacità ​

Queste capacità fanno parte del set di comandi del workflow espanso.

Creazione granulare degli artefatti:

/opsx:continue

Crea un artefatto alla volta in base alle dipendenze. Usa questo quando vuoi rivedere ogni passo.

Modalità esplorazione:

/opsx:explore

Rifletti su idee con un partner prima di impegnarti in una modifica.

Comprendere la Nuova Architettura ​

Da Fasi Vincolate a Fluido ​

Il flusso di lavoro legacy imponeva una progressione lineare:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   FASE DI    │ ───► │   FASE DI    │ ───► │   FASE DI    │
│ PIANIFICAZIONE│      │IMPLEMENTAZIONE│      │ ARCHIVIAZIONE│
└──────────────┘      └──────────────┘      └──────────────┘

Se sei nella fase di implementazione e ti accorgi che il progetto è sbagliato?
Peccato. I gate di fase non ti permettono di tornare indietro facilmente.

OPSX usa azioni, non fasi:

         ┌───────────────────────────────────────────────┐
         │           AZIONI (non fasi)                   │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    qualsiasi ordine           │
         └───────────────────────────────────────────────┘

Grafo delle Dipendenze ​

Gli artefatti formano un grafo diretto. Le dipendenze sono abilitatori, non gate:

                        proposal
                       (nodo radice)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (richiede:                  (richiede:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (richiede:
                     specs, design)

Quando esegui /opsx:continue, controlla cosa è pronto e propone il prossimo artefatto. Puoi anche creare più artefatti pronti in qualsiasi ordine.

Skill vs Comandi ​

Il sistema legacy usava file di comando specifici per lo strumento:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX usa lo standard emergente delle skill:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Le skill sono riconosciute da più strumenti di coding AI e forniscono metadati più ricchi.

Codex in OPSX utilizza solo le skill. OpenSpec non genera più file di prompt personalizzati per Codex; utilizza invece le directory generate .agents/skills/openspec-*.

Continuare Modifiche Esistenti ​

Le tue modifiche in corso funzionano perfettamente con i comandi OPSX.

Hai una modifica attiva dal flusso di lavoro legacy?

/opsx:apply add-my-feature

OPSX legge gli artefatti esistenti e continua da dove eri rimasto.

Vuoi aggiungere altri artefatti a una modifica esistente?

/opsx:continue add-my-feature

Mostra cosa è pronto per essere creato in base a ciò che già esiste.

Hai bisogno di vedere lo stato?

bash
openspec status --change add-my-feature

Il Nuovo Sistema di Configurazione ​

Struttura di config.yaml ​

yaml
# Obbligatorio: Schema predefinito per nuove modifiche
schema: spec-driven

# Facoltativo: Contesto del progetto (max 50KB)
# Iniettato in TUTTE le istruzioni degli artefatti
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Facoltativo: Regole per artefatto
# Iniettato solo negli artefatti corrispondenti
rules:
  proposal:
    - Includi piano di rollback
  specs:
    - Usa il formato Given/When/Then
  design:
    - Documenta le strategie di fallback
  tasks:
    - Suddividi in blocchi massimi di 2 ore

Risoluzione dello Schema ​

Per determinare quale schema usare, OPSX controlla in ordine:

  1. Flag CLI: --schema <name> (priorità più alta)
  2. Metadati della modifica: .openspec.yaml nella directory della modifica
  3. Configurazione del progetto: openspec/config.yaml
  4. Predefinito: spec-driven

Schemi Disponibili ​

SchemaArtefattiIdeale per
spec-drivenproposal → specs → design → tasksLa maggior parte dei progetti

Elenca tutti gli schemi disponibili:

bash
openspec schemas

Schemi Personalizzati ​

Crea il tuo flusso di lavoro:

bash
openspec schema init my-workflow

Oppure fai un fork di uno esistente:

bash
openspec schema fork spec-driven my-workflow

Vedi Personalizzazione per i dettagli.

Risoluzione dei problemi ​

"File legacy rilevati in modalità non interattiva" ​

Stai eseguendo in un ambiente CI o non interattivo. Usa:

bash
openspec init --force

Comandi non visualizzati dopo la migrazione ​

Riavvia il tuo IDE. Le skill vengono rilevate all'avvio.

"ID artefatto sconosciuto nelle regole" ​

Verifica che le chiavi rules: corrispondano agli ID degli artefatti del tuo schema:

  • spec-driven: proposal, specs, design, tasks

Esegui questo per vedere gli ID degli artefatti validi:

bash
openspec schemas --json

Configurazione non applicata ​

  1. Assicurati che il file sia in openspec/config.yaml (non .yml)
  2. Convalida la sintassi YAML
  3. Le modifiche alla configurazione hanno effetto immediato, non è necessario riavviare

project.md non migrato ​

Il sistema conserva intenzionalmente project.md perché potrebbe contenere contenuti personalizzati. Esaminalo manualmente, sposta le parti utili in config.yaml, quindi eliminalo.

Vuoi vedere cosa verrebbe pulito? ​

Esegui init e rifiuta il prompt di pulizia: vedrai il riepilogo completo del rilevamento senza apportare alcuna modifica.

Riferimento Rapido ​

File Dopo la Migrazione ​

project/
├── openspec/
│   ├── specs/                    # Invariato
│   ├── changes/                  # Invariato
│   │   └── archive/              # Invariato
│   └── config.yaml               # NUOVO: Configurazione del progetto
├── .claude/
│   └── skills/                   # NUOVO: Skill OPSX
│       ├── openspec-propose/     # profilo core predefinito
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # profilo esteso aggiunge new/continue/ff/ecc.
├── CLAUDE.md                     # Marcatori OpenSpec rimossi, il tuo contenuto preservato
└── AGENTS.md                     # Marcatori OpenSpec rimossi, il tuo contenuto preservato

Cosa è Scomparso ​

  • .claude/commands/openspec/ — sostituito da .claude/skills/
  • openspec/AGENTS.md — obsoleto
  • openspec/project.md — migra a config.yaml, quindi elimina
  • Blocchi marcatori OpenSpec in CLAUDE.md, AGENTS.md, ecc.

Cheatsheet dei Comandi ​

text
/opsx:propose      Avvia rapidamente (profilo core predefinito)
/opsx:apply        Implementa i task
/opsx:archive      Completa e archivia

# Flusso di lavoro esteso (se abilitato):
/opsx:new          Crea lo scheletro di una modifica
/opsx:continue     Crea l'artefatto successivo
/opsx:ff           Crea artefatti di pianificazione

Ottenere Aiuto ​