Sviluppo guidato da specifiche vs Vibe Coding: Waterfall?

Specifiche come fonte di verità, o cerimonia lenta?

Indice

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

L’argomento è semplice: gli agenti AI producono risultati migliori e più coerenti quando implementano in base a una specifica revisionata piuttosto che a un prompt ad-hoc. In teoria, è difficile sostenere il contrario.

Nella pratica, Hacker News lo ha definito “Waterfall Strikes Back” (Il Waterfall torna all’attacco).

Entrambe le parti hanno un punto.

Spec-Driven Development versus Vibe Coding

Il caso a favore dello SDD in un mondo di Vibe Coding

Vibe coding – la pratica di scrivere un prompt vago e iterare su ciò che l’agente AI produce – funziona remarkably bene per lavori piccoli, esplorativi e usa-e-getta. Per i primi sei mesi del 2025, è stato il pattern di coding AI dominante. 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 divergere. I vincoli stabiliti nella prima sessione sono stati dimenticati nella terza. 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’argomento centrale: rendere la specifica l’artefatto centrale, non il prompt. Scrivere prima i requisiti, una progettazione e un piano di attività. Lasciare che l’agente implementi in base a quegli artefatti, un tassello alla volta. Mantenere la specifica versionata e aggiornata.

GitHub Spec Kit, Kiro, i workflow SDD di Claude Code e BMAD, insieme ad altri scaffold della comunità come Superpowers, sono tutte implementazioni di questa idea. Lo strumento è reale. L’interesse è reale. Anche il contraccolpo è reale.

In cosa è bravo il Vibe Coding

Prima di sminuire il vibe coding, vale la pena essere precisi su ciò che fa bene.

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

Esperimenti di UI. La disposizione visiva e la sensazione di interazione sono difficili da specificare in anticipo. Il vibe coding ti permette di vedere rapidamente le opzioni, scartare la maggior parte di esse e convergere su qualcosa che sembra davvero giusto. Un documento di requisiti non ti aiuta qui.

Automazione usa-e-getta. Script one-off, lavori di estrazione dati, helper di migrazione – raramente hanno bisogno di un documento di progettazione. 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? – il vibe coding riduce il ciclo di apprendimento a minuti. Lo SDD rallenterebbe quel processo 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 in caso di errore.

Dove il Vibe Coding si Scontra con i Limiti

Il vibe coding degrada in modo prevedibile man mano che l’ambito e le posta in gioco aumentano.

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

Deriva architetturale. Senza obiettivi non espliciti (non-goals), gli agenti implementano cose. L’agente aggiunge un layer 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 di 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 – queste sono esattamente il tipo di requisiti impliciti che vengono persi quando l’agente ottimizza per codice plausibile e funzionante piuttosto che per codice corretto e vincolato.

Passaggio di consegne al 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 differisce da TDD, BDD e metodi formali – vedi Cos’è lo Spec-Driven Development?

Invece di iterare sul codice e inferire l’intento dai 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 a quella degli Architecture Decision Records ma orientata all’intento della funzionalità piuttosto che alle scelte a livello di sistema. Il codice implementa quell’intento.

Lo SDD attraversa cinque fasi – specifica, piano, attività, implementazione, validazione – con un gate di revisione umana in ogni passaggio. Vedi Workflow Spec-Driven Development dai Requisiti al Codice per il processo completo, i template e i checkpoint. L’agente partecipa alla maggior parte delle fasi, ma gli umani revisionano gli artefatti prima che l’implementazione inizi. Quel passaggio di revisione è la differenza centrale tra SDD e vibe coding.

Perché gli Sviluppatori lo Chiamano Waterfall

La critica del waterfall non è sbagliata. È solo mirata allo SDD fatto male, non allo SDD in sé.

La modalità di fallimento specifica è la pianificazione preliminare lunga. La caratteristica definitoria del waterfall è un ciclo di feedback che si estende per settimane o mesi: fase requisiti, fase progettazione, fase build, fase test, release. Il feedback arriva in ritardo. Nel momento in cui scopri che l’assunzione di progettazione era sbagliata, hai 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 trascorre due giorni a rifinire il documento di requisiti prima che l’agente tocchi qualsiasi cosa, quello è waterfall. È waterfall con markdown invece di UML, ma la modalità di fallimento è identica.

Un commentatore di HN ha descritto l’uso di Spec Kit per un piccolo strumento CLI e lo ha trovato “troppo lento, troppo tuning prima di vedere il codice”. Questa è la versione sbagliata. Quell’utente aveva ragione a rifiutarlo per quel compito.

La critica utile non è “le specifiche sono cattive”. È “una lunga pianificazione preliminare prima del feedback è cattiva”. Sono affermazioni diverse.

Il Punto di Scontro Utile

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

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

Fette di attività brevi. Ogni attività dovrebbe essere implementabile in una singola sessione dell’agente, revisionabile come un piccolo diff e testabile in isolamento. Se le attività sono troppo grandi, il ciclo di implementazione si allunga e la mappatura specifica-codice diventa difficile da verificare.

Implementazione precoce. Specifica la prima attività, implementala, validala, poi passa alla prossima attività. 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 dalla progettazione – 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 mappare 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 verifichi che le richieste non autenticate vengano 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 Supera 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 errato è costoso o difficile da invertire. Il vibe coding lascia questi tipi di requisiti impliciti. Lo SDD li rende espliciti e revisionabili prima dell’implementazione.

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

Workflow 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 al 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 bastano.

Refactoring significativi. I refactoring che toccano astrazioni core hanno bisogno di una dichiarazione esplicita di cosa deve rimanere lo stesso (comportamento) e cosa è permesso cambiare (struttura). Senza di ciò, l’agente potrebbe rompere contratti che pensavi fossero preservati.

Quando il Vibe Coding È Ancora Migliore

Lo SDD è un overhead. A volte l’overhead non vale la pena.

Script rapidi. Uno script di 50 righe per rinominare file o trasformare JSON non ha bisogno di un documento di 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.

Bozze di UI. La progettazione delle interazioni beneficia dal vedere piuttosto che dal specificare. Costruisci diverse variazioni grezze rapidamente, reagisci a ciò che vedi e specifica solo ciò che stai effettivamente per rilasciare.

Automazione usa-e-getta. Script one-time, importazioni di dati, helper di migrazione – il costo di un risultato leggermente errato è di solito basso, e l’artefatto verrà comunque eliminato dopo l’uso.

Prototipi solitari. 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 mi serve per questo compito specifico?”

Usa il vibe coding quando:

  • Il compito richiede meno di un giorno
  • Stai esplorando o imparando
  • L’artefatto è usa-e-getta o a bassa posta in gioco
  • Sei l’unica persona che toccherà questo
  • La velocità del feedback conta più della correttezza

Usa lo SDD leggero quando:

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

Usa lo SDD completo quando:

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

L’errore più comune è applicare lo SDD completo a compiti che hanno bisogno solo di SDD leggero, e non applicare alcuna specifica a compiti che hanno bisogno di almeno una specifica leggera. Indipendentemente dal livello che scegli, la specifica rimane utile solo se qualcosa continua a verificarla rispetto al codice; Mantenere Specifiche, Test e Codice in Sync nello Sviluppo AI copre i controlli di tracciabilità che catturano una specifica che diventa silenziosamente obsoleta.

Lo SDD fatto male è waterfall con markdown. Lo SDD fatto bene è iterazione controllata con artefatti duraturi. Il vibe coding è lo strumento giusto per i compiti giusti – e lo strumento sbagliato per quelli sbagliati. Sapere la differenza è la competenza.

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.