Cos'è lo sviluppo guidato dalle specifiche? La specifica come fonte di verità

La specifica come unica fonte di verità, non un documento accessorio.

Indice

Lo Sviluppo Guidato dalle Specifiche è uno di quei concetti a cui gli ingegneri del software hanno cercato di arrivare 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 AI, che hanno reso costosa l’assenza di un intento esplicito. I prompt sono effimeri. Le sessioni degli agenti si resettano. Il codice cambia, ma il ragionamento sottostante scompare. La specifica è l’artefatto che impedisce che ciò accada.

Cos’è lo Spec-Driven Development – la specifica come fonte di verità per l’AI coding

La Specifica Sta Diventando la Fonte di Verità

Per gran parte della storia dello sviluppo software, la specifica è stata o un artefatto di pianificazione temporaneo o un pensiero tardivo. I requisiti vivevano nei ticket, le decisioni di design nei thread di chat, e il codice era la verità fondamentale. La documentazione descriveva ciò che esisteva a posteriori.

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.

Non è un’idea nuova. I metodi formali, il design-by-contract e il BDD contengono tutte versioni di questo concetto. Ciò che è nuovo è la motivazione pratica: gli agenti di coding AI hanno bisogno di un contesto esplicito e duraturo per produrre output corretti e coerenti. I prompt sono troppo effimeri. La specifica è l’unico artefatto che può trasportare l’intento 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 dati, contratti API, vincoli di sicurezza
  • Come verificarlo – strategia di test, regole di validazione, tracciabilità fino ai requisiti

La specifica non è un documento una tantum. Viene aggiornata quando la realtà differisce dal design. Quando l’agente scopre qualcosa durante l’implementazione che la specifica ha sbagliato, la specifica viene corretta prima di continuare. La specifica rimane onesta perché viene trattata come codice.

Recenti lavori accademici formalizzano questa impostazione: i ricercatori descrivono SDD come il trattamento delle specifiche come fonte di verità e del codice come generato o verificato rispetto a esse. L’interpretazione pratica è che la specifica è il registro duraturo e revisionato dell’intento che qualsiasi essere umano o strumento AI può leggere e fidarsi.

Tre termini catturano diversi punti sullo 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 fatta con cura.

Spec-anchored significa mantenere una specifica in sincrono con l’implementazione durante tutto il 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 dalla specifica, sia attraverso agenti AI che attraverso strumenti che controllano il codice rispetto ai vincoli della specifica. Questa è la direzione verso cui stanno andando strumenti come GitHub Spec Kit e Kiro.

Perché SDD è Importante Ora

La risposta onesta è che SDD non è convincente per uno sviluppatore solitario che sta costruendo uno script da un giorno. Il sovraccarico non ne vale la pena.

SDD diventa prezioso quando sono presenti tre condizioni: la funzionalità è abbastanza grande da coprire 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 da AI.

Gli LLM hanno bisogno 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 quando devia. Questo si collega al funzionamento di recupero e rappresentazione: dare a un’agente una specifica versionata è una forma di recupero strutturato dell’intento del progetto.

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

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

Vibe coding funziona finché non smette. Per prototipi e lavori da scartare, il prompting ad-hoc è più veloce e appropriato. Non appena una funzionalità richiede vincoli di sicurezza, decisioni architetturali multi-file o il passaggio di consegne a un team, l’assenza di una specifica diventa la principale fonte di deriva e difetti. Vedi il confronto in SDD vs Vibe Coding per sapere quando applicare ciascun approccio.

Artefatti Principali

Un flusso di lavoro SDD pratico produce quattro artefatti principali. Ciascuno riduce un tipo specifico di ambiguità prima che raggiunga l’agente.

Specifiche dei requisiti. L’enunciato del problema, gli utenti interessati, gli obiettivi, i non-obiettivi espliciti e i criteri di accettazione. I non-obiettivi sono tanto importanti quanto gli obiettivi – dicono all’agente cosa non costruire e prevengono il creep dello scope. I criteri di accettazione sono abbastanza precisi che ciascuno si mappa ad almeno un test.

Specifiche di design. Le decisioni architetturali rilevanti per questa funzionalità: moduli interessati, cambiamenti al modello dati, contratti API, migrazioni, vincoli di sicurezza, requisiti di osservabilità e modalità di guasto note. Questo non è un documento di design di sistema completo – è il sottoinsieme delle decisioni architetturali necessarie per implementare correttamente questa funzionalità.

Piano delle attività. Una sequenza di piccole attività di implementazione, ciascuna con dipendenze esplicite, cambiamenti di file attesi e criteri di validazione. Le attività sono abbastanza piccole da essere implementate in una singola sessione dell’agente e verificate con una diff focalizzata. Ogni attività ha un punto di controllo per la revisione umana.

Registro di tracciabilità. Una mappatura dai criteri di accettazione ai test, dalle decisioni di design ai file interessati, e dalle attività ai commit. Questo è ciò che separa SDD dalla documentazione che diventa obsoleta: la tracciabilità rende possibile verificare che la specifica sia stata effettivamente implementata, non solo scritta.

Questi artefatti non devono essere pesanti. Una funzionalità semplice potrebbe produrre un singolo documento markdown di due pagine che copre tutte e quattro le aree. Il formato conta meno dell’abitudine di scrivere l’intento prima che inizi l’implementazione.

Come 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. È autorevole prima che inizi l’implementazione. Viene validata dopo che l’implementazione si completa. Una specifica che descrive cosa è stato effettivamente costruito – piuttosto che vincolare cosa dovrebbe essere costruito – ha già fallito il suo scopo.

Le specifiche eseguibili guidano la generazione e la validazione. Le migliori specifiche SDD sono abbastanza vicine alla leggibilità da macchina che un agente può implementare rispetto a esse e una suite di test può verificarle. Criteri di accettazione scritti come “l’endpoint deve rifiutare le richieste non autenticate con una risposta 401” è una specifica eseguibile; “l’endpoint è sicuro” è documentazione.

Registri delle Decisioni – ADRs, PDRs e DDRs – sono complementari agli artefatti SDD ma servono uno scopo diverso. I registri delle decisioni catturano perché una scelta è stata fatta e cosa è stato respinto. Le specifiche SDD catturano cosa costruire e come verificarlo. Entrambi appartengono al repository. Insieme danno agli agenti AI il quadro completo: l’intento corrente e il ragionamento dietro di esso.

Come SDD Differisce da TDD

Lo Sviluppo Guidato dai Test e lo Sviluppo Guidato dalle Specifiche sono spesso confusi perché entrambi producono artefatti espliciti prima che esista il codice. La differenza è il punto di partenza.

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

SDD inizia con l’intento. 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 dallo scope. La specifica poi informa quali test scrivere, ed è per questo che un buon SDD e un buon TDD sono complementari piuttosto che in competizione.

Un modo pratico per pensarci: SDD guida TDD. I criteri di accettazione nella specifica diventano gli scenari di test. La specifica di design identifica i confini di integrazione che necessitano di test di contratto. Il piano delle attività identifica quali comportamenti di unità necessitano di copertura di test prima che l’agente li implementi.

Come SDD Differisce da BDD

Lo Sviluppo Guidato dal Comportamento 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’intento aziendale e l’implementazione tecnica.

SDD è più ampio. Include descrizioni di comportamento (che possono usare linguaggio stile BDD o prosa semplice) ma copre anche decisioni architetturali, modelli dati, vincoli di sicurezza, pianificazione delle attività e tracciabilità. 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 cosa 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’intento duraturo – attraverso gli strumenti, attraverso le sessioni e attraverso i membri del team.

Come SDD Differisce dai Metodi Formali

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

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 di contratto derivati direttamente dalla specifica
  • Specifica formale con prova automatizzata

La maggior parte dei team opera nel mezzo di questo spettro. L’obiettivo non è la rigore matematica – è rendere l’intento esplicito abbastanza che un agente AI possa implementare rispetto ad esso e un revisore umano possa verificare il risultato.

Benefici dello Spec-Driven Development

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

Output AI migliori. Gli agenti dati vincoli espliciti, non-obiettivi e criteri di accettazione producono implementazioni più vicine a ciò che era inteso e più facili da correggere quando sbagliano. La qualità del contesto determina direttamente la qualità dell’output.

Revisione più facile. Una pull request attaccata a una specifica è più facile da revisionare di una pull request che richiede al revisore di ricostruire l’intento 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, ogni 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 della specifica: ogni criterio di accettazione è coperto da almeno un test?

Passaggio di consegne duraturo. Quando una funzionalità passa di mano – tra ingegneri, tra sessioni degli agenti, tra sprint – la specifica è l’artefatto di passaggio. Cattura cosa è stato deciso, cosa era fuori dallo scope e cosa rimane 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 fiducia. Una specifica che esiste ma non è validata rispetto all’implementazione dà un falso senso di correttezza. Le specifiche obsolete sono a volte peggiori di nessuna specifica: ingannano i revisori e gli agenti che le leggono.

Specifiche obsolete. Le specifiche derivano quando il team le tratta come artefatti di pianificazione piuttosto che documenti viventi. Aggiornare la specifica quando l’implementazione differisce dal design non è opzionale – è ciò che separa SDD dalla documentazione che si accumula e marcisce.

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

Lock-in degli strumenti. Alcuni strumenti SDD sono opinati su formato, struttura dei file e flusso di lavoro. Una specifica scritta in un formato proprietario è più difficile da trasportare 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 sta diventando pratica di nuovo perché il costo dell’intento implicito è ora visibile nel codice generato da AI.

La disciplina è semplice: scrivere down cosa intendi costruire, revisionato e versionato, prima che l’agente lo costruisca. Mantieni quel registro onesto aggiornandolo quando la realtà differisce. Usalo come riferimento per revisione, testing e passaggio di consegne.

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

SDD si trova all’intersezione della pratica di documentazione, architettura di testing e design del codice – tutto coperto nel cluster Architettura App in Produzione insieme a registri delle decisioni, design API e pattern di accesso ai dati.

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.