Risoluzione dei problemi

Soluzioni concrete per problemi concreti. Ogni voce indica un sintomo, ne spiega la causa probabile in una frase e fornisce la soluzione. Se non trovi il tuo problema qui, la FAQ potrebbe esserti utile, e il Discord sicuramente sì.

Installazione e configurazione

openspec: command not found

La CLI non è installata o il tuo shell non riesce a trovarla. Installala globalmente e verifica:

npm install -g @fission-ai/openspec@latest
openspec --version

Se è stata installata ma continua a non essere trovata, probabilmente la directory bin globale di npm non è presente nel tuo PATH. Esegui npm prefix -g per vedere dove si trovano i pacchetti globali: su macOS e Linux i binari si trovano nella sottodirectory bin/ di tale directory, mentre su Windows risiedono direttamente al suo interno. Assicurati che questo percorso sia incluso nel tuo PATH. (npm bin -g è stato rimosso in npm 9.)

Se hai utilizzato l'installazione assistita dall'AI, questo è il punto previsto per il passaggio di consegne: quel prompt istruisce il tuo assistente a mostrarti la modifica al PATH invece di modificare direttamente i file di avvio del tuo shell.

"Requires Node.js 20.19.0 or higher"

OpenSpec richiede Node 20.19.0 o versioni successive. Verifica la tua versione ed effettua l'aggiornamento se necessario:

node --version

Se utilizzi bun per installare OpenSpec, tieni presente che OpenSpec esegue comunque su Node, quindi devi avere Node 20.19.0+ disponibile nel tuo PATH, indipendentemente da tutto. Vedi Installazione.

openspec init non ha configurato il mio strumento AI

Init chiede quali strumenti configurare. Se hai saltato il tuo strumento o vuoi aggiungerne un altro, eseguilo di nuovo, oppure usa la forma non interattiva:

openspec init --tools claude,cursor

L'elenco completo degli ID degli strumenti è disponibile in Strumenti supportati. Usa --tools all per tutto, --tools none per saltare la configurazione degli strumenti.

I comandi non vengono visualizzati

Se /opsx:propose (o l'equivalente del tuo strumento) non appare o non fa nulla, procedi con questa lista. Sono ordinate dalla verifica più rapida a quella più lenta.

1. Potresti essere nel posto sbagliato. I comandi slash vanno inseriti nella chat del tuo assistente AI, non nel terminale. Se hai digitato /opsx:propose nel tuo shell, questo è il problema. Vedi Come funzionano i comandi.

2. Rigenera i file. Dalla radice del tuo progetto:

   openspec update

   Questo riscrive i file delle skill e dei comandi per ogni strumento che hai configurato.

   I file di istruzioni provengono dalla CLI installata, quindi una CLI obsoleta segnalerà tutto come aggiornato senza mai scrivere i flussi di lavoro più recenti. openspec update ora controlla anche questo e offre di effettuare l'aggiornamento: accetta l'offerta se la vedi.

3. Riavvia il tuo assistente. La maggior parte degli strumenti scansiona le skill e i comandi all'avvio. Una nuova finestra spesso basta.

4. Conferma che i file esistano. Per Claude Code, verifica che .claude/skills/ contenga cartelle openspec-*. Altri strumenti utilizzano le proprie directory, tutte elencate in Strumenti supportati.

5. Verifica di aver inizializzato questo progetto. Le skill sono scritte per progetto. Se hai clonato un repository o cambiato cartella, esegui openspec init (o openspec update) lì.

6. Conferma che il tuo strumento supporti i file di comando. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent e il target condiviso .agents non generano file di comando opsx-*; utilizzano invece invocazioni basate sulle skill, quindi /opsx non verrà mai completato automaticamente per loro. Digita $openspec-propose in Codex, /skill:openspec-propose in Kimi Code e /openspec-propose negli altri. Il target condiviso .agents è indipendente dal fornitore, quindi /openspec-propose è la forma comune piuttosto che garantita: se il tuo assistente non risponde ad essa, consulta la sua documentazione per capire come invoca una skill. Amazon Q riceve file di comando, ma li carica nella sua libreria di prompt piuttosto che nel menu slash: digita @opsx-propose lì, non /opsx. La forma di ogni strumento è elencata in Come invocare.

Lavorare con le modifiche

"Change not found"

Il comando non è riuscito a determinare a quale modifica ti riferivi. Nominala esplicitamente, oppure controlla cosa esiste:

openspec list                    # vede le modifiche attive
/opsx:apply add-dark-mode        # nomina la modifica nella chat

Conferma inoltre di trovarti nella directory corretta del progetto.

"No artifacts ready"

Ogni artefatto è già stato creato o è bloccato in attesa di una dipendenza. Vedi cosa sta bloccando:

openspec status --change <name>

Quindi crea prima la dipendenza mancante. Ricorda l'ordine: la proposal abilita specs e design; specs e design insieme abilitano tasks.

openspec validate segnala warning o errori

La validazione controlla le tue specs e le modifiche per problemi strutturali. Leggi il messaggio: indica il file e il problema.

openspec validate <name>           # valida un singolo elemento
openspec validate --all            # valida tutto
openspec validate --all --strict   # controlli più rigorosi, utili per CI
openspec validate --archived       # fallisce se le modifiche archiviate hanno task non verificati

Le cause comuni sono una sezione richiesta mancante (come una spec senza scenari) o un'intestazione delta malformata. Correggi il file ed esegui di nuovo. Il riferimento alla CLI documenta il formato dell'output.

Un messaggio merita una nota a parte:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Una requirement MODIFIED sostituisce l'intero blocco della requirement, quindi deve contenere tutti gli scenari che sopravvivono alla modifica, non solo quelli che hai modificato. Copia gli scenari nominati da openspec/specs/<capability-path>/spec.md nuovamente nel delta, preservando eventuali directory di dominio nel percorso. Questo appare spesso su una modifica precedente dopo che la modifica di qualcun altro ha aggiunto uno scenario alla stessa requirement — l'archiviazione rifiuta quella modifica in ogni caso, e la validazione ora lo segnala prima che tu la implementi.

L'AI ha creato artefatti incompleti o errati

L'AI non aveva abbastanza contesto. Alcuni leve aiutano:

• Aggiungi contesto del progetto in openspec/config.yaml affinché il tuo stack e le tue convenzioni vengano iniettati in ogni richiesta. Vedi Personalizzazione.
• Aggiungi rules: per artefatto per indicazioni che si applicano solo, ad esempio, alle specs.
• Fornisci una descrizione più dettagliata quando proponi.
• Usa /opsx:continue esteso per creare un artefatto alla volta e revisionarlo, invece di usare /opsx:ff per farli tutti in una volta.

L'archiviazione non termina o segnala warning su task incompleti

L'archiviazione non blocca su task incompleti, ma ti avvisa, perché di solito archiviare significa che il lavoro è finito. Se i task rimangono intenzionalmente (stai registrando una modifica parziale), procedi. Altrimenti completa prima i task. L'archiviazione offrirà anche di sincronizzare le tue specs delta nelle specs principali se non le hai ancora sincronizzate; dì di sì a meno che tu non abbia una ragione per non farlo.

"User force closed the prompt with 0 null"

Qualcosa ha eseguito openspec archive dove nulla può rispondere a una domanda: un agente AI che lo chiama da uno strumento, un job CI o qualsiasi shell con stdin chiuso. Archive chiede fino a tre conferme, e una non rispondibile in passato falliva con quel messaggio grezzo.

Passa --yes per rispondere subito:

openspec archive <change-name> --yes

Mantieni qualsiasi flag stavi già passando — --skip-specs e --no-validate cambiano ciò che archive fa, quindi una riesecuzione con solo --yes non è lo stesso comando. Le versioni attuali indicano il nome del flag per te e stampano una riga Fix: che puoi incollare. Se intendevi scegliere da un elenco, passa esplicitamente il nome della modifica: il picker ha bisogno di una risposta anch'esso.

Se invece hai eseguito archive reindirizzando il suo output su un file o catturandolo da uno strumento e hai inviato una risposta (printf 'y\n' | openspec archive …), le versioni precedenti scrivevano codici di escape del terminale in quella cattura durante il disegno del prompt — in alcuni ambienti abbastanza da gonfiare pesantemente il file. Le versioni attuali leggono i prompt di conferma come testo normale quando stdout non è un terminale, e un openspec archive senza argomenti (che altrimenti disegnerebbe un picker di modifiche interattivo) ti chiede di passare un nome di modifica subito invece di renderizzare un menu nella cattura. In entrambi i casi, le esecuzioni reindirizzate e degli agenti restano pulite; passare --yes (con un nome di modifica) salta completamente i prompt.

Configurazione

Il mio config.yaml non viene applicato

Tre sospitati abituali:

1. Nome file errato. Deve essere openspec/config.yaml, non .yml.
2. YAML non valido. Passalo attraverso qualsiasi validatore YAML; la CLI segnala anche errori di sintassi con i numeri di riga.
3. Ti aspettavi un riavvio. Non ne hai bisogno. Le modifiche alla configurazione hanno effetto immediato.

"Unknown artifact ID in rules: X"

Una chiave sotto rules: non corrisponde ad alcun artefatto nel tuo schema. Per lo schema predefinito spec-driven gli ID validi sono proposal, specs, design, tasks. Per vedere gli ID per qualsiasi schema:

openspec schemas --json

"Context too large"

Il campo context: è limitato a 50KB, volutamente, perché viene iniettato in ogni richiesta. Riassumilo, oppure linka a documenti più lunghi invece di incollarli. Un contesto snello produce anche risultati migliori e più veloci.

"Schema not found"

Il nome dello schema che hai referenziato non esiste. Elencati cosa è disponibile e controlla l'ortografia:

openspec schemas                    # elenca gli schemi disponibili
openspec schema which <name>        # vedi da dove si risolve uno schema
openspec schema init <name>         # creane uno personalizzato

Vedi Personalizzazione.

Migrazione dal flusso di lavoro legacy

"Legacy files detected in non-interactive mode"

Sei in CI o in una shell non interattiva, e OpenSpec ha trovato vecchi file da pulire ma non può chiedertelo. Approva automaticamente:

openspec init --force

Per Codex, OpenSpec potrebbe rilevare vecchi file prompt gestiti in $CODEX_HOME/prompts o ~/.codex/prompts. Questa pulizia è limitata ai nomi dei file prompt legacy di Codex nella whitelist di OpenSpec, e openspec init non interattivo rimuove solo i file le cui skill di sostituzione .agents/skills/openspec-* esistono. openspec update non interattivo lascia intatta tutta la pulizia legacy a meno che tu non passi --force.

I comandi non sono apparsi dopo la migrazione

Riavvia il tuo IDE. Le skill vengono rilevate all'avvio. Se continuano a non apparire, esegui openspec update e controlla le posizioni dei file in Strumenti supportati.

La mia vecchia project.md non è stata migrata

È intenzionale. OpenSpec non elimina mai project.md automaticamente perché potrebbe contenere contesto che hai scritto. Sposta le parti utili nella sezione context: di config.yaml, poi eliminatela tu stesso. La Guida alla migrazione illustra questo processo, incluso un prompt che puoi dare alla tua AI per fare il distillaggio.

Ancora bloccato?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Dal tuo terminale: openspec feedback "what went wrong" apre un issue per te.

Quando segnali un problema, includi la tua versione di OpenSpec (openspec --version), la tua versione di Node (node --version), il tuo strumento AI e il comando e l'output esatti. Rende l'aiuto molto più veloce.