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

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

Indice

Lo Sviluppo Guidato dalle Specifiche è uno di quei concetti che gli ingegneri del software hanno cercato di adottare in passato, per poi abbandonarlo quando lo sforzo richiesto non ha più portato benefici.

Ciò che è cambiato nel 2025 è l’arrivo degli agenti di coding AI, che hanno reso l’assenza di un’intento esplicito costosa. I prompt sono effimeri. Le sessioni degli agenti si resettano. Il codice cambia, ma il ragionamento che lo ha generato scompare. La specifica è l’artefatto che impedisce che ciò accada.

Cos’è lo Sviluppo Guidato dalle Specifiche – 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 dopo-pensiero. 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 Sviluppo Guidato dalle Specifiche 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 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 Davvero lo Sviluppo Guidato dalle Specifiche

Lo Sviluppo Guidato dalle Specifiche, 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 di dati, contratti API, vincoli di sicurezza
  • Come verificarlo – strategia di test, regole di validazione, tracciabilità verso i requisiti

Quell’ultimo punto è facile da scrivere e facile da saltare nella pratica. Mantenere Specifiche, Test e Codice in Sincronia nello Sviluppo AI copre cosa significhi realmente la tracciabilità verso i requisiti come dati: ID dei requisiti, ID delle decisioni di design e test collegati alle pull request che li hanno implementati.

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 gestito male, la specifica viene corretta prima di procedere. La specifica rimane onesta perché viene trattata come codice.

Recenti lavori accademici formalizzano questa cornice: 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 record revisionato e duraturo dell’intento che qualsiasi umano o strumento AI può leggere e fidarsi.

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

Spec-anchored significa mantenere una specifica in sincrono con l’implementazione per tutto il ciclo di vita della feature. 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 convalidare l’implementazione dalla specifica, sia attraverso agenti AI sia attraverso tooling che controlla il codice rispetto ai vincoli della specifica. Questa è la direzione verso cui strumenti come GitHub Spec Kit e Kiro si stanno muovendo, ciascuno con un diverso compromesso tra portabilità e guida integrata nell’IDE.

Perché SDD È Importante Ora

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

SDD diventa prezioso quando sono presenti tre condizioni: la feature è abbastanza grande da estendersi su più sessioni, l’agente deve prendere decisioni che influenzano l’architettura, e il lavoro sarà 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 a come funzionano 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 cosa gli hai detto nell’ultima sessione. Una specifica versionata memorizzata 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 è più veloce per lavori usa e getta; SDD vs Vibe Coding copre quando aggiungere specifiche e quando continuare a usare prompt liberamente.

Artefatti Principali

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

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

Come produrli e revisionarli passo dopo passo – specificare, pianificare, task, implementare, validare – è coperto in Flusso di Lavoro dello Sviluppo Guidato dalle Specifiche Dai Requisiti al Codice. Una feature semplice può coprire tutte e quattro le aree in un breve file markdown. L’abitudine conta più del formato.

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 gli è permesso costruire e cosa non gli è permesso fare. È autorevole prima che inizi l’implementazione. Viene validata dopo che l’implementazione si completa. Una specifica che descrive cosa è stato realmente 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 al leggibile 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.

Decisioni Registrati – ADRs, PDRs e DDRs – sono complementari agli artefatti SDD ma servono uno scopo diverso. I record delle decisioni catturano perché una scelta è stata fatta e cosa è stato rifiutato. 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. Scrivi un test fallente che descrive il comportamento che vuoi, poi scrivi il codice minimo per farlo passare. TDD è un ciclo di feedback a livello di unità. Produce buoni test ma non risponde alla domanda se stai costruendo la cosa giusta.

SDD inizia con l’intento. Prima che esistano i test, prima che l’architettura sia decisa, la specifica risponde: chi ha questo problema, come appare il comportamento corretto, cosa è esplicitamente fuori scope. La specifica poi informa quali test scrivere, ecco perché un buon SDD e un buon TDD sono complementari piuttosto che concorrenti.

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 hanno bisogno di test di contratto. Il piano dei task identifica quali comportamenti di unità hanno bisogno di copertura di test prima che l’agente li implementi.

Come SDD Differisce da BDD

Lo Sviluppo Guidato dal Comportamento usa 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 di dati, vincoli di sicurezza, pianificazione dei task 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 dentro.

La distinzione conta nella pratica: il tooling BDD si concentra sul rendere gli scenari eseguibili. La pratica SDD si concentra sul rendere l’intento duraturo – attraverso tool, attraverso sessioni e attraverso membri del team.

Come SDD Differisce dai Metodi Formali

I metodi formali usano notazione matematica e verifica automatizzata per dimostrare proprietà di 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 abbastanza esplicito che un agente AI possa implementare rispetto a esso e un revisore umano possa verificare il risultato.

Benefici dello Sviluppo Guidato dalle Specifiche

Meno deriva dell’intento. La specifica è il riferimento. Quando l’agente deriva – e lo farà – il revisore ha qualcosa contro 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 feature, 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 mappano direttamente ai 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 mano duraturo. Quando una feature cambia mano – tra ingegneri, tra sessioni di agenti, tra sprint – la specifica è l’artefatto di passaggio. Cattura cosa è stato deciso, cosa era fuori scope e cosa rimane da validare.

Costi dello Sviluppo Guidato dalle Specifiche

Sforzo iniziale. Scrivere una buona specifica prima di scrivere qualsiasi codice richiede tempo. Per feature 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 revisori e 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 task esaustive e specifiche verbosi rapidamente. 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.

Lock-in degli strumenti. Alcuni strumenti SDD hanno opinioni su formato, struttura dei file e flusso di lavoro. Una specifica scritta in un formato proprietario è più difficile da trasportare attraverso gli strumenti di un file markdown con header chiari e criteri di accettazione.

Conclusione

Lo Sviluppo Guidato dalle Specifiche 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: scrivi giù cosa intendi costruire, revisionato e versionato, prima che l’agente lo costruisca. Mantieni quel record onesto aggiornandolo quando la realtà differisce. Usalo come riferimento per la revisione, i test e il passaggio di mano.

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

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

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.