OpenSpec Quickstart: installazione, flusso di lavoro e errori comuni

Specifiche come delta, non una PRD di 40 pagine.

Indice

OpenSpec è un CLI gratuito e open source di Fission AI che permette a te e al tuo agente di codifica di accordarvi su una modifica in Markdown semplice prima che vengano scritti codici, senza la cerimonia con fasi rigide dei framework spec-driven più pesanti.

La maggior parte dei team che prova lo Spec-Driven Development si blocca sullo stesso compromesso: abbastanza processo da impedire all’agente di indovinare, ma senza così tanto impalcatura che una modifica di bug di cinquantaine di righe richieda un documento di proposta. La risposta di OpenSpec è di saltare completamente l’istinto di “documentare prima l’intero sistema” e scrivere specifiche solo per ciò che una modifica tocca effettivamente, utilizzando delta ADDED, MODIFIED e REMOVED invece di un riscrittura completa ogni volta.

Flusso di lavoro spec-driven development di OpenSpec con un assistente di codifica AI

Questo design centrato sulla modifica è anche il motivo per cui OpenSpec continua a comparire accanto a GitHub Spec Kit, Kiro e Superpowers nel confronto delle categorie di strumenti SDD – è solitamente la scelta quando un team vuole specifiche revisionabili senza una fase di pianificazione di 800 righe. Questa guida copre l’installazione del CLI, il flusso di lavoro a quattro comandi che si usa effettivamente ogni giorno, come appare una modifica sul disco e le domande e le lamentele che emergono più spesso su Reddit e nel tracker di issue di OpenSpec stesso.

Cos’è OpenSpec?

OpenSpec descrive la propria filosofia in quattro righe: fluido e non rigido, iterativo e non waterfall, semplice e non complesso, costruito per brownfield e non solo greenfield. In pratica significa che non ci sono fasi bloccate: puoi modificare una proposta, una specifica o un elenco di attività in qualsiasi punto di una modifica, invece di essere costretto a seguire specifiche-poi-pianifica-poi-implementa in ordine rigoroso come descritto dal flusso di lavoro SDD tool-neutral.

Una modifica in OpenSpec produce fino a quattro artefatti Markdown nella propria cartella:

Artefatto Scopo
proposal.md Perché la modifica esiste e cosa cambia, in linguaggio semplice
specs/ Requisiti e scenari delta – la specifica testabile per questa modifica
design.md Approccio tecnico opzionale, per modifiche che ne hanno bisogno
tasks.md L’elenco di controllo di implementazione su cui l’agente lavora

Una volta che una modifica è implementata e archiviata, le sue specifiche delta si fondono in openspec/specs/, che diventa la descrizione durevole e dello stato attuale del tuo sistema – la stessa idea di “specifica come fonte di verità” coperta in Cos’è lo Spec-Driven Development?, ma limitata a una modifica alla volta invece di essere scritta tutta in una volta.

Installazione di OpenSpec

OpenSpec è un CLI Node.js, quindi hai bisogno di Node 20.19.0 o successivo sul tuo computer.

node --version

Installa il CLI globalmente con npm, quindi verifica che sia stato inserito nel tuo PATH:

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

Deno, pnpm, yarn, bun e nix sono anche percorsi di installazione supportati se si adattano meglio al tuo setup di npm. Una volta installato, inizializzalo all’interno di un progetto:

cd your-project
openspec init

openspec init chiede quali strumenti AI usi e scrive i file di skill e comandi corrispondenti – OpenSpec supporta oltre 30 assistenti, incluso Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro e OpenCode. Per CI o configurazione scriptata, saltare completamente il selettore:

openspec init --tools claude,cursor   # configura strumenti specifici
openspec init --tools all             # tutti gli strumenti supportati
openspec init --tools none            # solo struttura openspec/, nessun file di strumenti

Riavvia il tuo IDE in seguito in modo da rilevare le skill e i comandi appena scritti. Se preferisci che il tuo assistente faccia tutta l’installazione per te, OpenSpec include un prompt di configurazione che puoi incollare in Claude Code o un altro agente, che esegue l’installazione, esegue openspec init e riporta cosa ha configurato.

Il Flusso di Lavoro Principale: Esplora, Proponi, Applica, Archivia

Questa è l’unica cosa che fa inciampare quasi tutti al primo giorno: i comandi openspec vengono eseguiti nel terminale, ma i comandi /opsx: vengono eseguiti nella finestra chat del tuo assistente AI. Non c’è una separata “modalità interattiva” da entrare – digitare il comando slash nella chat è il modo per iniziare.

flowchart LR A["/opsx:explore (opzionale)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore è un partner di pensiero senza rischi. Legge la parte rilevante della tua codebase, espone le opzioni e modella un piano prima che venga scritto qualcosa sul disco – vale la pena formarne l’abitudine specificamente perché impedisce a un agente entusiasta di costruire con sicurezza la cosa sbagliata.
  • /opsx:propose <name> crea openspec/changes/<name>/ e redige la proposta, le specifiche delta, il design opzionale e l’elenco dei task in un’unica fase. Qui revisioni il piano, prima che l’implementazione inizi.
  • /opsx:apply lavora attraverso l’elenco dei task, spuntando gli elementi man mano che avanza. Poiché i progressi vivono nei file e non solo nella cronologia della chat, puoi cancellare la finestra di contesto o avviare una nuova sessione e riprendere esattamente da dove /opsx:apply si era fermato.
  • /opsx:archive archivia la modifica completata in openspec/changes/archive/YYYY-MM-DD-<name>/ e fonde le sue specifiche delta nell’albero canonico openspec/specs/.

Il profilo core predefinito installa esattamente quei quattro comandi più update e sync. Un profilo espanso aggiunge new, continue, ff, verify, bulk-archive e onboard per team che vogliono creare un artefatto alla volta invece di tutti insieme – passaci con openspec config profile seguito da openspec update.

Ogni strumento ortografia il comando in modo diverso a seconda di come carica le istruzioni personalizzate: /opsx:propose in Claude Code, /opsx-propose in Cursor e GitHub Copilot, @opsx-propose in Amazon Q, o $openspec-propose in Codex. openspec init stampa la forma esatta per gli strumenti che hai scelto, quindi la correzione più veloce per “niente è successo quando ho digitato il comando” è di solito rileggere quell’hint stampato invece di indovinare.

Come appare una modifica sul disco

Una cartella di modifica sotto openspec/changes/add-dark-mode/ contiene tipicamente una proposta, una specifica delta e un elenco di task come questo:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Questo formato delta ADDED/MODIFIED/REMOVED è il meccanismo che permette a OpenSpec di evitare di riscrivere un intero file di specifica per una modifica di un singolo campo. È anche il motivo per cui OpenSpec è esplicitamente brownfield-first piuttosto che greenfield-first: non documenti mai la tua intera applicazione prima di ottenere valore, documenti solo la fetta che ogni modifica reale tocca, e openspec/specs/ si popola naturalmente nel corso di mesi di lavoro normale.

Comandi CLI utili per controllare quello stato senza uscire dal terminale:

openspec list                 # modifiche attive
openspec show add-dark-mode   # visualizza gli artefatti di una modifica
openspec validate --all       # controlla il formato delle specifiche in tutto il progetto
openspec view                 # dashboard interattiva

Committa l’intera cartella openspec/ su git. Le modifiche attive e l’archivio sono destinati a diventare un registro durevole e versionato di cosa fa il tuo sistema e perché è cambiato – non un blocco note da eliminare dopo il merge.

Adottare OpenSpec su una codebase esistente

La preoccupazione più comune dai team che valutano OpenSpec su un progetto reale è qualche versione di “la mia app ha 80.000 righe, devo specificare tutto prima?” No. La guida stessa di OpenSpec è franca su questo: scegli qualcosa di piccolo e reale che avevi già intenzione di costruire questa settimana, esegui /opsx:explore sull’area che stai per toccare in modo che l’agente mappi prima come le cose funzionano effettivamente, poi /opsx:propose una modifica limitata a solo quella fetta.

Se hai già PRD, documenti SRS o documenti di design che stanno in Notion o Confluence, trattali come materiale di fonte per l’esplorazione piuttosto che qualcosa da convertire in blocco in specifiche. Incolla la sezione rilevante in una sessione /opsx:explore e lascia che l’agenti modelli un delta focalizzato da essa; una conversione meccanica una tantum di un PRD di quaranta pagine tende a produrre una specifica che nessuno si fida di sei mesi dopo. Per team che vogliono una prima esecuzione guidata e narrazione invece di saltare direttamente in una modifica reale, il comando espanso /opsx:onboard scansiona la tua codebase per un miglioramento piccolo e sicuro e passa attraverso il ciclo completo su di esso.

Domande e Problemi Comuni

Questi sono i problemi che emergono ripetutamente attraverso il Discord di OpenSpec, le issue GitHub e i thread Reddit in subreddits come r/cursor, r/RooCode e r/opencodeCLI.

“Ho digitato il comando slash e niente è successo.” Quasi sempre uno di questi: lo hai digitato nel terminale invece che nella chat del tuo assistente, il tuo IDE non è stato riavviato da quando openspec init è stato eseguito, o la versione del CLI è così vecchia che openspec update segnala tutto come aggiornato senza mai scrivere i file di workflow più recenti. Esegui openspec update, riavvia l’IDE e conferma che le cartelle delle skill esistono (.claude/skills/openspec-* per Claude Code, o l’equivalente del tuo strumento dall’elenco degli strumenti supportati).

“L’AI genera molto più specifica di quanto ne abbia bisogno.” Questa è la lamentela più citata nelle discussioni più lunghe: un agente può trasformare una funzionalità di trenta minuti in una specifica di 800 righe. OpenSpec limita il campo context: iniettato in ogni richiesta a 50KB specificamente per forzare la disciplina, ma le specifiche delta stesse non hanno un limite rigido, quindi ridurre le specifiche generate a ciò che è effettivamente portante è un’abitudine che devi mantenere da solo, non qualcosa che lo strumento applica per te.

“Due modifiche hanno toccato lo stesso requisito e una ha silenziosamente eliminato lo scenario dell’altra.” Questo è un caso limite reale e documentato: l’archiviazione applica un delta MODIFIED come una sostituzione a blocco intero con chiave per nome del requisito, quindi se due modifiche in corso modificano entrambe lo stesso requisito, l’archiviazione della seconda sovrascriveva in precedenza gli scenari della prima senza avvertimento. Le versioni attuali aggiungono un controllo di drift che interrompe l’archiviazione e ti dice di aggiornare prima la specifica della modifica – ma vale comunque la pena sapere che la modalità di fallimento esiste se esegui diverse modifiche sulla stessa area in parallelo.

“Quale modello AI dovrei effettivamente usare con esso?” I documenti stessi di OpenSpec raccomandano modelli di alta ragioneria sia per la pianificazione che per l’implementazione – i modelli di classe Opus e Codex sono specificati – e svuotare la finestra di contesto prima dell’implementazione, poiché un contesto pulito produce risultati misurabilmente migliori rispetto a una sessione lunga e accumulata.

“Come è diverso da Spec Kit, Kiro, Superpowers o BMAD?” Questa è la domanda Reddit più frequente, e la risposta onesta è “peso del processo.” Il README stesso di OpenSpec inquadra il confronto direttamente: Spec Kit è meticoloso ma più pesante, con più Markdown e gate di fase rigidi; Kiro è potente ma ti blocca nell’IDE di AWS e nei modelli Claude; OpenSpec scambia parte di quella struttura iniziale per la capacità di iterare liberamente e lavorare con qualsiasi assistente che hai già aperto. Per la suddivisione completa rispetto a Spec Kit, Kiro, skill Claude Code, BMAD-METHOD e Superpowers, vedi il confronto degli strumenti SDD dedicato.

“L’AI segue davvero la specifica che ha appena scritto?” Non sempre, e questo è un problema documentato attraverso gli strumenti SDD in generale, non unico di OpenSpec – una grande finestra di contesto non significa che l’agente presti attenzione ugualmente a ogni parte di essa. Il comando /opsx:verify esiste specificamente per cogliere codice generato che contraddice la sua stessa specifica, e vale la pena eseguirlo su qualsiasi cosa non banale invece di fidarsi ciecamente dell’implementazione.

“Ho bisogno di questo per una modifica di una riga?” No. La FAQ stessa di OpenSpec dice così: usalo dove l’accordo conta, che è la maggior parte del lavoro non banale, multi-file, e saltalo per una correzione di refuso o un prototipo monouso che eliminerai in una settimana.

Quando OpenSpec si Adatta e Quando Non si Adatta

Buona corrispondenza:

  • Codebase brownfield dove vuoi specifiche revisionabili senza documentare l’intero sistema in anticipo.
  • Sviluppatori solisti e piccoli team che vogliono una cerimonia più leggera di Spec Kit ma ottenere comunque un piano scritto prima del codice.
  • Lavoro che attraversa diversi file, una modifica dello schema o qualsiasi cosa per cui un ingegnere junior vorrebbe ragionevolmente un breve documento di design.
  • Team già impegnati a revisionare i piani nelle pull request – le specifiche delta differenziano pulitamente poiché descrivono solo ciò che è cambiato.

Corrispondenza più debole:

  • Correzioni di bug di una riga e prototipi monouso, dove il passaggio di revisione della proposta costa più di quanto salvi.
  • Team che hanno bisogno della struttura più pesante e prescrittiva di Spec Kit o di un’esperienza AWS-nativa, integrata con l’IDE come Kiro – vedi il quadro decisionale nel confronto degli strumenti per dove ogni strumento vince.
  • Funzionalità cross-repo al momento, a meno che tu non sia disposto a provare la funzione stores beta di OpenSpec, che sposta la pianificazione in un proprio repository condiviso in modo che più codebase e agenti possano leggere lo stesso piano.
  • Qualcuno che sta ancora decidendo se una data funzionalità meriti una specifica – leggi Spec-Driven Development vs Vibe Coding prima, poiché OpenSpec aiuta solo una volta che hai già deciso che la struttura vale l’overhead.

Conclusione

La scommessa di OpenSpec è che la maggior parte del dolore dello Spec-Driven Development provenga dalla cerimonia, non dall’idea sottostante di accordarsi su un piano prima che esista codice. Delta invece di riscritture complete, nessuna fase bloccata e un workflow brownfield-first lo rendono visibilmente più leggero di Spec Kit o Kiro da adottare su una codebase che non hai costruito da zero. I compromessi sono reali anche – l’espansione delle specifiche è un rischio genuino senza disciplina, la gestione dei conflitti intorno a modifiche simultanee a un singolo requisito è ancora in fase di maturazione, e l’ecosistema è più giovane di quello di GitHub stesso. Installalo su un progetto reale, esegui una piccola modifica attraverso explore-propose-apply-archive dall’inizio alla fine, e decidi da lì se la cerimonia più leggera si guadagna il suo posto rispetto al tuo carico di lavoro reale.

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.