OpenSpec Quickstart: Installazione, Workflow e Errori più Comuni

Specifica le modifiche come incrementi, non in un PRD di 40 pagine.

Indice

OpenSpec è una CLI gratuita e open source di Fission AI che consente a te e al tuo agente di coding di concordare una modifica in Markdown semplice prima che venga scritto qualsiasi codice, evitando la cerimoniale fase-gated dei framework spec-driven più pesanti.

La maggior parte dei team che provano lo Sviluppo Guidato da Specifiche (Spec-Driven Development) si blocca allo stesso dilemma: quanto processo è necessario per impedire all’agente di fare supposizioni, senza che il supporto (scaffolding) diventi così ingombrante da richiedere un documento di proposta per la correzione di un bug di cinquanta righe. La risposta di OpenSpec è di ignorare completamente l’istinto di “documentare prima l’intero sistema” e scrivere specifiche solo per ciò che la modifica tocca effettivamente, utilizzando delta ADDED, MODIFIED e REMOVED invece di una riscrittura completa ogni volta.

Flusso di lavoro per lo sviluppo guidato da specifiche di OpenSpec con un assistente AI per la codifica

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 – è in genere la scelta quando un team desidera specifiche revisionabili senza una fase di pianificazione di 800 righe. Questa guida copre l’installazione della CLI, il flusso di lavoro a quattro comandi che si usa effettivamente giorno per giorno, come appare una modifica su disco e le domande e i reclami più frequenti su Reddit e nel tracciante di problemi (issue tracker) di OpenSpec.

Cos’è OpenSpec?

OpenSpec descrive la propria filosofia in quattro righe: fluido non rigido, iterativo non waterfall, semplice non complesso, costruito per il brownfield non solo per il greenfield. In pratica questo significa che non ci sono fasi bloccate – puoi modificare una proposta, una specifica o un elenco di task in qualsiasi punto di una modifica, invece di essere costretto a seguire specify-then-plan-then-implement in ordine rigoroso come descrive il flusso di lavoro SDD neutrale rispetto al tool.

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 le modifiche che ne hanno bisogno
tasks.md L’elenco di controllo per l’implementazione che l’agente segue

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

Installare OpenSpec

OpenSpec è una CLI basata su Node.js, quindi hai bisogno di Node 20.19.0 o versioni successive sulla tua macchina.

node --version

Installa la CLI globalmente con npm, quindi verifica che si trovi sulla tua 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 alla tua configurazione rispetto a npm. Una volta installato, inizializzalo all’interno di un progetto:

cd your-project
openspec init

openspec init chiede quali strumenti AI utilizzi e scrive i file di skill e comando corrispondenti – OpenSpec supporta oltre 30 assistenti, inclusi Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro e OpenCode. Per CI o setup scriptizzati, salta completamente la selezione:

openspec init --tools claude,cursor   # configura strumenti specifici
openspec init --tools all             # ogni strumento supportato
openspec init --tools none            # solo struttura openspec/, nessun file per strumenti

Riavvia il tuo IDE in modo che rilevi le nuove skill e i comandi scritti. Se preferisci che sia il tuo assistente a eseguire tutta l’installazione, OpenSpec fornisce un prompt di setup che puoi incollare in Claude Code o un altro agente, che eseguirà l’installazione, eseguirà openspec init e ti riferirà cosa ha configurato.

Il Flusso di Lavoro Principale: Explore, Propose, Apply, Archive

Questa è l’unica cosa che fa inciampare quasi tutti nel primo giorno: i comandi openspec vengono eseguiti nel tuo terminale, ma i comandi /opsx: vengono eseguiti nella finestra di chat del tuo assistente AI. Non c’è una separata “modalità interattiva” da attivare – digitare il comando con la barra diagonale nella chat è il modo in cui si inizia.

flowchart LR A["/opsx:explore (opzionale)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specifiche unificate| E["openspec/specs/"]
  • /opsx:explore è un partner di ragionamento a zero rischi. Legge la parte rilevante del tuo codebase, presenta le opzioni e modella un piano prima che venga scritto qualcosa su disco – vale la pena formarne l’abitudine proprio perché impedisce a un agente entusiasta di costruire con sicurezza la cosa sbagliata.
  • /opsx:propose <nome> crea openspec/changes/<nome>/ e abbozza la proposta, le specifiche delta, il design opzionale e l’elenco dei task in un solo passaggio. Qui revisioni il piano, prima che inizi l’implementazione.
  • /opsx:apply lavora attraverso l’elenco dei task, spuntando gli elementi man mano che procede. Poiché il progresso vive nei file e non solo nella cronologia della chat, puoi svuotare la tua finestra di contesto o iniziare una nuova sessione e riprendere esattamente da dove /opsx:apply si era interrotto.
  • /opsx:archive archivia la modifica completata in openspec/changes/archive/YYYY-MM-DD-<nome>/ e unifica le sue specifiche delta nell’albero canonico openspec/specs/.

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

Ogni strumento scrive lo stesso 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ù rapida per “niente è successo quando ho digitato il comando” è in genere rileggere quel suggerimento stampato piuttosto che indovinare.

Come Appare una Modifica su 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 specifiche per una modifica di un singolo campo. È anche per questo che OpenSpec è esplicitamente brownfield-first piuttosto che greenfield-first: non devi mai documentare la tua intera applicazione prima di trarne valore, documenti solo la fetta che ogni modifica reale tocca, e openspec/specs/ si riempie naturalmente nel corso di mesi di lavoro normale.

Comandi CLI utili per controllare quello stato senza lasciare il 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/ in git. Le modifiche attive e l’archivio sono destinati a diventare un registro duraturo e versionato di cosa fa il tuo sistema e perché è cambiato – non un blocco note da cancellare dopo il merge.

Adottare OpenSpec su un Codebase Esistente

La preoccupazione più comune da parte di team che valutano OpenSpec su un progetto reale è una versione di “la mia app ha 80.000 righe di codice, devo specificarla tutta prima?”. No. Le linee guida di OpenSpec sono franche su questo: scegli qualcosa di piccolo e reale che avevi già in programma 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 giacciono in Notion o Confluence, trattali come materiale di partenza per l’esplorazione piuttosto che come qualcosa da convertire in blocco in specifiche. Incolla la sezione rilevante in una sessione /opsx:explore e lascia che l’agente ne modelli uno delta focalizzato; una conversione meccanica unica di un PRD di quaranta pagine tende a produrre una specifica che nessuno si fida dopo sei mesi. Per i team che preferiscono una prima esecuzione guidata e narrata invece di saltare direttamente in una modifica reale, il comando espanso /opsx:onboard scansiona il tuo codebase per un piccolo miglioramento sicuro e percorre il ciclo completo su di esso.

Domande e Problemi Comuni

Questi sono i problemi che emergono ripetutamente nel Discord di OpenSpec, nelle issue GitHub e nei thread Reddit in subreddit come r/cursor, r/RooCode e r/opencodeCLI.

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

“L’AI genera molto più specifiche di quante ne ho bisogno.” Questa è la lamentela più citata in scritti più lunghi: 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 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 scartato lo scenario dell’altra.” Questo è un caso limite reale e documentato: l’archiviazione applica uno delta MODIFIED come una sostituzione di blocco intero chiave per nome del requisito, quindi se due modifiche in corso modificano entrambe lo stesso requisito, l’archiviazione della seconda sovrascriveva gli scenari della prima senza preavviso. Le versioni correnti aggiungono un controllo di deriva che interrompe l’archiviazione e ti dice di aggiornare prima la specifica della modifica – ma vale comunque la pena sapere che il modo di fallimento esiste se esegui diverse modifiche sulla stessa area in parallelo.

“Quale modello AI dovrei effettivamente usare?” I documenti di OpenSpec stesso raccomandano modelli ad alto ragionamento sia per la pianificazione che per l’implementazione – vengono citati specificamente modelli di classe Opus e Codex – e di svuotare la finestra di contesto prima dell’implementazione, poiché un contesto pulito produce risultati misurabilmente migliori di una sessione lunga e accumulata.

“Come è diverso da Spec Kit, Kiro, Superpowers o BMAD?” Questa è la singola domanda più frequente su Reddit, e la risposta onesta è “peso del processo”. Il README di OpenSpec stesso inquadra il confronto direttamente: Spec Kit è accurato ma più pesante, con più Markdown e gate di fase rigidi; Kiro è potente ma ti vincola all’IDE di AWS e ai 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 il breakdown completo contro Spec Kit, Kiro, skill di Claude Code, BMAD-METHOD e Superpowers, consulta la dedicata confrontazione degli strumenti SDD.

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

“Ne ho bisogno per una correzione di una riga?” No. La FAQ di OpenSpec stessa lo dice: usalo dove l’accordo conta, che è la maggior parte del lavoro non banale e multi-file, e saltalo per la correzione di un refuso o per un prototipo usa-e-getta che cancellerai in una settimana.

“Come faccio a impedire a un agente di riproporre qualcosa che abbiamo già rifiutato?” /opsx:archive non ha uno stato dedicato per una modifica rifiutata, quindi nulla dice a una proposta futura che un’idea è già stata indagata e respinta. Vedi Proposte Rifiutate in OpenSpec: Una Convenzione di Memoria Decisionale per il pattern decision.md e la regola di configurazione che fa sì che un agente cerchi nell’archivio prima di riproporre.

Quando OpenSpec Si Adatta e Quando No

Buona adattabilità:

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

Adattabilità più debole:

  • Correzioni di bug di una riga e prototipi usa-e-getta, dove il passo di proposta-revisione costa più di quanto risparmi.
  • Team che necessitano della struttura più pesante e prescrittiva di Spec Kit o di un’esperienza AWS-nativa e integrata nell’IDE come Kiro – vedi il framework decisionale nel confronto degli strumenti per dove ogni strumento vince.
  • Funzionalità cross-repo oggi, a meno che tu non sia disposto a provare la funzione beta stores di OpenSpec, che sposta la pianificazione in un proprio repository condiviso in modo che più codebase e agenti possano leggere lo stesso piano.
  • Qualsiasi persona che stia 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 il sovraccarico.

Conclusione

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

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.