Spec Kit: la specifica viene prima dell'agente

Il modo in cui la maggior parte di noi usa un agente è ancora quello della chat. Scrivi tre righe di prompt, l'agente comincia a toccare i file, tu leggi il diff e correggi. Su una modifica piccola funziona benissimo. Su una feature che tocca database, API e interfaccia comincia a sfaldarsi, e il punto di rottura è sempre lo stesso: le decisioni stanno nella conversazione, e la conversazione muore quando chiudi la sessione. Due settimane dopo apri il codice e non sai più perché quella tabella ha tre stati invece di due.

Spec Kit è il tentativo di GitHub di mettere ordine in questa cosa. È open source, licenza MIT, e la prima cosa da dire è quello che non è: non è un framework, non entra nelle dipendenze del progetto, non gira a runtime. È una CLI che ti scarica nel repository dei template, degli script e una serie di comandi slash per il tuo agente. Lo installi, e quello che cambia è il processo, non lo stack.

uv tool install specify-cli
specify init il-mio-progetto

Da quel momento hai una cartella .specify/ con i template e la memoria del progetto, e i comandi disponibili nell'agente. Io lo uso con Claude Code, ma oggi le integrazioni supportate sono decine, da Copilot a Cursor a Gemini CLI.

Il flusso, in concreto

Questi sono i comandi che uso davvero, in ordine:

/speckit.constitution   principi e vincoli del progetto, si scrive una volta
/speckit.specify        cosa deve fare la feature, senza dire come
/speckit.clarify        le domande sulle parti ambigue, prima del piano
/speckit.plan           stack, architettura, modello dati, contratti
/speckit.checklist      la checklist di qualità sui requisiti
/speckit.tasks          la lista ordinata di task
/speckit.analyze        controllo di coerenza tra spec, piano e task
/speckit.implement      esecuzione

Il risultato non è una chat, è una cartella. Per ogni feature ti ritrovi con una struttura di questo tipo:

specs/009-modulo-contabilita/
├── spec.md            requisiti, scenari utente, criteri di successo
├── research.md        le alternative valutate e perché
├── data-model.md      entità, relazioni, vincoli
├── contracts/         le interfacce delle API
├── plan.md            come si costruisce
├── tasks.md           i task numerati, in ordine di dipendenza
└── checklists/        cosa deve essere vero perché la feature sia finita

Sono file di testo dentro al repository, versionati insieme al codice. Questa è la parte che conta più di tutte le altre.

La costituzione è la parte che avevo sottovalutato

All'inizio consideravo /speckit.constitution un passaggio cerimoniale, il punto in cui scrivi quattro buoni propositi che nessuno rileggerà. Mi sbagliavo. La costituzione di uno dei progetti su cui lavoro adesso è un file da 14 KB diviso in principi fondamentali, vincoli tecnici di piattaforma, workflow di sviluppo e governance. Dentro ci sono le cose che su quel progetto non si discutono più: come si fa l'autenticazione, cosa non può mai finire nei log, quali librerie sono già state scelte e perché, quando serve una migrazione.

Serve a una cosa precisa. Senza, ogni feature ricomincia dal foglio bianco e l'agente riprogetta lo stack da capo, con la sicurezza di chi non ha memoria della volta prima. Con la costituzione nel contesto, le proposte che arrivano sono già dentro i binari del progetto, e le poche volte che ne escono te ne accorgi subito perché hai un testo con cui confrontarle.

Cosa ci guadagno

La specifica sopravvive alla sessione

Sei mesi dopo il file spec.md è lì, con gli scenari, i criteri di successo e le assunzioni che ci avevo messo dentro. La cronologia della chat non ce l'ha nessuno e non la rilegge nessuno. Quando entra una persona nuova sul progetto non le passo la conversazione, le passo la cartella.

Le ambiguità saltano fuori prima del codice

/speckit.clarify è il comando che mi ha sorpreso di più: fa le domande scomode sulle parti che hai lasciato vaghe, e le fa quando costa niente rispondere. Che succede se l'utente annulla a metà? Il totale lo ricalcoliamo o lo congeliamo? Nelle spec che scrivo adesso c'è una sezione Clarifications che è il verbale di quelle domande, ed è il pezzo che mi ha salvato più ore.

Una feature diventa una lista, non un blocco

L'ultimo tasks.md che ho generato ha 64 voci con le caselle da spuntare, ordinate per dipendenza. Il lavoro si può interrompere, riprendere il giorno dopo, spezzare fra sessioni diverse, e in qualsiasi momento sai dove sei. Con il prompt in chat lo sai solo finché resti dentro quella chat.

La review torna possibile

Una spec la leggi in dieci minuti e ci discuti sopra. Un diff da duemila righe generato in un colpo solo non lo rivede nessuno con la stessa attenzione, e chi dice il contrario non l'ha mai fatto di venerdì sera. Spostare il controllo qualità prima della generazione è l'unico modo che ho trovato per non firmare pull request che non ho capito.

Quello che costa

Il flusso completo, prima che venga scritta una riga di codice, sono tranquillamente tre quarti d'ora. Per una correzione di due righe, per un bug, per un esperimento che probabilmente butto via, non lo uso e non lo consiglierei. Il costo si ripaga quando la feature è abbastanza grande da avere un modello dati, o abbastanza lunga da durare più di una sessione.

C'è poi un rischio che ho visto da vicino. La spec te la scrive l'agente, ed è lunga: quella del modulo di contabilità è un file da 27 KB. Se non la leggi davvero, hai solo spostato il problema, perché adesso stai approvando senza capire un documento invece che un diff. Le risposte a /speckit.clarify le devo dare io, non le può indovinare il modello, e quando ho tirato via su quelle risposte il risultato è stato regolarmente peggiore.

Ultima nota pratica: il progetto si muove in fretta, i comandi hanno cambiato nome almeno una volta, quindi prima di copiare qualcosa da un tutorial vecchio conviene guardare il repository. Non è una critica, è la normale vita di uno strumento uscito da poco e con molta gente sopra.

Io oggi apro Spec Kit su qualsiasi cosa duri più di mezza giornata. Non perché mi piaccia scrivere documentazione, che è una cosa che ho evitato per anni, ma perché è l'unico modo in cui sono riuscito a far lavorare un agente su qualcosa di grosso senza perderne il controllo.