Configura il tuo progetto

Aggiungi OpenSpec a un progetto: esegui init, guarda cosa ha scritto e modificalo.

Scegli dove risiede OpenSpec

• Nel tuo repository (impostazione predefinita): le specifiche e le modifiche si trovano accanto al codice che descrivono e ne condividono il versionamento. Il resto di questa pagina segue questo percorso.
• In uno store: un repository di pianificazione separato condiviso dai repository che lo utilizzano, per configurazioni multi-repo o per tenere la pianificazione completamente fuori dal repository. Store (beta) spiega quando vale la pena e come configurarlo.

Inizializza il tuo progetto

Con la CLI installata (Installazione), esegui init alla radice del tuo progetto. Nel tuo terminale:

cd <your-project>
openspec init

Init chiede quali strumenti AI utilizzi, scrive i file di workflow per quelli selezionati e riporta cosa hai ottenuto:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Riavvia il tuo IDE affinché i nuovi comandi abbiano effetto.

Rieseguire init è sicuro:

• Gli strumenti già configurati stampano Refreshed invece di Created.
• Eseguendo nuovamente init con un nuovo strumento selezionato, quest'ultimo viene aggiunto.
• Il flag --tools salta il selettore (Riferimento CLI).

Migrare un project.md esistente

Init non copia il legacy openspec/project.md in config.yaml. Mantiene il file e stampa una richiesta di migrazione assistita da AI.

Nella tua chat AI:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Rivedi config.yaml, quindi elimina project.md quando sei pronto.

Cosa installa init

L'esecuzione di init crea due cose nel tuo progetto:

• Una cartella openspec/ alla radice del repository
• File di workflow (skill e comandi) aggiunti alla cartella del tuo strumento AI (.agents/, .claude/, ecc.)

Esegui il commit di tutto come del resto del tuo codice sorgente. Init non modifica null'altro nel tuo repository (se trova residui di una versione precedente di OpenSpec, chiede prima di rimuoverli).

La cartella openspec/

Ogni artifact di OpenSpec risiede qui, alla radice del tuo progetto. Ecco l'aspetto:

openspec/
├── config.yaml     impostazioni del progetto e contesto per l'AI
├── specs/          le tue specifiche (vuote per ora)
└── changes/        modifiche in corso (vuote per ora)
    └── archive/    le modifiche completate vengono spostate qui

Configurazione del progetto copre config.yaml.

I file di workflow (skill e comandi)

Questi sono i workflow di OpenSpec, le azioni che utilizzerai durante il lavoro. Ecco come sono installati come skill, nella cartella condivisa .agents/ usata dalla maggior parte degli strumenti:

.agents/skills/
├── openspec-explore/              elabora prima un'idea
├── openspec-propose/              proponi una modifica
├── openspec-apply-change/         implementa le attività di una modifica
├── openspec-update-change/        rivedi il piano di una modifica
├── openspec-sync-specs/           sincronizza gli aggiornamenti delle specifiche di una modifica in specs/
├── openspec-archive-change/       sposta una modifica terminata nell'archivio
├── openspec-verify-change/        verifica che l'implementazione corrisponda al piano (non incluso per impostazione predefinita)
└── openspec-bulk-archive-change/  archivia diverse modifiche contemporaneamente (non incluso per impostazione predefinita)

Questo è il set predefinito più due workflow opzionali. Profili elenca tutti i dodici.

Per impostazione predefinita ogni workflow viene installato in due forme:

• Skill (openspec-apply-change): istruzioni che il tuo agente acquisisce da solo quando chiedi il lavoro.
• Comando (/opsx:apply in Claude Code): un punto di ingresso digitato per lo stesso workflow, con un nome più breve.

I due sono funzionalmente identici. Lo skill e il comando di un workflow contengono le stesse istruzioni.

Perché due: i comandi sono arrivati primi, e ogni strumento li scrive a modo suo. Gli skill sono lo standard più recente condiviso tra gli strumenti, ma non tutti gli strumenti possono invocare uno skill direttamente, quindi i comandi restano come punto di ingresso per quegli strumenti.

Alcuni strumenti si installano solo in forma di skill. Dove lo strumento esegue gli skill direttamente, init salta i comandi e lo indica (Commands skipped for: codex (uses skills)).

Preferiamo gli skill e prevediamo di ritirare i comandi nel tempo.

Cambiare ciò che viene installato

Il selettore interattivo modifica la forma di consegna e il set di workflow (Profili). Nel tuo terminale:

openspec config profile

Ecco come passare ai soli skill:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Rispondendo sì, viene applicato immediatamente al progetto corrente. Gli altri progetti lo riceveranno al loro prossimo openspec update. L'impostazione è globale, per macchina.

Claude Code non mostra i workflow

Claude Code carica i workflow di OpenSpec da uno o entrambi questi percorsi del progetto, in base all'impostazione di consegna:

• Skill: .claude/skills/openspec-*/SKILL.md
• Comandi: .claude/commands/opsx/<id>.md

Se i file mancano, aggiorna il progetto. Nel tuo terminale:

openspec update

Se i file di comando esistono ma /opsx: non mostra i comandi OpenSpec, aggiorna Claude Code e riavvialo. Se i comandi ancora non si caricano, abilita anche gli skill. Nel tuo terminale:

openspec config set delivery both
openspec update

Riavvia Claude Code, quindi esegui /openspec-propose nella sua chat. Se mancano solo alcuni workflow, modifica il tuo profilo.

La configurazione è completata. Il Quickstart ti guida nella tua prima modifica da qui.