FAQ

Risposte rapide alle domande più comuni. Se la tua domanda riguarda in realtà "qualcosa non funziona", la pagina Risoluzione dei problemi è più adatta. Se vuoi la definizione di un termine, consulta il Glossario.

Le basi

Cos'è OpenSpec, in una frase?

Un livello leggero che permette a te e al tuo assistente di codifica AI di concordare su cosa costruire, per iscritto, prima che venga scritto qualsiasi codice.

Perché dovrei volerlo?

Perché gli assistenti AI sono sicuri di sé anche quando sbagliano. Quando i requisiti vivono solo in una conversazione di chat, l'AI colma le lacune con congetture e te ne accorgi solo dopo che il codice esiste. OpenSpec anticipa l'accordo, dove gli errori sono economici da correggere. Vedi Concetti fondamentali in sintesi per l'argomentazione completa.

Devo usarlo per tutto?

No. Usalo dove l'accordo è importante, cioè nella maggior parte dei lavori non banali. Per la correzione di un errore di battitura di un carattere, la procedura probabilmente non vale la pena, e va bene così.

Posso usarlo su un grande codebase esistente, o solo su nuovi progetti?

I codebase esistenti sono l'evento principale. OpenSpec è pensato principalmente per progetti esistenti (brownfield): non devi documentare l'intera applicazione in anticipo. Scrivi specifiche solo per ciò che ogni modifica tocca, e le tue specifiche si completano nel tempo attorno al lavoro che effettivamente svolgi. Esiste una guida dedicata: Usare OpenSpec in un progetto esistente.

È legato a un unico strumento AI?

No. OpenSpec funziona con più di 30 assistenti, tra cui Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex e altri. L'elenco completo e i dettagli per ogni strumento sono in Strumenti supportati.

Esecuzione dei comandi

Dove digito /opsx:propose?

Nella chat del tuo assistente AI, non nel terminale. Questo è il punto di confusione più comune, quindi ha una pagina dedicata: Come funzionano i comandi. Versione breve: openspec ... si esegue nel terminale, /opsx:... si esegue in chat.

Come faccio ad "avviare la modalità interattiva"?

Non esiste una modalità separata da avviare. Apri il tuo assistente AI come al solito e digita un comando slash nella sua chat. Il comando slash è il modo in cui "entri" in OpenSpec. (L'unica funzionalità terminale realmente interattiva è openspec view, una dashboard per navigare tra specifiche e modifiche.) Spiegazione completa in Come funzionano i comandi.

Ho digitato un comando slash e non è successo nulla. Perché?

Molto probabilmente l'hai digitato nel terminale invece che nella chat AI, hai usato una grafia che il tuo strumento non riconosce, oppure i comandi non sono ancora installati. Se i file mancano — o non hai mai configurato lo strumento — esegui openspec init; openspec update aggiorna solo file che già esistono. Poi riavvia il tuo assistente e usa il formato stampato sotto "Getting started" — vedi Come invocare. Risoluzione dei problemi contiene la checklist completa.

Perché la sintassi è /opsx:propose in uno strumento e /opsx-propose in un altro?

Ogni strumento AI presenta i comandi personalizzati in modo leggermente diverso, e OpenSpec li scrive nel modo in cui il tuo strumento carica il file che ha creato. Un file di comando chiamato opsx-propose.md si digita /opsx-propose; uno archiviato in commands/opsx/ si digita /opsx:propose. Gli strumenti che usano skill invece di comandi usano il nome della skill — Codex richiede $openspec-propose, Kimi Code /skill:openspec-propose. La riga "Getting started" di openspec init stampa già il formato corretto per gli strumenti che hai scelto; la tabella completa è in Come invocare.

Qual è la differenza tra una skill e un comando?

Entrambi sono file che OpenSpec scrive affinché il tuo assistente possa eseguire il flusso di lavoro. Le skill (.../skills/openspec-*/SKILL.md) sono lo standard più recente e multipiattaforma; i comandi (.../commands/opsx-*) sono i vecchi file slash specifici per strumento. Non devi scegliere. Devi solo digitare il comando slash, e OpenSpec installa ciò che il tuo strumento utilizza.

Il flusso di lavoro

Da dove dovrei iniziare se non sono sicuro di cosa costruire?

Con /opsx:explore. È un partner di riflessione senza rischi che legge il tuo codebase, presenta le opzioni e trasforma un problema vago in un piano concreto, il tutto prima che esista qualsiasi modifica o codice. È nel profilo predefinito, quindi è sempre disponibile. Quando il piano è chiaro, passa il testimone a /opsx:propose. Questa è la migliore abitudine da formare, perché impedisce a un'AI troppo zelante di costruire con sicurezza la cosa sbagliata. Vedi Esplora prima.

Qual è il flusso più semplice possibile?

/opsx:explore (opzionale)   poi   /opsx:propose <cosa vuoi>   poi   /opsx:apply   poi   /opsx:archive

Esplora per riflettere, proponi per abbozzare il piano, applica per costruirlo, archivia per metterlo da parte. Salta explore quando sai già esattamente cosa vuoi.

Qual è la differenza tra /opsx:propose e /opsx:new?

/opsx:propose è il comando predefinito in un unico passaggio: crea la modifica e abbozza tutti gli artefatti di pianificazione in una volta sola. /opsx:new fa parte del set di comandi esteso e crea solo una modifica vuota, lasciando a te la creazione degli artefatti uno alla volta con /opsx:continue (o tutti insieme con /opsx:ff). Usa propose a meno che tu non voglia un controllo passo-passo. Vedi Comandi.

Cosa sono i profili core ed espanso?

Un profilo determina quali comandi slash vengono installati. Core (quello predefinito) ti offre propose, explore, apply, update, sync, archive. Il set espanso aggiunge new, continue, ff, verify, bulk-archive e onboard per un controllo più fine. Passa da uno all'altro con openspec config profile, poi applica con openspec update.

Devo eseguire /opsx:sync?

Di solito no. Sync unisce le specifiche delta di una modifica nelle tue specifiche principali, e /opsx:archive ti offrirà di farlo al posto tuo. Esegui sync manualmente solo quando vuoi che le specifiche vengano unite prima dell'archiviazione, ad esempio in una modifica di lunga durata. Vedi Comandi.

Come posso modificare una proposta, una specifica o un'attività dopo aver iniziato?

Basta modificare il file. Ogni artefatto è semplice Markdown in openspec/changes/<nome>/, e non esiste una fase bloccata o una modalità di modifica speciale. Modificalo a mano, oppure chiedi alla tua AI di rivederlo ("aggiorna il design per usare una coda"), poi continua. L'AI lavora sempre a partire dal contenuto attuale del file. Guida completa: Modificare e iterare su una modifica.

Posso tornare indietro e cambiare il piano dopo aver implementato parte di esso?

Sì, in qualsiasi momento. Il flusso di lavoro è fluido, quindi revisione e modifica non sono fasi da cui vieni escluso. Modifica l'artefatto, poi continua. Se vuoi una verifica strutturata che il codice corrisponda ancora al piano, esegui /opsx:verify. Vedi Modificare e iterare su una modifica.

Ho modificato il codice a mano. Come lo riconcilio con la specifica?

Riportali in sincronia prima di archiviare, poiché l'archiviazione rende le tue specifiche la fonte di verità. Se il codice ora è corretto, aggiorna la specifica delta per riflettere ciò che hai rilasciato; se la specifica è corretta, continua a sviluppare finché il codice non concorda. /opsx:verify evidenzia le discrepanze. Vedi Modificare e iterare su una modifica.

Quando dovrei aggiornare una modifica esistente invece di crearne una nuova?

Aggiorna quando è lo stesso lavoro, raffinato. Inizia da zero quando l'intento è cambiato fondamentalmente o l'ambito è esploso in un lavoro diverso. C'è un diagramma di flusso decisionale ed esempi in Flussi di lavoro.

Cosa succede se la mia sessione esaurisce il contesto, o i requisiti cambiano a metà implementazione?

È qui che le specifiche dimostrano il loro valore. Poiché il piano vive in file (non solo nella cronologia della chat), puoi cancellare il contesto, avviare una nuova sessione AI e riprendere con /opsx:apply; legge gli artefatti e riprende dal primo task non verificato. Se i requisiti cambiano, modifica gli artefatti per riflettere la nuova realtà e continua. Mantenere pulita la finestra di contesto produce anche risultati migliori; cancellala prima dell'implementazione.

Dovrei committare la cartella openspec/ in git?

Sì. Le tue specifiche, le modifiche attive e l'archivio fanno parte della storia del tuo progetto. Committali come qualsiasi altro sorgente. In particolare, l'archivio diventa una registrazione duratura del motivo per cui il tuo sistema funziona nel modo in cui funziona.

Specifiche e modifiche

Cosa va in una specifica rispetto a un design?

Una specifica descrive il comportamento osservabile: cosa fa il sistema, i suoi input, output e condizioni di errore. Un design descrive come lo costruirai: l'approccio tecnico, le decisioni architetturali, le modifiche ai file. Se l'implementazione potrebbe cambiare senza modificare il comportamento esternamente visibile, appartiene al design, non alla specifica. Concetti approfondisce.

Cos'è una specifica delta?

Una specifica che descrive solo ciò che sta cambiando, usando sezioni ADDED, MODIFIED e REMOVED, invece di riscrivere l'intera specifica. È il modo in cui OpenSpec gestisce in modo pulito le modifiche ai sistemi esistenti. Vedi Concetti.

Dove vanno le modifiche archiviate?

In openspec/changes/archive/YYYY-MM-DD-<nome>/, con tutti gli artefatti della modifica preservati. La modifica esce dall'elenco delle modifiche attive. Una modifica che dichiara esplicitamente retire_capabilities: true può anche eliminare una specifica di capacità principale quando rimuove l'ultimo requisito di quella capacità.

Configurazione e personalizzazione

Come comunico all'AI il mio stack tecnologico?

Inseriscilo in openspec/config.yaml sotto context:. Quel testo viene iniettato in ogni richiesta di pianificazione, quindi l'AI conosce sempre il tuo stack e le tue convenzioni. Vedi Personalizzazione.

Posso generare specifiche in una lingua diversa dall'inglese?

Sì. Aggiungi un'istruzione sulla lingua al context: della tua configurazione. Multilingua contiene frammenti copia-incolla per diverse lingue.

Posso cambiare il flusso di lavoro stesso?

Sì, con schemi personalizzati. Uno schema definisce quali artefatti esistono e come dipendono l'uno dall'altro. Crea un fork dello schema predefinito con openspec schema fork spec-driven my-workflow, poi modificalo. Vedi Personalizzazione.

Modelli, privacy e aggiornamenti

Quale modello AI dovrei usare?

OpenSpec funziona al meglio con modelli ad alta capacità di ragionamento. Il README raccomanda modelli come Codex 5.5 e Opus 4.7 sia per la pianificazione che per l'implementazione. Mantieni anche pulita la finestra di contesto: cancellala prima dell'implementazione per ottenere risultati migliori.

OpenSpec raccoglie dati?

Raccoglie statistiche di utilizzo anonime: solo nomi dei comandi e versione. Nessun argomento, percorso, contenuto o dato personale, ed è disattivato automaticamente nella CI. Puoi disattivarlo con export OPENSPEC_TELEMETRY=0 o export DO_NOT_TRACK=1.

Come si aggiorna?

Due passaggi. Aggiorna il pacchetto (npm install -g @fission-ai/openspec@latest), poi esegui openspec update all'interno di ogni progetto per aggiornare le skill e i comandi generati.

Come disinstallo OpenSpec?

Non esiste un comando di disinstallazione, perché è solo un pacchetto globale più file nel tuo progetto. Rimuovi il pacchetto (npm uninstall -g @fission-ai/openspec) e, facoltativamente, elimina la directory openspec/ e i file degli strumenti generati. La procedura passo-passo, incluso ciò che è sicuro conservare, è in Installazione: Disinstallazione.

Ottenere aiuto

Dove posso fare domande o segnalare bug?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Dal tuo terminale: openspec feedback "il tuo messaggio" apre una issue GitHub per te.

Questa documentazione è sbagliata o confusa. Cosa faccio?

Diccelo, o correggila. Le PR di documentazione sono benvenute e apprezzate. Apri una issue o invia una pull request.