Sviluppo guidato dalle specifiche vs. Vibe Coding: Waterfall?

Le specifiche come fonte di verità, o lenta cerimonia?

Indice

Lo Spec-Driven Development è entrato nel 2026 come la risposta seria degli sviluppatori alla deriva del vibe coding.

L’argomento è semplice: gli agenti AI producono output migliori e più coerenti quando implementano contro una specifica revisionata piuttosto che contro un prompt ad hoc. Teoricamente, è difficile discutere.

In pratica, su Hacker News l’hanno chiamato “Waterfall Strikes Back” (Il Waterfall torna).

Entrambe le parti hanno ragione.

Spec-Driven Development versus Vibe Coding

Il caso per lo SDD in un mondo di Vibe Coding

Vibe coding – la pratica di scrivere un prompt libero e iterare su qualsiasi cosa l’agente AI produca – funziona in modo sorprendente per lavori piccoli, esplorativi e buttavia. Per i primi sei mesi del 2025, è stato il pattern dominante di coding con l’AI. Gli sviluppatori hanno rilasciato script, prototipi e strumenti semplici più velocemente che mai.

Poi i progetti sono cresciuti. Le funzionalità multi-file hanno iniziato a derivare. I vincoli stabiliti nella sessione uno sono stati dimenticati nella sessione tre. Le assunzioni di sicurezza sono state abbandonate. Le decisioni architetturali sono cambiate a metà funzionalità perché l’agente non aveva una memoria duratura dell’intento.

Lo Spec-Driven Development (SDD) è apparso come la risposta disciplinata. L’affermazione centrale: rendere la specifica l’artefatto centrale, non il prompt. Scrivere prima i requisiti, un design e un piano di attività. Lasciare che l’agente implementi contro quegli artefatti una fetta alla volta. Mantenere la specifica versionata e aggiornata.

Strumenti di coding AI – GitHub Spec Kit, Kiro, BMAD e un numero crescente di flussi di lavoro personalizzati per Claude Code – sono tutte implementazioni di questa idea. Gli strumenti sono reali. L’interesse è reale. La reazione contraria è anch’essa reale.

In cosa è bravo il Vibe Coding

Prima di scartare il vibe coding, vale la pena essere precisi su in cosa è bravo.

Prototipi esplorativi. Quando non sei sicuro di cosa vuoi costruire, il percorso più veloce è costruire qualcosa di approssimativo e reagire ad esso. Lo SDD richiede di sapere cosa specificare. Se non lo sai ancora, le specifiche sono premature.

Esperimenti UI. Il layout visivo e la sensazione di interazione sono difficili da specificare in anticipo. Il vibe coding ti permette di vedere opzioni rapidamente, scartarne la maggior parte e convergere su qualcosa che sembra davvero giusto. Un documento dei requisiti non ti aiuta qui.

Automazione buttavia. Script one-off, lavori di estrazione dati, helper per migrazioni – questi raramente hanno bisogno di un documento di design. Il costo di sbagliare leggermente è basso. Il costo di un processo lento e cerimoniale è reale.

Feedback rapido. Quando hai bisogno di imparare qualcosa rapidamente – questa API funziona come penso io? – il vibe coding riduce il ciclo di apprendimento a minuti. Lo SDD rallenterebbe tutto questo senza alcun beneficio.

L’errore è prendere i pattern di successo di questi contesti e applicarli a funzionalità di produzione con vincoli reali, utenti reali e conseguenze reali per aver sbagliato.

Dove il Vibe Coding fallisce

Il vibe coding si degrada in modo prevedibile man mano che scope e rischi aumentano.

Modifiche multi-file. Una volta che una funzionalità tocca cinque o più file, la finestra di contesto dell’agente inizia a perdere traccia degli invarianti. Senza un documento di design, ogni prompt deve ristabilire il contesto che è stato stabilito e dimenticato in una sessione precedente.

Deriva architetturale. Senza non-obiettivi espliciti, gli agenti implementano cose. L’agente aggiunge uno strato di caching perché sembra ragionevole. Tre sessioni dopo, l’assunzione di caching è incorporata nel modello dati e rimuoverla è costoso.

Vincoli dimenticati. “Solo gli utenti autenticati possono attivare questo” è una frase in un documento dei requisiti. In una sessione di vibe coding, è qualcosa che hai menzionato una volta nella sessione uno e l’agente non ricorda nella sessione quattro quando scrive il nuovo endpoint.

Assunzioni di sicurezza nascoste. Regole di autorizzazione, confini di validazione degli input, gestione dei segreti – questi sono esattamente il tipo di requisiti impliciti che vengono persi quando l’agente ottimizza per un codice funzionante plausibile piuttosto che per un codice corretto e vincolato.

Passaggio di consegne nel team. Se l’hai costruito attraverso prompting iterativo, l’artefatto che registra cosa è stato deciso e perché è… il log di git. Buona fortuna con quello.

Cosa cambia lo Spec-Driven Development

Lo SDD non pretende di eliminare l’iterazione. Le buone versioni dello SDD sono esplicitamente iterative. Ciò che cambiano è dove avviene l’iterazione. Per la definizione completa – incluso come lo SDD differisca da TDD, BDD e metodi formali – vedi Cos’è lo Spec-Driven Development?

Invece di iterare sul codice e dedurre l’intento dalle diff, si itera sulla specifica e poi si implementa. La specifica diventa l’artefatto che registra cosa è stato deciso, perché, e cosa è fuori scope – svolgendo una funzione simile ai Decision Records Architetturali ma orientata verso l’intento della funzionalità piuttosto che verso le scelte a livello di sistema. Il codice implementa quell’intento.

Un tipico flusso di lavoro SDD passa attraverso cinque fasi:

Specificare. Enunciato del problema, utenti, obiettivi, non-obiettivi, criteri di accettazione, domande aperte.

Pianificare. Decisioni architetturali, moduli interessati, modello dati, contratti API, preoccupazioni di sicurezza, strategia di test.

Scomposizione delle attività. Piccole fette di implementazione con criteri di validazione espliciti e punti di controllo di revisione umana.

Implementare. Un’attività alla volta, con reset del contesto tra le attività, applicando i vincoli dalla specifica e aggiornando il piano quando la realtà differisce dal design.

Validare. Test, lint, controlli di tipo, criteri di accettazione, diff tra spec e codice.

L’agente partecipa alla maggior parte delle fasi – bozza della specifica, generazione del design, proposta delle attività – ma gli umani revisionano gli artefatti prima che inizi l’implementazione. Questo step di revisione è la differenza centrale tra SDD e vibe coding.

Perché gli sviluppatori lo chiamano Waterfall

La critica del Waterfall non è sbagliata. È semplicemente rivolta verso un SDD cattivo, non verso lo SDD stesso.

Il modo di fallire specifico è la pianificazione anticipata prolungata. La caratteristica definitoria del Waterfall è un ciclo di feedback che si estende per settimane o mesi: fase dei requisiti, fase del design, fase di costruzione, fase di test, rilascio. Il feedback arriva tardi. Nel momento in cui scopri che l’assunzione del design era sbagliata, hai già costruito sopra di essa per settimane.

Quando uno sviluppatore usa Spec Kit e genera un elenco di attività di 200 righe prima di scrivere una singola riga di codice, e poi passa due giorni a rifinire il documento dei requisiti prima che l’agente tocchi qualsiasi cosa, quello è Waterfall. È Waterfall con markdown invece di UML, ma il modo di fallire è identico.

Un commentatore su HN ha descritto l’uso di Spec Kit per un piccolo strumento CLI trovandolo “troppo lento, troppo tweaking prima di vedere il codice”. Quella è la versione cattiva. Quell’utente aveva ragione a rifiutarla per quell’attività.

La critica utile non è “le specifiche sono cattive”. È “la pianificazione anticipata prolungata prima del feedback è cattiva”. Queste sono affermazioni diverse.

Il terreno intermedio utile

Un buon SDD evita la trappola del Waterfall mantenendo la specifica piccola e iniziando l’implementazione presto.

Specifiche piccole. Un documento dei requisiti per una singola funzionalità dovrebbe stare in uno schermo. Se la specifica è di dieci pagine, è o un design di piattaforma o ha bisogno di essere spezzata in funzionalità più piccole. Le specifiche troppo grandi richiedono troppo tempo per essere revisionate e diventano obsolete rapidamente.

Fette di attività brevi. Ogni attività dovrebbe essere implementabile in una singola sessione dell’agente, revisionabile come una diff piccola e testabile in isolamento. Se le attività sono troppo grandi, il ciclo di implementazione si allunga e il mapping tra spec e codice diventa difficile da verificare.

Implementazione precoce. Specificare il primo compito, implementarlo, validarlo, poi passare al prossimo compito. Non specificare tutto prima di implementare qualsiasi cosa. La prima implementazione rivelerà cose che la tua specifica ha sbagliato. Aggiorna la specifica prima di continuare.

Specifica vivente. Quando la realtà differisce dal design – e lo farà – aggiorna la specifica, non solo il codice. La specifica è utile solo se riflette ciò che è stato effettivamente costruito.

Test come feedback eseguibile. Ogni criterio di accettazione dovrebbe mapparsi su almeno un test. La suite di test è la versione leggibile dalla macchina della specifica. Se la specifica dice “solo gli utenti autenticati possono attivare questo”, dovrebbe esserci un test che verifica che le richieste non autenticate siano rifiutate.

Questo ibrido – specifiche piccole, attività brevi, implementazione precoce, documenti viventi – è ciò che funziona davvero. Non è vibe coding e non è Waterfall. È iterazione controllata con artefatti duraturi.

Quando lo SDD batte il Vibe Coding

Usa lo SDD – anche uno SDD leggero – quando il costo di sbagliare è reale.

Logica di business rischiosa. Fatturazione, permessi, migrazioni dati, idempotenza – qualsiasi logica dove un comportamento scorretto è costoso o difficile da invertire. Il vibe coding lascia questi tipi di requisiti impliciti. Lo SDD li rende espliciti e revisionabili prima dell’implementazione.

Cambiamenti API di produzione. Qualsiasi cambiamento a un contratto API pubblico o interno dovrebbe avere un documento di design. Il documento di design è ciò che revisioni prima che l’agente scriva codice che rompe i chiamanti.

Flussi di lavoro multi-agente. Quando più agenti stanno implementando parti diverse di una funzionalità, la specifica è la fonte di verità condivisa. Senza di essa, ogni agente ottimizza localmente e i pezzi potrebbero non combaciare.

Passaggio di consegne nel team. Se un altro sviluppatore o un altro agente continuerà questo lavoro, la specifica è l’artefatto di passaggio. Un log di git e un README non sono sufficienti.

Refactoring significativi. I refactoring che toccano astrazioni core hanno bisogno di un’enunciazione esplicita di cosa deve rimanere uguale (comportamento) e cosa è permesso cambiare (struttura). Senza quello, l’agente potrebbe rompere contratti che pensavi fossero preservati.

Quando il Vibe Coding è ancora migliore

Lo SDD è un sovraccarico. A volte il sovraccarico non ne vale la pena.

Script veloci. Uno script di 50 righe per rinominare file o trasformare JSON non ha bisogno di un documento dei requisiti. Scrivi il prompt, controlla l’output, rilascialo.

Esperimenti. Se stai imparando se un approccio è fattibile – esplorando un’API, testando una libreria, validando un’ipotesi – hai bisogno di velocità, non di struttura. Sperimenta prima, specifica se l’esperimento ha successo.

Schizzi UI. Il design delle interazioni beneficia di vedere piuttosto che specificare. Costruisci diverse variazioni approssimative rapidamente, reagisci a ciò che vedi, e specifica solo ciò che stai effettivamente per rilasciare.

Automazione buttavia. Script one-time, importazione dati, helper per migrazioni – il costo di un risultato leggermente sbagliato è di solito basso, e l’artefatto sarà comunque cancellato dopo l’uso.

Prototipi solisti. Se sei l’unica persona che vedrà mai questo codice e l’obiettivo è l’apprendimento piuttosto che la produzione, il vibe coding è più veloce e gli svantaggi sono contenuti.

Un semplice framework decisionale

La domanda pratica non è “SDD o vibe coding?”. È “quanta specifica ho bisogno per questa specifica attività?”.

Usa il vibe coding quando:

  • L’attività richiede meno di un giorno
  • Stai esplorando o imparando
  • L’artefatto è buttavia o a basso rischio
  • Sei l’unica persona che toccherà questo
  • La velocità del feedback è più importante della correttezza

Usa lo SDD leggero quando:

  • L’attività richiede due o più giorni
  • Sono interessati più file
  • Ci sono requisiti espliciti di sicurezza o correttezza
  • Un’altra persona o un agente continuerà il lavoro
  • Hai bisogno di scrivere test che mappino ai requisiti

Usa lo SDD completo quando:

  • La funzionalità tocca un’interfaccia pubblica o un contratto dati
  • Sono coinvolti più agenti o membri del team
  • L’organizzazione richiede una revisione del design prima dell’implementazione
  • Sono richiesti compliance o trail di audit

L’errore più comune è applicare lo SDD completo a compiti che hanno bisogno solo di uno SDD leggero, e applicare nessuna specifica a compiti che hanno bisogno almeno di una leggera.

Un SDD cattivo è Waterfall con markdown. Un buon SDD è iterazione controllata con artefatti duraturi. Il vibe coding è lo strumento giusto per i compiti giusti – e lo strumento sbagliato per quelli sbagliati. Conoscere la differenza è l’abilità.

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.