Spec-driven development con i coding agent: guida pratica dal vibe coding alle specifiche

Chiedi a un agente di coding “aggiungi l’esportazione degli ordini in Excel” e dopo dieci minuti hai un pulsante, un file scaricabile e un centinaio di righe di codice. Poi scopri che esporta solo la pagina corrente, che le date sono in formato americano e che i filtri attivi vengono ignorati. Nessuno di questi requisiti era nella richiesta. L’agente ha fatto esattamente quello che gli hai chiesto, non quello che volevi.

Lo spec-driven development nasce per colmare questa distanza. Invece di affidarsi a una richiesta di una riga, si scrive una specifica breve e strutturata che descrive cosa costruire, e l’agente la usa come riferimento per pianificare, implementare e verificare. A settembre DeepLearning.AI ha pubblicato con JetBrains un corso completo sul tema, e Matt Pocock ha rilasciato una skill /implement-spec pensata per far completare all’agente grandi blocchi di lavoro a partire da una specifica.

In questa guida vediamo cos’è davvero lo spec-driven development, come scrivere una specifica utile, quale flusso seguire e, soprattutto, quando non serve.

Per le aziende che commissionano software, lo spec-driven development ha un vantaggio immediato: rende esplicito e verificabile ciò che si sta comprando. La specifica diventa il punto di incontro tra chi conosce il business e chi sviluppa, e il documento con cui si controlla il risultato alla consegna.

In breve

• Lo spec-driven development (SDD) usa una specifica scritta, versionata nel repository, come fonte di verità per il lavoro dell’agente.
• Il flusso tipico è: specifica, piano, task, implementazione, verifica, con l’umano che approva a ogni passaggio.
• Esistono tre livelli di rigore: spec-first, spec-anchored e spec-as-source. Quasi tutti oggi lavorano al primo livello.
• Strumenti come GitHub Spec Kit, Kiro e OpenSpec strutturano il processo, ma una cartella di file markdown e qualche skill bastano per iniziare.
• Una buona specifica descrive comportamento, vincoli e criteri di accettazione verificabili, non l’implementazione.
• Per bug piccoli e modifiche banali lo SDD è eccessivo: la scelta dipende dalla dimensione del lavoro.
• Per chi decide: una specifica breve con criteri di accettazione è lo strumento più efficace per controllare tempi, costi e qualità di un progetto sviluppato con gli agenti, anche senza competenze tecniche.

Che cos’è lo spec-driven development

Lo spec-driven development è un approccio in cui una specifica scritta precede il codice e ne guida la generazione e la verifica. La specifica è un documento breve, di solito in markdown, che descrive il comportamento atteso, i vincoli e i criteri con cui si considera il lavoro completato.

L’idea non è nuova. Metodi formali, design by contract e behavior-driven development (BDD, con strumenti come Cucumber) mettono da decenni la specifica al centro. Cosa cambia con gli agenti? Due cose.

• L’agente non ha memoria tra le sessioni. Una specifica scritta è l’unico artefatto che porta l’intenzione da una sessione all’altra, da una persona all’altra e nel tempo.
• Scrivere codice costa poco, capire cosa scrivere no. Quando l’implementazione richiede minuti, il collo di bottiglia diventa la chiarezza dei requisiti.

Il paper Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants, pubblicato a gennaio su arXiv, lo descrive come un ritorno a un’idea antica resa praticabile dagli assistenti AI, e propone un quadro decisionale per capire quando conviene. In italiano si trova una buona introduzione concettuale su glukhov.org, mentre mancano guide operative.

Cosa cambia per chi commissiona software

Con gli agenti, scrivere il codice costa sempre meno. Il valore si sposta su ciò che viene prima e dopo: capire cosa serve e verificare che sia stato fatto. Per un’azienda cliente questo cambia il modo di lavorare con il fornitore o con il team interno.

Dal brief alla specifica

Il classico brief (“vogliamo un portale per i rivenditori”) lascia troppe decisioni a chi sviluppa. Una specifica obbliga a chiarire chi usa la funzionalità, con quali permessi, con quali volumi, con quali eccezioni. Chi conosce il processo (l’amministrazione, l’ufficio commerciale, la logistica) è la persona giusta per scrivere o validare il contesto e i criteri di accettazione. Non serve competenza tecnica: serve conoscenza del lavoro.

Preventivi più affidabili

Una specifica chiara riduce l’incertezza, e quindi i margini di sicurezza nei preventivi e le discussioni sulle varianti. Se una richiesta non è nella specifica, è una modifica; se è nella specifica ma non funziona, è un difetto. La distinzione diventa evidente per entrambe le parti.

Un collaudo semplice

I criteri di accettazione sono già una lista di collaudo. Alla consegna si verificano uno per uno, con i dati e gli esempi scritti nella specifica. Il collaudo diventa una verifica oggettiva invece di una sensazione.

Documentazione che resta

Le specifiche conservate nel repository diventano la documentazione funzionale del sistema: cosa fa ogni parte e perché. È preziosa per la manutenzione, per l’arrivo di nuove persone e per un eventuale cambio di fornitore.

Domande da fare al fornitore

• Vedremo e approveremo la specifica prima che inizi lo sviluppo?
• I criteri di accettazione sono verificabili da noi, senza competenze tecniche?
• Come gestite le modifiche alla specifica in corso d’opera?
• Dove resteranno le specifiche a fine progetto?

Perché il vibe coding non basta

Il vibe coding, cioè descrivere a voce o in chat cosa si vuole e accettare quello che l’agente produce, funziona bene per prototipi, script e piccoli esperimenti. Su un prodotto reale mostra tre limiti.

L’intenzione si perde

Le decisioni prese durante una conversazione restano nella conversazione. Quando la sessione si chiude, o quando il contesto viene compattato, spariscono. La volta successiva l’agente riparte da zero e può prendere decisioni diverse.

Il debito cognitivo cresce

Se nessuno ha scritto cosa doveva fare una funzionalità, nessuno può verificare se lo fa. Il codice diventa l’unica documentazione, e il codice generato velocemente tende a essere letto poco. Il corso di DeepLearning.AI chiama questo problema cognitive debt.

Il problema di comunicazione

Matt Pocock lo ha riassunto nel video “Don’t underestimate the communication barrier”: il limite principale non è il modello, è la distanza tra ciò che hai in testa e ciò che l’agente sa di te e del progetto. Una specifica è il modo più efficace per ridurre quella distanza.

I tre livelli di rigore

Birgitta Böckeler di Thoughtworks, nell’analisi Understanding Spec-Driven Development, distingue tre livelli. Sono utili per capire cosa promettono gli strumenti e cosa fanno davvero.

Livello	Cosa succede alla specifica	Chi modifica il codice	Maturità oggi
Spec-first	Scritta prima del task, usata per il task, poi spesso abbandonata	Agente e persone	Diffuso e praticabile
Spec-anchored	Mantenuta e aggiornata insieme alla funzionalità nel tempo	Agente e persone, con la specifica sempre allineata	Possibile, richiede disciplina
Spec-as-source	È l’artefatto principale; il codice viene rigenerato	Solo l’agente; le persone modificano solo la specifica	Sperimentale

Il nostro consiglio è partire dal livello spec-first e puntare allo spec-anchored per le parti stabili e importanti del prodotto. Lo spec-as-source, oggi, somma la rigidità dei vecchi approcci model-driven alla non determinazione dei modelli: stessa specifica, codice diverso a ogni generazione.

Il flusso di lavoro: dalla costituzione alla verifica

Gli strumenti usano nomi diversi, ma il flusso è quasi sempre lo stesso.

0. La costituzione del progetto

Un documento scritto una volta, insieme all’agente, che descrive missione del prodotto, stack tecnologico, principi non negoziabili e roadmap. GitHub Spec Kit lo chiama constitution; il corso di DeepLearning.AI lo usa come primo passo. Ha lo stesso ruolo del file di istruzioni del progetto di cui abbiamo parlato nell’articolo sull’harness engineering, ma con un taglio più di prodotto che tecnico.

1. Specifica della funzionalità

Cosa deve fare, per chi, in quali condizioni, con quali vincoli. Nessuna scelta implementativa, se non quelle già decise.

2. Piano tecnico

L’agente legge la specifica e il codice esistente e propone come implementarla: file da toccare, modelli dati, componenti, rischi. La persona rivede il piano prima di procedere. È il momento più economico per correggere un malinteso.

3. Scomposizione in task

Il piano viene diviso in task piccoli e verificabili, ognuno con un criterio di completamento. I task diventano la lista di lavoro dell’agente.

4. Implementazione

L’agente lavora un task alla volta. Ogni task si chiude con i controlli del progetto (lint, tipi, test) e un commit.

5. Verifica rispetto alla specifica

Alla fine si confronta il risultato con i criteri di accettazione della specifica, non solo con i test. Se emergono differenze, si corregge il codice o si aggiorna la specifica, consapevolmente.

6. Ripianificazione

Tra una funzionalità e l’altra si rivede la roadmap alla luce di quanto appreso. Il corso di DeepLearning.AI dedica una lezione a questo passaggio, spesso dimenticato.

Come scrivere una specifica che l’agente può usare

Una specifica utile è breve, concreta e verificabile. Ecco il template che usiamo nei progetti, adattabile a qualsiasi strumento.

# Specifica: Esportazione ordini in Excel

## Contesto
Il reparto amministrazione esporta ogni lunedì gli ordini della settimana
per la riconciliazione con il gestionale contabile.

## Comportamento atteso
- Dalla pagina /ordini l'utente con ruolo "amministrazione" vede il pulsante "Esporta".
- L'esportazione include TUTTI gli ordini che rispettano i filtri attivi,
  non solo la pagina visualizzata.
- Il file è .xlsx, un ordine per riga, colonne nell'ordine indicato sotto.

## Colonne
numero_ordine | data (gg/mm/aaaa, fuso Europe/Rome) | cliente | partita_iva |
imponibile | iva | totale | stato

## Vincoli
- Fino a 20.000 righe senza timeout: generazione asincrona oltre 2.000 righe,
  con notifica quando il file è pronto.
- Importi con due decimali e separatore decimale italiano.
- Nessun dato personale oltre a quelli elencati.

## Fuori ambito
- Esportazione in CSV o PDF.
- Programmazione automatica delle esportazioni.

## Criteri di accettazione
- [ ] Con il filtro "stato = spedito" il file contiene solo ordini spediti.
- [ ] Con 5.000 ordini il file arriva via notifica entro 2 minuti.
- [ ] Un utente senza ruolo "amministrazione" non vede il pulsante e riceve 403 dall'API.
- [ ] Le date di ordini creati alle 23:30 del 31/03 risultano 31/03, non 01/04.

## Domande aperte
- Serve tracciare chi ha esportato e quando? (da confermare con l'amministrazione)

Alcune regole che rendono una specifica efficace.

• Descrivi il comportamento, non l’implementazione. “Generazione asincrona oltre 2.000 righe” è un vincolo; “usa una coda Redis con BullMQ” è una scelta tecnica che può stare nel piano.
• Scrivi i criteri di accettazione come test. Se un criterio non può essere verificato, riscrivilo. Gli esempi con valori concreti (il 31 marzo alle 23:30) catturano i casi limite meglio delle descrizioni generali.
• Dichiara cosa è fuori ambito. Gli agenti tendono ad aggiungere funzionalità “utili”. Una sezione esplicita riduce il lavoro non richiesto.
• Tieni le domande aperte visibili. Una specifica non deve essere completa per iniziare, ma le incertezze devono essere dichiarate.
• Una pagina, non dieci. Se la specifica supera le due pagine, probabilmente la funzionalità va divisa.

Farsi intervistare dall’agente

Una tecnica che funziona molto bene è invertire i ruoli: invece di scrivere la specifica da soli, chiedi all’agente di intervistarti finché non ha abbastanza informazioni. Matt Pocock ha reso popolare questo approccio con la skill /grill-me: l’agente pone domande una alla volta su casi limite, vincoli e priorità, e alla fine produce la specifica. Nel video When should you NOT use /grill-me? propone anche un albero decisionale su quando usarla, che riprendiamo più avanti.

Prima di scrivere codice, intervistami per costruire una specifica.
Fai una domanda alla volta. Concentrati su: utenti e permessi, casi limite,
volumi di dati, cosa è fuori ambito, come verificheremo il risultato.
Quando hai abbastanza informazioni, scrivi la specifica in specs/NOME.md
usando il template in specs/_template.md e fermati.

Dalla specifica ai task: un esempio completo

Vediamo, con un esempio illustrativo, come la specifica dell’esportazione si trasforma in lavoro concreto per l’agente. Dopo aver letto specifica e codice, l’agente propone un piano. Un piano tipico per questa funzionalità indica: un endpoint che accoda la generazione del file, un worker che costruisce il foglio Excel leggendo gli ordini a blocchi, una notifica in app con il link di download, il controllo del ruolo sia nell’interfaccia sia nell’API.

In revisione emergono spesso punti da correggere. Due classici. Il primo: l’agente propone di riusare la query della tabella paginata, che però applica un limite di cinquanta righe; serve una query dedicata senza paginazione, con i filtri condivisi. Il secondo: il piano non dice nulla sulla scadenza dei file generati; si aggiunge alla specifica una riga (“il link resta valido 24 ore”) e si lascia la domanda sulla tracciabilità a una decisione del cliente.

Il piano approvato diventa sei task, ognuno con il proprio criterio di completamento:

1. Query degli ordini filtrati senza paginazione, con test sui filtri esistenti.
2. Generazione del file .xlsx con colonne, formati di data e importi in italiano, con test sul caso del 31 marzo alle 23:30.
3. Endpoint di richiesta esportazione con controllo del ruolo e risposta 403 per gli altri utenti.
4. Worker asincrono per le esportazioni oltre 2.000 righe, con test su 5.000 ordini.
5. Notifica in app con link valido 24 ore.
6. Pulsante nella pagina /ordini visibile solo al ruolo amministrazione, con test end-to-end.

Ogni task si chiude con un commit e con i controlli del progetto verdi. Alla fine si verificano i quattro criteri di accettazione su dati di prova. È in questo passaggio che emergono errori come un fuso orario gestito in un percorso del codice ma non nell’altro (per esempio nelle esportazioni piccole, generate senza passare dal worker). Una correzione di pochi minuti, scoperta prima del rilascio e non da un cliente. È esattamente il tipo di errore che una richiesta di una riga non fa emergere.

Gli strumenti: Spec Kit, Kiro, OpenSpec e alternative

Esistono decine di framework per lo spec-driven development. Ecco quelli più usati e le loro caratteristiche.

Strumento	Tipo	Flusso	Adatto a
GitHub Spec Kit	CLI open source, funziona con Copilot, Claude Code, Gemini CLI e altri	constitution, specify, plan, tasks, implement	Team che vogliono un processo completo e uniforme
Kiro	IDE basato su VS Code	requisiti (user story e criteri), design, task	Chi preferisce un’esperienza integrata nell’editor
OpenSpec	Framework open source leggero	Proposte di modifica alle specifiche, poi applicazione	Progetti esistenti che evolvono per modifiche incrementali
Skill personalizzate	File markdown nel repository	Definito dal team	Chi vuole controllo totale e portabilità tra agenti

GitHub ha presentato Spec Kit nel post Spec-driven development with AI. È lo strumento più citato e un buon punto di partenza per capire il processo, anche se si decide poi di costruirne una versione più leggera.

Il corso di DeepLearning.AI dedica le lezioni finali a costruire il proprio flusso e a renderlo indipendente dall’agente, impacchettandolo come skill. È l’approccio che preferiamo: le specifiche e il flusso restano nel repository, l’agente si può cambiare.

Quando usarlo e quando no

Il limite più evidente degli strumenti di SDD è che impongono lo stesso flusso a qualsiasi lavoro. Per un bug di una riga, generare costituzione, specifica, piano e task è burocrazia. Böckeler lo sottolinea: un flusso fisso è eccessivo per i bug piccoli e forse anche per funzionalità medie.

Riprendendo l’albero decisionale di Matt Pocock, la scelta dipende dalla dimensione del lavoro.

Dimensione	Esempio	Approccio consigliato
Piccola	Correggere un errore di validazione, cambiare un testo	Richiesta diretta all’agente, verifica con i test
Media	Un nuovo filtro, un’esportazione, un’integrazione semplice	Intervista breve, specifica di una pagina, piano rivisto
Grande	Un nuovo modulo, una migrazione, un’integrazione complessa	Specifica completa, piano, task, implementazione per fasi con verifiche intermedie
Esplorativa	Non sai ancora cosa vuoi	Prototipo usa-e-getta in vibe coding, poi specifica basata su ciò che hai imparato

L’ultima riga è importante. Lo SDD non è in contrasto con la sperimentazione: un prototipo rapido è spesso il modo migliore per capire cosa scrivere nella specifica. L’errore è portare il prototipo in produzione senza passare dalla specifica.

Spec-driven development su un progetto esistente

La maggior parte dei progetti reali non parte da zero. Introdurre lo SDD in un codice esistente richiede un approccio diverso.

1. Non specificare tutto. Scrivere specifiche per l’intero sistema esistente è un progetto a sé e raramente vale la pena.
2. Parti dalle modifiche. Ogni nuova funzionalità o modifica significativa ha la sua specifica. Col tempo le parti più attive del sistema saranno documentate.
3. Fai estrarre le specifiche all’agente. Per le aree critiche, chiedi all’agente di leggere codice, test e documentazione e di scrivere una specifica del comportamento attuale. Poi rivedila: spesso emergono comportamenti che nessuno ricordava.
4. Usa le specifiche come test di regressione. I criteri di accettazione delle specifiche estratte diventano test che proteggono il comportamento esistente durante le modifiche.

Errori comuni

Specifiche troppo lunghe

Dieci pagine di requisiti generate dall’agente e approvate senza leggerle. Böckeler osserva che il markdown generato dagli strumenti è spesso ripetitivo e faticoso da rivedere. Una specifica che nessuno legge non è una specifica.

Implementazione travestita da specifica

Nomi di classi, struttura delle cartelle, scelte di librerie: tutto nella specifica. Così l’agente non può proporre soluzioni migliori, e la specifica invecchia a ogni refactoring.

Criteri di accettazione vaghi

“L’esportazione deve essere veloce” non si può verificare. “5.000 ordini entro 2 minuti” sì.

Specifica e codice che divergono

La specifica dice una cosa, il codice ne fa un’altra, e nessuno sa quale sia giusta. Se adotti il livello spec-anchored, ogni pull request che cambia il comportamento deve aggiornare anche la specifica.

Saltare la revisione del piano

Il piano tecnico è il punto in cui un malinteso costa cinque minuti invece di cinque ore. Approvarlo senza leggerlo annulla gran parte del valore del processo.

Portarlo in produzione nel team

• Dove stanno le specifiche: in una cartella del repository (per esempio specs/), versionate con il codice. Mai solo in un tool esterno.
• Chi le scrive: non solo gli sviluppatori. Le sezioni di contesto e criteri di accettazione sono il punto di contatto naturale con chi conosce il dominio, come l’amministrazione nell’esempio.
• Revisione: la specifica entra nella pull request. Chi rivede il codice rivede anche la specifica.
• Collegamento con i ticket: il ticket rimanda alla specifica, non la duplica.
• Misura: confronta per qualche settimana il tempo speso in correzioni dopo il merge, con e senza specifica. È il dato che convince il team, più di qualsiasi teoria.

Stai costruendo un prodotto con gli agenti e vuoi un processo che regga nel tempo? Nello sviluppo di web app e nei progetti di software su misura usiamo specifiche leggere e verificabili, condivise con il cliente prima di scrivere codice.

Da dove partire questa settimana

1. Crea una cartella specs/ con un template come quello di questo articolo.
2. Scegli la prossima funzionalità di dimensione media e fatti intervistare dall’agente per scrivere la specifica.
3. Chiedi all’agente un piano tecnico e rivedilo prima di dare il via libera.
4. Fai implementare un task alla volta, con i controlli del progetto a ogni passo.
5. A fine lavoro verifica i criteri di accettazione uno per uno e annota quante correzioni sono servite.

Se le sessioni con l’agente diventano lunghe, applica anche le tecniche di context engineering: la specifica e il piano sono anche il miglior riepilogo per ripartire con una sessione pulita.

Checklist di una buona specifica

• Spiega il contesto: chi usa la funzionalità e perché.
• Descrive il comportamento atteso, non l’implementazione.
• Elenca i vincoli misurabili: volumi, tempi, permessi, formati.
• Dichiara cosa è fuori ambito.
• Ha criteri di accettazione verificabili, con esempi concreti.
• Include i casi limite noti, come fusi orari, valori vuoti, permessi.
• Rende visibili le domande aperte.
• Sta in una o due pagine.
• È versionata nel repository e collegata al ticket.
• Viene aggiornata quando il comportamento cambia.

Domande frequenti

Fonti e approfondimenti

• DeepLearning.AI e JetBrains: Spec-Driven Development with Coding Agents
• Birgitta Böckeler: Understanding Spec-Driven Development (Kiro, spec-kit, Tessl)
• Piskala: Spec-Driven Development, From Code to Contract (arXiv)
• GitHub Spec Kit
• Thoughtworks Technology Radar: spec-driven development
• Video del corso completo su YouTube

Hai un’idea da trasformare in software e vuoi partire con il piede giusto? Parliamone: la prima cosa che costruiamo insieme è una specifica chiara.