Cosa è lo Sviluppo Guidato dalle Specifiche? La Specifica come Fonte di Verità

La specifica come fonte di verità, non come documento secondario.

Indice

Lo Spec-Driven Development è uno di quegli approcci a cui gli ingegneri del software hanno fatto ricorso in passato per poi abbandonarlo quando lo sforzo smetteva di dare i suoi frutti.

Ciò che è cambiato nel 2025 è l’arrivo degli agenti di coding basati su intelligenza artificiale, che ha reso costosa l’assenza di un’intenzione esplicita. I prompt sono effimeri. Le sessioni degli agenti vengono azzerate. Il codice cambia, ma il ragionamento che ne sta alla base scompare. La specifica (spec) è l’artefatto che impedisce che ciò accada.

What Is Spec-Driven Development – the spec as source of truth for AI coding

La Specifica Sta Diventando la Fonte di Verità

Per gran parte della storia dello sviluppo software, la specifica era o un artefatto di pianificazione temporaneo o un pensiero a posteriori. I requisiti vivevano nei ticket, le decisioni di progettazione nei thread di chat e il codice era la verità assoluta. La documentazione descriveva ciò che esisteva, ma solo dopo che era stato realizzato.

Lo Spec-Driven Development inverte questa relazione. La specifica diventa l’artefatto primario. Il codice è ciò che viene generato o verificato rispetto alla specifica, non il contrario.

Questa non è un’idea nuova. I metodi formali, il design-by-contract e il BDD (Behavior-Driven Development) contengono tutte versioni di questo concetto. Ciò che è nuovo è la motivazione pratica: gli agenti di coding basati su IA necessitano di un contesto esplicito e durevole per produrre output corretti e coerenti. I prompt sono troppo effimeri. La specifica è l’unico artefatto in grado di trasmettere l’intenzione attraverso le sessioni degli agenti, tra i membri del team e nel tempo.

Cosa Significa Realmente lo Spec-Driven Development

Lo Spec-Driven Development, solitamente abbreviato in SDD, è un flusso di lavoro in cui una specifica versionata guida o genera l’implementazione. La specifica viene scritta e revisionata prima che l’agente scriva il codice. Essa cattura:

  • Cosa costruire – problema dell’utente, obiettivi e non-obiettivi
  • Come appare un comportamento corretto – criteri di accettazione, casi limite, stati di errore
  • Come costruirlo – decisioni architetturali, modello dei dati, contratti API, vincoli di sicurezza
  • Come verificarlo – strategia di test, regole di convalida, tracciabilità rispetto ai requisiti

L’ultimo punto è facile da scrivere ma spesso trascurato nella pratica. Mantenere Specifiche, Test e Codice in Sincronia nello Sviluppo con IA illustra cosa significhi concretamente la tracciabilità rispetto ai requisiti in termini di dati: ID dei requisiti, ID delle decisioni di progettazione e test collegati alle pull request che li hanno implementati.

La specifica non è un documento una tantum. Viene aggiornata quando la realtà diverge dalla progettazione. Quando l’agente scopre durante l’implementazione qualcosa che la specifica aveva sbagliato, la specifica viene corretta prima di procedere. La specifica resta onesta perché viene trattata come codice.

Recenti lavori accademici formalizzano questa impostazione: i ricercatori descrivono l’SDD come il trattamento delle specifiche come fonte di verità e del codice come generato o verificato rispetto ad esse. L’interpretazione pratica è che la specifica è il record revisionato e durevole dell’intenzione che qualsiasi strumento umano o IA può leggere e fidarsi.

Tre termini catturano punti diversi dello spettro dell’uso delle specifiche:

Spec-first significa scrivere la specifica completa prima che inizi qualsiasi implementazione. Questa è l’interpretazione più rigorosa e quella più vicina al modello a cascata (waterfall) se non eseguita con attenzione.

Spec-anchored significa mantenere una specifica in sincronia con l’implementazione per tutta la durata del ciclo di vita della funzionalità. La specifica viene aggiornata man mano che le decisioni cambiano. Questa è la versione più pratica per la maggior parte dei team.

Spec-as-source significa generare o validare l’implementazione a partire dalla specifica, sia attraverso agenti IA sia attraverso strumenti che verificano il codice rispetto ai vincoli della specifica. Questa è la direzione verso cui si muovono strumenti come GitHub Spec Kit e Kiro, ciascuno con un diverso compromesso tra portabilità e guida integrata nell’IDE. I pacchetti di skill come Superpowers si collocano più vicino all’estremo spec-anchored – essi applicano automaticamente la disciplina di revisione piuttosto che generare direttamente codice dalla specifica.

Perché l’SDD Conta Ora

La risposta onesta è che l’SDD non è convincente per uno sviluppatore solitario che sta costruendo uno script di un giorno. Il sovraccarico (overhead) non ne vale la pena.

L’SDD diventa prezioso quando sono presenti tre condizioni: la funzionalità è abbastanza grande da estendersi su più sessioni, l’agente deve prendere decisioni che influenzano l’architettura e il lavoro verrà revisionato o continuato da qualcun altro.

Tutte e tre le condizioni sono sempre più comuni con lo sviluppo assistito dall’IA.

Gli LLM necessitano di contesto, non solo di prompt. Un modello che riceve un prompt vago prende decisioni vaghe. Un modello che riceve una specifica revisionata con vincoli espliciti, non-obiettivi e criteri di accettazione prende decisioni migliori ed è più facile da correggere se devia. Questo si collega a come funzionano recupero e rappresentazione: fornire a un’agente una specifica versionata è una forma di recupero strutturato dell’intenzione del progetto.

La generazione di codice è economica; decidere cosa costruire è ancora difficile. Il collo di bottiglia nello sviluppo assistito dall’IA non è più la digitazione – è sapere cosa costruire e come vincolare l’agente. L’SDD sposta lo sforzo dove conta: specificare chiaramente l’intenzione prima che inizi la generazione.

I prompt sono effimeri. L’agente non ricorda cosa gli hai detto nell’ultima sessione. Una specifica versionata archiviata nel repository sì. Ogni nuova sessione può leggere la stessa specifica e implementare rispetto alla stessa intenzione senza dover ristabilire il contesto da zero.

**Vibe coding è più veloce per lavori usa-e-getta; SDD vs Vibe Coding copre quando aggiungere specifiche e quando continuare a promptare liberamente.

Artefatti Principali

L’SDD produce quattro tipi di artefatti. Ciascuno riduce un diverso tipo di ambiguità prima che l’agente tocchi il codice:

  • Specifiche dei requisiti – problema, utenti, obiettivi, non-obiettivi, criteri di accettazione
  • Specifiche di progettazione – architettura, modello dei dati, contratti API, vincoli di sicurezza per questa funzionalità
  • Piano di lavoro – piccole fette di implementazione con dipendenze e criteri di validazione
  • Record di tracciabilità – mappatura dai criteri di accettazione ai test, dalle decisioni di progettazione ai file, dai task ai commit

Come produrli e revisionarli passo dopo passo – specificare, pianificare, task, implementare, validare – è coperto in Workflow dello Spec-Driven Development dai Requisiti al Codice. Una funzionalità semplice può coprire tutte e quattro le aree in un breve file markdown. L’abitudine conta più del formato.

Come l’SDD Differisce dalla Documentazione

La confusione più comune è trattare gli artefatti SDD come documentazione. Non sono documentazione nel senso convenzionale.

La documentazione descrive. Ti dice cosa fa il sistema, come usarlo e cosa contiene. Viene scritta a posteriori e aggiornata quando il sistema cambia.

Le specifiche vincolano. Una specifica dice all’agente cosa è autorizzato a costruire e cosa non è autorizzato a fare. È autoritativa prima che l’implementazione inizi. Viene validata dopo che l’implementazione è completata. Una specifica che descrive ciò che è stato effettivamente costruito – piuttosto che vincolare ciò che dovrebbe essere costruito – ha già fallito il suo scopo.

Le specifiche eseguibili guidano generazione e validazione. Le migliori specifiche SDD sono sufficientemente vicine a essere leggibili da macchina affinché un agente possa implementare rispetto ad esse e una suite di test possa verificarle. Un criterio di accettazione scritto come “il endpoint deve rifiutare le richieste non autenticate con una risposta 401” è una specifica eseguibile; “l’endpoint è sicuro” è documentazione.

Decision Records – ADR, PDR e DDR – sono complementari agli artefatti SDD ma servono a uno scopo diverso. I decision records catturano perché una scelta è stata fatta e cosa è stato scartato. Le specifiche SDD catturano cosa costruire e come verificarlo. Entrambi appartengono al repository. Insieme forniscono agli agenti IA il quadro completo: l’intenzione attuale e il ragionamento che ne sta alla base.

Come l’SDD Differisce dal TDD

Il Test-Driven Development (TDD) e lo Spec-Driven Development (SDD) vengono spesso confusi perché entrambi producono artefatti espliciti prima che esista il codice. La differenza sta nel punto di partenza.

Il TDD inizia con i test. Si scrive un test fallente che descrive il comportamento desiderato, poi si scrive il minimo codice necessario per farlo passare. Il TDD è un ciclo di feedback a livello di unità. Produce buoni test ma non risponde alla domanda se si stia costruendo la cosa giusta.

L’SDD inizia con l’intenzione. Prima che esistano i test, prima che l’architettura sia decisa, la specifica risponde a: chi ha questo problema, come appare un comportamento corretto, cosa è esplicitamente fuori scope. La specifica informa poi quali test scrivere, motivo per cui un buon SDD e un buon TDD sono complementari piuttosto che in competizione.

Un modo pratico per pensarla: l’SDD guida il TDD. I criteri di accettazione nella specifica diventano gli scenari di test. La specifica di progettazione identifica i confini di integrazione che necessitano di test contrattuali. Il piano di lavoro identifica quali comportamenti a livello di unità necessitano di copertura di test prima che l’agente li implementi.

Come l’SDD Differisce dal BDD

Il Behavior-Driven Development (BDD) utilizza scenari in linguaggio naturale – tipicamente in formato Gherkin – per descrivere il comportamento atteso dal punto di vista dell’utente. Questi scenari colmano il divario tra l’intenzione di business e l’implementazione tecnica.

L’SDD è più ampio. Include descrizioni comportamentali (che possono usare linguaggio stile BDD o prosa semplice) ma copre anche decisioni architetturali, modelli dei dati, vincoli di sicurezza, pianificazione dei task e tracciabilità. Il BDD può essere un formato utile per scrivere criteri di accettazione all’interno di una specifica dei requisiti SDD. La specifica è il contenitore; gli scenari BDD sono un modo per scrivere ciò che va al suo interno.

La distinzione conta nella pratica: gli strumenti BDD si concentrano sul rendere gli scenari eseguibili. La pratica SDD si concentra sul rendere l’intenzione durevole – attraverso gli strumenti, attraverso le sessioni e attraverso i membri del team.

Come l’SDD Differisce dai Metodi Formali

I metodi formali utilizzano notazione matematica e verifica automatica per dimostrare proprietà di sistemi software. Sono estremamente rigorosi ed estremamente costosi per la maggior parte dei contesti di sviluppo di produzione.

L’SDD non richiede notazione formale. Un file markdown con criteri di accettazione e decisioni architetturali è una specifica. Vincola senza essere matematicamente formale. Il livello di rigore scala con le posta in gioco: una specifica per un servizio di fatturazione dovrebbe essere più precisa e revisionata con più cura di una specifica per una pagina di documentazione.

La relazione è uno spettro:

  • Specifica in prosa informale (SDD minimo vitale)
  • Markdown strutturato con criteri di accettazione e non-obiettivi
  • Specifica leggibile da macchina con validazione dello schema
  • Test contrattuali derivati direttamente dalla specifica
  • Specifica formale con prova automatica

La maggior parte dei team opera nella parte centrale di questo spettro. L’obiettivo non è la rigore matematico – è rendere l’intenzione esplicita abbastanza affinché un agente IA possa implementare rispetto ad essa e un revisore umano possa verificarne il risultato.

Benefici dello Spec-Driven Development

Meno deriva dell’intenzione. La specifica è il riferimento. Quando l’agente devia – e lo farà – il revisore ha qualcosa con cui confrontare l’implementazione. Senza una specifica, la deriva è invisibile finché qualcosa non si rompe.

Output IA migliori. Gli agenti forniti di vincoli espliciti, non-obiettivi e criteri di accettazione producono implementazioni più vicine a quanto intenduto e più facili da correggere quando sbagliano. La qualità del contesto determina direttamente la qualità dell’output.

Revisione più facile. Una pull request collegata a una specifica è più facile da revisionare di una pull request che richiede al revisore di ricostruire l’intenzione dal codice. La specifica è la checklist di revisione.

Allineamento del team. Quando più persone o agenti lavorano sulla stessa funzionalità, la specifica è il contratto condiviso. Senza di essa, ciascun contributore ottimizza localmente e i pezzi potrebbero non combaciare.

Pianificazione dei test migliore. I criteri di accettazione nella specifica si mappano direttamente sui casi di test. La copertura dei test diventa una questione di copertura delle specifiche: ogni criterio di accettazione è coperto da almeno un test?

Passaggio di consegne durevole. Quando una funzionalità cambia mani – tra ingegneri, tra sessioni di agenti, tra sprint – la specifica è l’artefatto di passaggio. Cattura cosa è stato deciso, cosa era fuori scope e cosa resta da validare.

Costi dello Spec-Driven Development

Sforzo iniziale. Scrivere una buona specifica prima di scrivere qualsiasi codice richiede tempo. Per funzionalità piccole, questo sovraccarico è reale e a volte non ne vale la pena.

Falsa sicurezza. Una specifica che esiste ma non è validata rispetto all’implementazione dà un falso senso di correttezza. Le specifiche obsolete sono a volte peggio di nessuna specifica: ingannano i revisori e gli agenti che le leggono.

Specifiche obsolete. Le specifiche deragliano quando il team le tratta come artefatti di pianificazione piuttosto che come documenti vivi. Aggiornare la specifica quando l’implementazione diverge dalla progettazione non è opzionale – è ciò che distingue l’SDD dalla documentazione che si accumula e marcisce.

Burocrazia generata. Gli agenti IA possono generare rapidamente liste di task esaustive e specifiche verbosi. Una specifica di 200 task generata in trenta secondi non è una specifica utile – è un generatore di burocrazia. Un buon SDD richiede giudizio su cosa specificare e cosa lasciare implicito.

Vincolo agli strumenti. Alcuni strumenti SDD sono opinati riguardo a formato, struttura dei file e flusso di lavoro. Una specifica scritta in un formato proprietario è più difficile da portare attraverso gli strumenti rispetto a un file markdown con intestazioni chiare e criteri di accettazione.

Conclusione

Lo Spec-Driven Development non è una nuova metodologia. È una vecchia disciplina che torna a essere pratica perché il costo dell’intenzione implicita è ora visibile nel codice generato dall’IA.

La disciplina è semplice: scrivere giù cosa si intende costruire, revisionato e versionato, prima che l’agente lo costruisca. Mantenere quel record onesto aggiornandolo quando la realtà diverge. Usarlo come riferimento per revisione, test e passaggio di consegne.

La specifica non è magia. Una specifica che non è validata diventa il tipo di documentazione più costoso: quella che inganna con sicurezza. Un buon SDD è la pratica di mantenere le specifiche oneste – abbastanza piccole da essere mantenute, abbastanza precise da vincolare e abbastanza durevoli da sopravvivere a qualsiasi singola sessione di agente.

L’SDD si colloca all’incrocio tra la pratica della documentazione, l’architettura dei test e la progettazione del codice – tutto coperto nel cluster App Architecture in Production insieme ai decision records, al design API e ai pattern di accesso ai dati.

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.