GitHub Spec Kit: usare le specifiche per rendere controllabile il coding assistito
Spec Kit propone un flusso spec-driven per progetti software con AI. Cosa aggiunge al lavoro di un team, dove fallisce e come provarlo senza burocrazia.
Scritto da Daniel Vedovato · Revisionato il 21 luglio 2026
Articolo preparato con assistenza AI, verificato e revisionato da Daniel Vedovato.
Il codice arriva più in fretta, l’accordo sul problema no
Spec Kit è un progetto di GitHub che raccoglie un flusso di lavoro spec-driven: prima si chiariscono requisiti, principi e piano, poi si passa all’implementazione con strumenti di coding assistito. Non è un modello AI né un generatore di codice. È un insieme di template e comandi pensato per rendere esplicite le decisioni che spesso restano implicite nel prompt di un agente.
Il problema è concreto. Un assistente può produrre una patch credibile in pochi minuti, ma non sa da solo se un requisito è compatibile con privacy, migrazioni, convenzioni del repository o comportamento atteso da utenti esistenti. Se queste informazioni non sono scritte, la velocità di generazione sposta il lavoro a valle: review più lunga, richieste di modifica e regressioni difficili da attribuire.
Spec Kit propone una sequenza che parte da una costituzione del progetto, passa da specifica e piano e arriva a task più piccoli. Il valore non è compilare documenti per principio. È rendere verificabili domande che altrimenti spariscono nel dialogo: quale problema si risolve, per chi, quali confini non vanno oltrepassati e come si dimostra che il cambiamento funziona.
Dove aiuta davvero
In un repository nuovo o in una feature trasversale, una specifica può evitare che agenti diversi inventino interpretazioni diverse. La costituzione è utile per poche regole durevoli: compatibilità, test obbligatori, standard di sicurezza, limiti di dipendenza e stile di revisione. La specifica descrive invece il comportamento osservabile. Il piano collega quel comportamento a file, componenti e rischi. I task trasformano il piano in unità che si possono controllare.
Questo approccio è particolarmente utile quando l’AI riceve contesto incompleto. Anziché chiedere “aggiungi il login”, una specifica può stabilire ruoli, provider, sessioni, protezione dai tentativi ripetuti, esperienza in caso di errore e criteri di accettazione. Il modello resta libero di proporre codice, ma non deve indovinare la parte più costosa: cosa intendesse davvero il team.
| Artefatto | Domanda a cui risponde | Segnale di qualità |
|---|---|---|
| Principi | Quali vincoli restano validi? | Regole brevi, applicabili in review |
| Specifica | Che cosa vede e fa l’utente? | Casi normali ed errori descritti |
| Piano | Quali parti del sistema cambiano? | Dipendenze e rischi espliciti |
| Task | Qual è il prossimo pezzo verificabile? | Risultato e test definiti |
Il rischio: documentare una supposizione sbagliata
Un template non garantisce una buona analisi. Una specifica lunga, vaga o non aggiornata può diventare un falso senso di sicurezza. L’AI produrrà codice coerente con il testo, ma il testo potrebbe ignorare un utente, una dipendenza o una regola legale. La documentazione va quindi considerata un input di progettazione soggetto a review, non un contratto automaticamente vero.
Esiste anche un rischio di doppio mantenimento. Se ticket, documenti, codice e prompt raccontano quattro storie, il processo peggiora. La soluzione non è aggiungere altri file: bisogna decidere quale artefatto è la fonte di verità per ciascun tipo di decisione e rimuovere le copie inutili. Per modifiche minime, una breve checklist nel pull request può essere più onesta di una specifica formale.
Gli agenti devono infine ricevere confini operativi. Un piano non autorizza a cambiare infrastruttura, pubblicare dati o eseguire migrazioni irreversibili. I comandi consentiti, i test e la revisione umana restano parte del sistema, anche se il codice è stato generato a partire da una specifica eccellente.
Un pilota da due settimane
Per capire se Spec Kit aiuta davvero, conviene scegliere una feature di media complessità, con un comportamento utente chiaro e qualche dipendenza interna. Si crea la specifica prima del codice, si fa rivedere da chi conosce prodotto e sistema, poi si delegano task limitati a un assistente. Per confronto, si prende una feature simile realizzata con il processo abituale.
Le metriche non devono essere solo righe generate. Sono più informative il numero di chiarimenti dopo il primo diff, difetti trovati in review, regressioni dopo il rilascio, tempo per riprendere il lavoro e completezza dei test rispetto ai criteri scritti. Vale la pena annotare anche le parti della specifica che sono cambiate: mostrano dove il team non aveva ancora capito il problema.
Verdetto
Spec Kit è utile come disciplina per il coding assistito, non come rito da applicare a ogni modifica. Fa emergere il fatto che un agente accelera l’implementazione ma non sostituisce decisioni di prodotto e architettura. Se la specifica resta corta, collegata ai test e realmente usata nelle review, può diminuire la deriva del codice generato. Se diventa solo un modulo da riempire, aggiunge testo senza aumentare controllo.