Quando lavori con un agente di programmazione basato sull’intelligenza artificiale, come Claude Code, Codex o OpenCode, puoi già discutere il lavoro nella modalità Plan e lasciarlo poi eseguire in Build. Il limite è che quel piano vive dentro la conversazione. Chiudi la sessione o cambi assistente, e le scelte concordate finiscono sepolte nella cronologia della chat insieme alle loro ragioni.
Spec Kit nasce per dare a quelle decisioni una forma stabile. Si tratta di un kit open source pubblicato da GitHub con licenza MIT, che affianca il tuo agente preferito (oltre a quelli citati, anche Copilot, Gemini CLI, Cursor e molti altri) e lo costringe a seguire una procedura precisa. Prima si scrive una specifica, cioè un documento che descrive cosa deve fare il software e perché. Poi si prepara un piano tecnico, lo si divide in compiti e solo alla fine si passa alla scrittura del codice.
L’approccio ha un nome, Spec-Driven Development, e in un anno ha raccolto un seguito notevole. Il repository supera le 139.000 stelle, la versione 1.0 è arrivata ad agosto 2026 e l’ultima release, la 1.0.12, è uscita il 25 settembre.
Oggi Spec Kit non serve soltanto a costruire applicazioni, perché due estensioni ufficiali lo usano anche per correggere bug e per valutare se un’idea merita di essere sviluppata. Il risultato è un modo di lavorare con l’AI più lento all’inizio e molto più prevedibile alla fine.
Dal prompt improvvisato alla specifica scritta
Per capire Spec Kit conviene partire da un’analogia. Nessuno chiamerebbe una squadra di muratori dicendo soltanto «costruitemi una casa». Prima arrivano la planimetria, il progetto dell’impianto elettrico, l’elenco dei materiali, e solo dopo si posano i mattoni. Con gli agenti AI, invece, anche quando il progetto viene discusso resta spesso su un foglio volante, cioè una conversazione destinata a perdersi.
Lo Spec-Driven Development rovescia questa abitudine. Al centro c’è la specifica, un file Markdown che descrive il comportamento atteso in termini comprensibili anche a chi non programma, con gli scenari d’uso e i criteri per stabilire se una funzionalità è completa. Il codice diventa una conseguenza di quel testo, e se qualcosa cambia si aggiorna prima la specifica e poi l’implementazione.
Spec Kit traduce questa filosofia in una sequenza di documenti, ciascuno generato dall’agente e rivisto da te:
- Costituzione. Le regole che valgono per tutto il progetto. Si scrive una volta sola.
- Specifica. Descrive cosa deve fare la nuova funzionalità e perché, senza nominare linguaggi o framework.
- Piano. Qui entrano le scelte tecniche, dallo stack al modello dei dati.
- Compiti. Il piano viene spezzato in attività ordinate, con le dipendenze tra l’una e l’altra.
Il vantaggio più evidente riguarda il contesto. Un agente che lavora su una specifica scritta non deve ricordare tutto quello che gli hai detto venti messaggi prima, perché le decisioni sono salvate in file che rilegge a ogni passaggio. Di conseguenza puoi chiudere la sessione, riaprirla il giorno dopo o perfino cambiare agente, e il lavoro riprende esattamente dal punto in cui era rimasto.
Esiste anche un beneficio meno ovvio. I documenti restano nel repository insieme al codice, quindi fra sei mesi saprai ancora perché una funzione è stata costruita in un certo modo. Con il vibe coding puro, cioè la programmazione affidata a una conversazione libera con l’AI, quella memoria si perde nella cronologia della chat.
Ma se l’agente offre già una modalità Plan/Ask, a cosa serve un kit in più? Le differenze principali sono quattro:
- Persistenza. Il piano discusso in Plan resta nella sessione, mentre specifica, piano e compiti di Spec Kit sono file versionati nel repository, da rileggere, correggere e far approvare con una pull request.
- Regole comuni. La costituzione vale per ogni funzionalità futura, senza doverla ripetere all’inizio di ogni conversazione.
- Livelli separati. La specifica descrive che cosa deve fare il software e perché; il piano stabilisce invece come realizzarlo.
- Controllo finale. Con il comando
convergel’agente confronta il codice con i documenti approvati e segnala ciò che manca, una verifica che la discussione iniziale non prevede.
Per una modifica rapida il piano in chat basta e avanza. Spec Kit acquista senso per lavori che durano giorni, per progetti da riprendere fra mesi e per chi alterna più assistenti sullo stesso codice.
Installare Specify CLI e preparare il primo progetto
Il cuore di Spec Kit è Specify CLI, un programma a riga di comando che prepara la struttura del progetto e aggiunge all’agente i comandi del metodo. I requisiti sono tre, ovvero Python 3.11 o successivo, il gestore di pacchetti uv e almeno un agente di programmazione già funzionante. Git è facoltativo e serve solo se attivi l’estensione dedicata.
Se uv non è ancora presente sul tuo computer, si installa con un solo comando:
# Windows (PowerShell)
winget install --id=astral-sh.uv -e
# macOS
brew install uv
# Linux e macOS, installer ufficiale
curl -LsSf https://astral.sh/uv/install.sh | sh
A questo punto installi Specify CLI e crei il primo progetto, indicando l’agente che usi con l’opzione --integration:
uv tool install specify-cli
specify version
specify init catalogo-libri --integration claude
cd catalogo-libri
Al posto di claude puoi scrivere copilot, gemini, codex, cursor-agent, qwen, opencode o una delle altre chiavi supportate, che ormai superano la quarantina. L’elenco completo si ottiene con specify integration list. Se non indichi nulla, in una sessione interattiva il programma ti chiede quale agente preferisci con un menu.
Su Windows il sistema sceglie da solo le procedure automatiche per PowerShell, mentre su Linux e macOS usa quelle per bash. Puoi forzare la scelta con --script ps, --script sh oppure --script py, utile se lavori con WSL o in un ambiente misto.
Nella mia prova con la versione 1.0.12, il comando init ha creato la directory nascosta .specify, con modelli, script e la futura costituzione, per circa 180 KB in tutto. Per Claude Code ha aggiunto inoltre dieci skill in .claude/skills, una per ciascun comando del metodo. Ogni specifica prodotta in seguito vivrà invece in specs/, dentro una sottocartella numerata per ciascuna funzionalità.
Per restare aggiornato ti basta lanciare ogni tanto specify self check, che controlla se esiste una versione più recente senza toccare nulla. Il progetto viaggia a ritmo serrato, con una nuova release ogni due o tre giorni, quindi il controllo non è superfluo.
Il ciclo completo, dalla costituzione al codice
A questo punto il lavoro si sposta dentro l’agente e lascia il terminale. Apri Claude Code, Copilot o l’assistente che hai scelto nella cartella del progetto e invochi i comandi uno alla volta, rileggendo il risultato prima di passare al successivo. La sintassi cambia leggermente a seconda dell’agente:
| Agente o modalità | Esempio |
|---|---|
| GitHub Copilot in modalità skill | /speckit-specify |
| Notazione con il punto, usata nella documentazione | /speckit.specify |
| Codex, Command Code, ZCode | $speckit-specify |
| Kimi | /skill:speckit-specify |
Ecco una sequenza intera per un’app che cataloga i libri di casa. Le richieste si possono scrivere tranquillamente in italiano:
/speckit-constitution Crea principi basati su codice leggibile, test automatici per ogni funzione e interfaccia accessibile anche da smartphone.
/speckit-specify Crea un'app web per catalogare i libri di casa, con ricerca per autore, genere e stato di lettura, e una pagina con le statistiche dell'anno.
/speckit-plan Usa Vite con JavaScript senza framework. I dati restano sul computer in un database SQLite.
/speckit-tasks
/speckit-implement
/speckit-converge
I primi quattro comandi producono testi da rileggere, mentre implement scrive finalmente il codice seguendo i compiti. L’ultimo passaggio, il comandoconverge, è quello che distingue di più il metodo. Confronta il codice con specifica, piano e compiti, individua ciò che manca o è rimasto a metà e lo aggiunge in coda a tasks.md come nuove attività. Non modifica il codice né i file di partenza, si limita ad allungare la lista. Ripeti implement e converge finché il rapporto non dichiara la funzionalità convergente, cioè realizzata per intero.
Fra una fase e l’altra puoi inserire tre verifiche facoltative, che su progetti non banali consiglio di usare sempre:
- Clarify. L’agente ti pone fino a cinque domande mirate sui punti ambigui della specifica e salva le risposte nel documento. Va lanciato prima del piano.
- Checklist. Genera una lista di controllo sulla qualità dei requisiti, una sorta di test per la specifica anziché per il codice.
- Analyze. Legge specifica, piano e compiti e segnala incoerenze, come un compito senza requisito corrispondente. Non modifica alcun file.
Il consiglio più utile riguarda la separazione dei ruoli. Nella specifica descrivi solo il comportamento e lascia le tecnologie al piano, altrimenti l’agente mescola le due cose e perdi il principale vantaggio del metodo. Allo stesso modo, prenditi il tempo di leggere ogni documento generato, perché sistemare una riga della specifica costa molto meno che riscrivere righe di codice.
Bug da correggere e idee da valutare con le estensioni
Con la versione 1.0 Spec Kit ha smesso di essere soltanto uno strumento per costruire funzionalità da zero. Il gruppo che lo mantiene lo descrive ormai come un’impalcatura per processi strutturati, e ne distribuisce due già pronti come moduli facoltativi.
Il primo riguarda i bug e si attiva con specify extension add bug. Il principio è separare tre fasi che di solito un agente mescola in un unico tentativo, ovvero la diagnosi, la correzione e il collaudo:
/speckit-bug-assess "Se invio il modulo di accesso con la password vuota, la pagina va in errore." slug=login-vuoto
/speckit-bug-fix slug=login-vuoto
/speckit-bug-test slug=login-vuoto
I rapporti vengono salvati in .specify/bugs/login-vuoto/ e si chiudono con un verdetto netto tra verified, partial e failed. Una riparazione senza verifica non conta come riuscita, e questo toglie all’agente la tentazione di dichiarare risolto un problema che ha solo spostato altrove.
Il secondo, installabile con specify extension add assess, serve prima ancora di scrivere codice. Accompagna l’agente in cinque fasi (raccolta, ricerca, definizione, modellazione e decisione) per capire se un’idea merita tempo e risorse. Il percorso termina con uno di tre esiti, ovvero via libera, chiarimenti necessari oppure abbandono, e un esito positivo può passare direttamente a /speckit-specify. Funziona anche in una cartella senza codice, per esempio per valutare una nuova sezione del tuo sito.
Accanto ai moduli ufficiali esiste un catalogo della comunità ormai molto ricco. Si trovano preset che adattano i modelli alle regole di un’azienda, estensioni per portare i compiti su Jira e pacchetti dedicati alla governance aziendale.
Usarlo su un progetto già avviato
Spec Kit non obbliga a partire da zero, e anzi la documentazione dedica una guida intera ai progetti esistenti. Per prima cosa salva il lavoro in corso con un commit e crea un ramo apposito, così ogni file aggiunto sarà visibile e reversibile. Poi, dalla radice del repository, lanci l’inizializzazione sul posto:
git checkout -b adozione-spec-kit
specify init --here --force --integration claude
git status
L’opzione --here lavora nella cartella corrente, mentre --force autorizza l’operazione in una directory non vuota. Il comando non tocca il codice dell’applicazione e non prova a ricostruire specifiche per ciò che esiste già, si limita ad aggiungere .specify e i file dell’agente.
Il passo seguente è la costituzione. Vanno inserite solo regole che il progetto rispetta davvero o che hai deciso di adottare, ricavandole dal README, dalle convenzioni già in uso e dai test esistenti. Infine scegli una prima modifica circoscritta, come l’esportazione in CSV di una tabella, e descrivi insieme il risultato atteso e ciò che non deve cambiare.
I costi di un metodo rigoroso
Spec Kit ha anche un prezzo, il primo in assoluto è il tempo. Il ciclo completo di costituzione, specifica, piano, compiti e convergenza produce testo da leggere con attenzione.
Il secondo riguarda i consumi. Ogni comando fa leggere all’agente modelli, costituzione e documenti precedenti, quindi i token usati potrebbero crescere rapidamente. Con un abbonamento a consumo, o con un’offerta che ha limiti settimanali, la differenza rispetto a una conversazione libera potrebbe notarsi.
Poi bisogna considerare la revisione. Il metodo funziona solo se leggi davvero ciò che l’agente scrive, e una specifica approvata di fretta può produrre un piano errato, da cui nasce codice difettoso. In altre parole, Spec Kit sposta il tuo lavoro dalla scrittura del codice alla verifica dei documenti.
Il file tasks.md come contratto fra te e l’agente
Spec Kit ti obbliga a decidere cosa vuoi prima di chiederlo, e lascia dietro di sé una traccia scritta che sopravvive alla sessione di chat, all’agente di turno e perfino alla tua memoria. Il file tasks.md riassume bene questa idea. È l’elenco di ciò che l’agente si è impegnato a fare, che tu hai approvato e che converge confronta con il codice reale per scoprire cosa manca. Funziona come un contratto, ed è molto più facile da controllare di una lunga conversazione.
Resta comunque un metodo da dosare. Per una correzione di due righe o per uno script usa e getta, il costo in tempo e token supera il beneficio. Diventa invece prezioso per sviluppi di medie dimensioni, per progetti che dovrai riprendere fra mesi e per chi lavora con più agenti diversi sullo stesso codice.
