Cos’è lo spec-driven development e quando è utile?

Cos’è lo spec-driven development?

Quando dai un compito a un agente di programmazione, di solito spieghi in chat cosa vuoi. Se resta solo nella chat, sparisce quando la sessione si chiude. Lo spec-driven development (SDD) scrive questa intenzione in un file prima del codice. La spec, cioè la specifica, è il documento che dice cosa farà l’agente e perché. L’agente scrive prima la spec, poi un piano tecnico che dice come farlo, poi una lista di task. Il codice lo genera per ultimo, basandosi su questi documenti.

Nell’articolo di settembre 2025 con cui ha presentato Spec Kit, GitHub riassume l’idea in una frase: «We’re moving from “code is the source of truth” to “intent is the source of truth.”» Cioè, a decidere cosa è giusto non è il codice, ma l’intenzione scritta. Lo stesso articolo dice anche cosa resta da fare allo sviluppatore: «Crucially, your role isn’t just to steer. It’s to verify.» Questo articolo parla di quella seconda frase.

Cosa succede alla spec a lavoro finito dipende dall’approccio. I tre livelli dell’articolo di ottobre 2025 in cui Birgitta Böckeler di Thoughtworks ha provato tre strumenti di SDD compaiono oggi anche nella documentazione di Spec Kit:

• Spec-first. La spec si scrive prima del codice; a lavoro finito si può buttare.
• Spec-anchored. La spec si conserva anche a lavoro finito e si usa per le modifiche successive.
• Spec-as-source. Le persone modificano solo la spec; il codice viene generato dalla spec e non si tocca mai a mano.

Secondo Böckeler, tutti gli approcci che ha trovato sono spec-first; come mantenere la spec nel tempo resta spesso indefinito. Come vedremo più avanti, è proprio questa incertezza a rendere più difficile la code review.

La nostra fonte principale sull’uso reale è lo studio Spec-Driven Development as Prescribed and as Practiced, di ricercatori della Carnegie Mellon University e di Google. La sua ultima versione su arXiv è del 15 ottobre 2026. Lo studio si basa su discussioni su Reddit, interviste a 21 professionisti (di cui 8 sviluppano strumenti) e 266 repository su GitHub. Anche le due percentuali qui sopra vengono da questo studio.

I file delle regole degli agenti di programmazione li abbiamo trattati nell’articolo su AGENTS.md e CLAUDE.md, e come esaminare una pull request scritta dall’IA in un articolo a parte. Questo articolo mette la spec tra i due.

Quali passaggi portano dalla spec al codice?

Gli strumenti danno nomi diversi ai passaggi, ma l’ordine è lo stesso: prima cosa fare, poi come, poi i task, e il codice per ultimo. Alla fine di ogni passaggio leggi il documento e lo correggi; l’agente passa al successivo con quella versione.

In Spec Kit si esegue /speckit.constitution una volta per progetto, poi per ogni funzionalità specify, plan, tasks, implement e converge, in quest’ordine. Nella constitution ci sono i principi del progetto, e ogni passaggio successivo viene valutato rispetto a essi; somiglia al file delle regole di un agente di programmazione. clarify, checklist e analyze sono controlli di qualità facoltativi, da aggiungere quando il lavoro ha punti poco chiari.

In Kiro ogni spec è fatta di tre file: requirements.md, design.md e tasks.md. I requisiti si scrivono con uno schema chiamato EARS: «WHEN [condizione] THE SYSTEM SHALL [comportamento atteso]». L’ordine è requisiti, design, task; se hai già un’architettura pronta, puoi anche partire dal design. I file delle regole di Kiro stanno nella cartella .kiro/steering/, e Kiro legge anche l’AGENTS.md nella radice del repository.

OpenSpec tiene ogni modifica in una cartella a sé: in openspec/changes/<modifica>/ ci sono la motivazione (proposal.md), i requisiti (specs/), un design se serve (design.md) e i task (tasks.md). Il ciclo è esplorazione, proposta, revisione, applicazione e archiviazione. La spec di una modifica scrive solo la differenza: quale requisito è stato aggiunto, modificato, rimosso o rinominato. Con l’archiviazione queste differenze confluiscono nelle spec principali in openspec/specs/; le spec principali descrivono il sistema com’è oggi. Ecco un file delta di esempio dal README di OpenSpec:

## 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 file delta è la parte più utile in review: nella pull request mostra a colpo d’occhio dove è cambiata l’intenzione. Ci torneremo più avanti.

Che differenza c’è tra Spec Kit, Kiro e OpenSpec?

Abbiamo letto la documentazione dei tre strumenti il 18 ottobre 2026. La tabella mostra quali file scrive ciascuno, cosa controlla a lavoro finito e cosa propone per i lavori piccoli:

Fonte: la documentazione di ciascuno strumento, 18 ottobre 2026. Il modo di scrivere i comandi dipende dall’agente di programmazione che usi (per esempio /speckit.plan o /speckit-plan). Secondo la documentazione di Kiro, i test property-based funzionano solo nell’IDE. In Kiro puoi anche far analizzare i requisiti prima del design, alla ricerca di incoerenze e lacune.

I tre funzionano in posti diversi. Spec Kit è un toolkit open source che si aggiunge al tuo agente di programmazione come comandi o skill. Anche OpenSpec si aggiunge agli strumenti che già usi; il suo README dice che supporta 30+ strumenti. Kiro invece è un agente di programmazione con un proprio IDE, una CLI e un’interfaccia web. Il README di OpenSpec dice che Kiro è «limited to Claude models»; nella pagina dei modelli di Kiro, al 18 ottobre 2026, ci sono però anche GPT-5.6 e modelli open-weight. Quello che uno strumento dice di un concorrente conviene verificarlo nella documentazione del concorrente stesso.

Nel 2025 in questo elenco c’era un nome in più: Tessl. Böckeler l’aveva provato insieme a Kiro e Spec Kit. A settembre 2025 Tessl ha presentato i suoi primi prodotti come basati sullo spec-driven development: uno Spec Registry in beta aperta e il Tessl Framework in beta chiusa. La sua documentazione di oggi descrive invece Tessl come «an open platform for managing agentic development across your organization» e non parla di spec-driven development. Il metodo oggi esiste come plugin pubblico nel registry di Tessl. Non abbiamo trovato una pagina aggiornata che dica a che punto sia oggi il Tessl Framework.

Ci sono altri due metodi open source che lavorano con le spec. In Superpowers l’agente prima ricostruisce con delle domande cosa vuoi; le modifiche piccole si concordano in chat, per i progetti si prepara un documento di design scritto. Nell’implementazione, che procede con subagent, ogni task viene esaminato in due fasi: prima la conformità alla spec, poi la qualità del codice. BMAD Method dice che il suo processo si adatta alla dimensione del lavoro: le modifiche piccole passano direttamente alla realizzazione.

Perché lo chiamano «il nuovo waterfall»?

Il waterfall, o modello a cascata, è l’approccio che progetta il lavoro in anticipo e porta avanti le fasi in un ordine rigido: niente design finché i requisiti non sono scritti e approvati, niente codice finché il design non è finito. Secondo chi lo critica, lo spec-driven development riporta quest’ordine con dei file markdown. Due articoli lo dicono già nel titolo: «The Waterfall Strikes Back» e «Reinvented Waterfall?». Quello che le critiche hanno in comune, però, è più il carico di review che l’ordine delle fasi.

Thoughtworks, ottobre 2025. Böckeler ha chiesto a Kiro di correggere un piccolo bug. Il documento dei requisiti ha trasformato quel piccolo bug in 4 user story con 16 criteri di accettazione in tutto. Quando ha provato Spec Kit su una funzionalità più grande, anche lì ha trovato troppi file markdown da leggere per la dimensione del lavoro: «To be honest, I’d rather review code than all these markdown files.» Nonostante tutti questi file, scrive, ha visto spesso l’agente non seguire tutte le istruzioni.

Scott Logic, novembre 2025. Colin Eberhardt ha cancellato una funzionalità della sua app amatoriale, l’ha fatta ricostruire con Spec Kit e ha annotato il tempo speso a ogni passaggio. Ha costruito la funzionalità in due passaggi: prima le schermate per gestire i circuiti, poi il GPS. Il primo passaggio ha prodotto 2.577 righe di markdown e 689 righe di codice, e leggerle e rivederle ha richiesto 3,5 ore; il secondo 2.262 righe di markdown e circa 300 righe di codice, con circa 2 ore di review. Quando ha fatto la stessa funzionalità senza spec, come lavora di solito, ha impiegato 24 minuti in tutto: 15 minuti di code review e 9 minuti di test. È la misurazione di Eberhardt stesso: un solo sviluppatore, una sola app amatoriale, Spec Kit com’era a novembre 2025; il passaggio converge in quell’articolo non compare.

La differenza non sta nel codice: senza spec, il codice dei due passaggi arrivava in tutto a circa 1.000 righe. Il tempo se l’è preso il markdown. Eberhardt scrive che senza spec è stato circa 10 volte più veloce, e conclude così: «For now, the fastest path is still iterative prompting and review, not industrialised specification pipelines.» È l’esperienza di un solo sviluppatore su una sola app, non una misura generale.

Marmelab, novembre 2025. Secondo François Zaninotto, la spec tecnica contiene già del codice. Lo sviluppatore legge quel codice prima di eseguirlo e, siccome i bug ci saranno comunque, legge anche il codice finale: «As a result, review time doubles.» Nell’esempio che mostra, l’agente aveva segnato come completato il task «verify implementation» senza scrivere un solo unit test.

Thoughtworks Technology Radar, novembre 2025. Il Radar ha messo il metodo nell’anello «Assess» e ha scritto che alcuni strumenti producono «lengthy spec files that are hard to review». La nota si chiude con questa frase: «We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn’t scale.» Nell’edizione attuale del Radar la nota non c’è.

Tutte queste critiche parlano del carico di review: più markdown da leggere che codice, la stessa cosa letta due volte, un agente che non segue quanto scritto. E sono state scritte tutte nell’autunno 2025, sugli strumenti com’erano allora; la stessa Böckeler nota che gli strumenti cambiano molto in fretta.

Cosa vede di diverso chi lo difende?

Meg Kretz di Atomic Object dice nel suo articolo di maggio 2026 che la somiglianza sta nel documento e la differenza nel comportamento: «The difference comes down to four behaviors, which are observable, not philosophical.» Secondo lei, il waterfall usa i documenti come un cancello: si scrivono, si approvano, si congelano, si consegnano. Nello spec-driven development, invece, il documento è uno strumento di lavoro, scritto e riscritto insieme al codice. Questi sono i quattro comportamenti che elenca:

• Quando cambia la spec? Il giorno stesso in cui arriva un’informazione nuova, spesso entro la stessa ora.
• Come procedono design e spec? Nessuno dei due aspetta l’altro; procedono insieme, cambiandosi a vicenda.
• Quando è finito il lavoro? I requisiti Must/Should/May della spec sono i criteri di accettazione; quando sono soddisfatti, il lavoro è finito.
• Chi modifica la spec? Lo sviluppatore che si imbatte in un’ambiguità corregge la spec in quel momento; la correzione va nel commit insieme al codice.

Quello che Kretz chiama «test operativo» è, per la review, il punto centrale di questo articolo: spec e codice vanno nei commit della stessa pull request. «If specs lag code, the spec is documentation, not source of truth.»

Anche i professionisti riportano dei vantaggi, ma con cautela. La maggior parte dei partecipanti allo studio di Carnegie Mellon dice che le spec rendono più affidabile il lavoro dell’agente, ma non riesce a separare questo vantaggio dal miglioramento dei modelli nello stesso periodo. Un team che ha usato il metodo per mesi ha scritto di non poter dimostrare che avesse migliorato il codice. Secondo lo studio, l’SDD non elimina il costo: sposta token, tempo e carico mentale dall’implementazione alla pianificazione.

Da quegli articoli, anche gli strumenti sono cambiati. Spec Kit ha aggiunto a giugno 2026 un’estensione facoltativa per correggere i bug e, sempre a giugno 2026, ha documentato come conservare le spec a lavoro finito. Nella documentazione di Kiro oggi ci sono Quick Spec, senza passaggio di approvazione, e la modalità Plan, che non scrive file. Kiro descrive così uno dei casi in cui consiglia Quick Spec: «You've been defaulting to Vibe mode because the standard Spec flow felt too heavy».

Quando è utile e quando diventa un peso?

Il risultato dello studio di Carnegie Mellon è chiaro: la maggior parte dei professionisti non usa l’SDD per ogni lavoro, ma in base alla sua dimensione. Lo saltano per i lavori piccoli, i bug e gli script usa e getta. Un partecipante, a proposito di una correzione urgente in produzione, dice: «there is no time for spec-driven development and the whole flow». Altri decidono in base al rischio: se un errore costa caro e l’intenzione è chiara, scrivono una spec.

Le tracce nei repository vanno nella stessa direzione. I ricercatori hanno fatto classificare a un modello linguistico un campione di 1.000 spec; secondo la loro stima, il 82,0% delle spec descrive una nuova funzionalità. Anche la documentazione degli strumenti fa la stessa distinzione:

Il gradino di mezzo conta. Kiro consiglia la modalità Plan per lavori da 15 a 60 minuti, per cui una spec formale sarebbe troppo. Il piano resta nella chat e nessun file di spec entra nel repository; quindi non ci sarà nemmeno un documento rispetto a cui esaminare il codice in seguito. Per un lavoro piccolo non è un problema: quella pull request la esamini come al solito, guardando il diff e la descrizione.

Per correggere i bug, Spec Kit propone una strada a parte: diagnosi, correzione e verifica restano separate, e una correzione non verificata non conta come riuscita. Kiro, invece, ritiene sufficiente una correzione rapida in chat per i refusi o per modifiche di una riga ben comprese.

Come si separano codice e spec col tempo?

La maggior parte dei partecipanti allo studio di Carnegie Mellon ha raccontato che codice e spec si erano allontanati. I ricercatori distinguono due modi in cui succede e danno loro un nome: implementation drift (il codice si discosta dalla spec) e spec decay (la spec diventa obsoleta). Il loro esempio è per quanto tempo resta aperta una sessione:

In entrambi i casi il codice dice 60 minuti e la spec 30 minuti; uno strumento che confronta codice e spec vede i due casi allo stesso modo. A fare la differenza è quale dei due è sbagliato. Lo studio lo scrive chiaramente: le review programmate fatte da agenti o i test end-to-end nella CI possono mostrare che codice e spec non coincidono, ma non quale dei due è sbagliato. Quella decisione spetta a chi possiede l’intenzione.

L’implementation drift avviene nella pull request in cui si scrive il codice. Lo studio consiglia a chi crea strumenti di trasformare i criteri di accettazione in test che l’agente deve superare; il fatto che Kiro generi test property-based dai suoi requisiti EARS ne è un esempio. Lo spec decay invece avviene dopo, in un’altra pull request: una modifica che cambia un comportamento non tocca la spec che lo descrive. Lo studio lo vede soprattutto nelle spec vive (living spec), quando una modifica tocca anche un comportamento descritto da altre spec.

I controlli integrati negli strumenti girano alla fine del lavoro. Il passaggio converge di Spec Kit confronta il codice con spec, piano e task di quella funzionalità e aggiunge solo i task mancanti; dopo il risultato «Converged», la documentazione ti indirizza alla review o all’apertura di una pull request. Il passaggio verify di OpenSpec confronta il codice con i documenti della modifica prima dell’archiviazione e produce solo un report. In Kiro puoi chiedere in chat con #spec se il lavoro soddisfa i criteri di accettazione, e far spuntare i task completati con Sync Files.

Tutti questi controlli li esegue lo stesso agente di programmazione che ha fatto il lavoro; la documentazione che abbiamo letto non dice se il controllo vada fatto con un altro modello o in una sessione separata. Lo studio scrive anche di non aver potuto stabilire se qualcuno di questi strumenti controlli, a lavoro finito, che spec e codice coincidano ancora. La documentazione di Spec Kit chiama il rischio per nome: «The main risk is silent divergence.»

Come si esamina il codice rispetto alla sua spec?

I passaggi generali per esaminare una pull request scritta dall’IA li abbiamo descritti in un articolo a parte: fa quello che dice la descrizione? Cosa ha cambiato che non doveva? I test verificano davvero qualcosa? In un team che lavora con le spec si aggiungono alcune domande proprie della spec:

Spec e codice devono stare nella stessa pull request. Spec Kit dice di esaminare insieme il codice e le modifiche ai documenti, e OpenSpec di fare il commit della cartella della modifica insieme al codice. Se la spec arriva in una pull request separata, o non arriva affatto, non puoi vedere se l’intenzione è cambiata.

Leggi prima il diff della spec. OpenSpec dice che la parte più preziosa da leggere, quando si rivede il piano, è specs/, e fa una sola domanda: «Would you accept these requirements as done?» Nella pull request fai questa domanda al diff: quale criterio di accettazione è stato aggiunto, quale è cambiato, quale è stato cancellato. Anche lo studio consiglia agli strumenti di mostrare come diff le modifiche ai criteri di accettazione. Il codice lo leggi rispetto alla nuova spec che porta la pull request; la modifica alla spec, rispetto alla sua versione precedente sul branch di destinazione. Se il codice rispetta la spec lo possono verificare i test e gli strumenti; se la modifica alla spec è giusta può dirlo solo chi possiede l’intenzione.

I criteri di accettazione deve scriverli o approvarli una persona. Lo studio lo consiglia esplicitamente: «Practitioners should write or approve acceptance criteria even when agents produce the rest.» Non serve leggere tutta la spec con la stessa attenzione; secondo lo studio, la definizione del problema, le decisioni principali e i criteri di accettazione esprimono l’intenzione, il resto è contesto per l’agente. I partecipanti che fissavano i criteri di accettazione o rivedevano i test dell’agente non hanno citato la verifica come un problema; i ricercatori aggiungono di non poter dimostrare che questo abbia evitato dei difetti.

Ogni criterio deve avere un test. Una spunta nella lista dei task non è un test: nell’esempio di Zaninotto l’agente aveva chiuso il task di verifica senza scrivere un test. Abbina ogni criterio di accettazione a un test. Un criterio senza test è una promessa senza niente dietro nel codice.

Il controllo non deve farlo l’agente che ha fatto il lavoro. Secondo lo studio, quando un solo agente scrive spec, codice e test, un solo malinteso può passare a tutti e tre; per questo alcuni partecipanti dicono «an agent must not review its own implementation». Spec Kit traccia lo stesso confine per le sue checklist: il passaggio di implementazione non deve approvarle da solo. Lo studio dice anche quanto costa lasciare del tutto a un agente la review della spec: «Delegating spec review to an agent removes the one point where a person decides what the system should do.»

Controlla se si è rotta un’altra spec. Lo spec decay spesso comincia qui. Secondo lo studio, un agente che modifica una funzionalità può aggiungere un comportamento che soddisfa il task del momento e passa i suoi test, ma viola un vincolo di una spec più vecchia. Se altre spec descrivono il comportamento cambiato, vanno aggiornate anche loro nella stessa pull request.

Nelle tracce dei repository open source, in questi passaggi le persone si vedono poco. Nel campione di 266 repository dello studio, il 98,3% dei 36.888 file di spec con storia registrata ha un solo autore, e i bot hanno scritto il 68,5% dei 1.731 commenti inline sulle spec. Per dirla con i ricercatori, il secondo lettore di una spec, se c’è, di solito è un bot. Questi numeri non mostrano con quanta attenzione le persone leggano le spec, né se la review avvenga altrove; mostrano solo che la partecipazione umana registrata è poca.

Cosa vede della spec uno strumento di review?

diffox è uno strumento di code review composto da 17 agenti specializzati. Non legge le cartelle delle spec (specs/, .kiro/specs/, openspec/); porta nella review due testi. Il primo è il file delle regole nella radice del repository: cerca prima AGENTS.md e, se non c’è, CLAUDE.md. Non legge il file dal branch della pull request, ma dal branch in cui verrà fatto il merge, nello stato in cui era nel punto in cui il branch se ne è staccato; per questo una pull request che modifica il file delle regole viene esaminata con le regole vecchie finché non viene fatto il merge.

diffox prende dal file delle regole solo le frasi che esprimono un obbligo (come «must», «never», «deve», «vietato») e le passa agli agenti della review come le regole che stabiliscono cosa conta come errore. Uno degli agenti, House Rules Agent, cerca tra le righe modificate quella che viola una di queste regole e non si inventa regole che non siano nella lista. Il secondo testo è la descrizione della pull request: entra anche lei nel contesto che leggono gli agenti.

Per un team che lavora con le spec, questo significa che gli obblighi che vuoi controllare in ogni pull request devono stare nel file delle regole. Una frase come «Every database migration must include a rollback plan.», presa dall’esempio di constitution che Spec Kit dà per i progetti esistenti, viene usata come regola nella review se sta nel file delle regole; il file di constitution di Spec Kit in .specify/memory/, invece, diffox non lo legge. Scrivi anche nella descrizione della pull request quale spec hai implementato e quali criteri di accettazione sono cambiati; la stessa descrizione la legge anche la persona che fa la review.

Da dove cominciare nel tuo progetto?

Invece di estendere il metodo a tutto il repository in una volta, comincia in piccolo:

1. Scegli una sola funzionalità grande. Una funzionalità nuova con un’intenzione chiara e in cui un errore costa caro. Le correzioni di bug e i lavori piccoli continua a farli come sei abituato.
2. Scrivi tu i criteri di accettazione, o approvali uno per uno. Il resto può scriverlo l’agente. Uno schema come EARS o WHEN/THEN rende più facile trasformare un criterio in un test.
3. Decidi fin dall’inizio come vivrà la spec. Spec Kit elenca tre modelli e non ne rende nessuno predefinito: flow-back, in cui ogni documento può aggiornare gli altri; flow-forward, in cui ogni modifica apre una nuova cartella; e living spec, in cui la spec è l’unica fonte. Scrivi il modello scelto nella constitution o nelle note di onboarding del team.
4. Invia spec e codice nella stessa pull request. Comincia la review dal diff della spec.
5. Fai fare il controllo a un altro paio d’occhi. Il risultato di converge o verify dell’agente che ha fatto il lavoro è un punto di partenza; ai criteri di accettazione e al diff della spec deve guardare anche una persona.

Dopo un po’, guarda due cose: le spec continuano a cambiare insieme al codice? E dove va a finire il tempo di review? Il criterio di Kretz è semplice: se la spec resta indietro rispetto al codice, non è più la fonte di verità, ma documentazione.