Cos'è lo sviluppo basato sulle specifiche?

Con l'accessibilità di strumenti di AI e assistenti di codifica come GitHub Copilot di Microsoft, Claude Code di Anthropic o Bob di IBM, la barriera d'ingresso per la generazione di codice si è abbassata. Un agente AI basato su LLM che utilizza modelli AI sofisticati può eseguire una serie di attività iterative in tempo reale in qualsiasi momento, partendo da un singolo prompt in linguaggio naturale da parte dell'utente.

Per lo sviluppo software, questo significa che possiamo ottimizzare e automatizzare il workflow di sviluppo per la realizzazione di prototipi, nuove funzionalità, test unitari e molto altro. Generare codice non è mai stato così facile. Tuttavia, c'è una deriva scivolosa di cui i vibe coder dovrebbero essere consapevoli: l'AI è valida solo quanto le istruzioni che riceve.

Tutti abbiamo probabilmente già visto il debito tecnico nel mondo reale, magari senza nemmeno rendercene conto. Il debito tecnico precede il vibe coding e fa parte dello sviluppo software da decenni, accumulandosi quando si prendono scorciatoie in nome della velocità. Tuttavia, il vibe coding accelera il debito tecnico rendendo facile generare grandi quantità di codice senza comprenderlo o convalidarlo completamente. Forse c'è pressione per rilasciare rapidamente, oppure il vibe coder semplicemente non dispone delle competenze tecniche necessarie per fermare il debito tecnico prima che inizi.  

Il debito tecnico nello sviluppo assistito dall'AI può assumere diverse forme: 

• La deriva del contesto si verifica quando la correzione di un bug in un'area compromette involontariamente la funzionalità in un'altra, un sintomo di codice generato senza una comprensione completa del sistema nel suo insieme.  
• La frammentazione è un'altra manifestazione comune, in cui le nuove funzionalità generate non si allineano alle convenzioni architetturali esistenti, erodendo gradualmente la coerenza e la facilità di manutenzione del codice sorgente.  
• Bisogna inoltre considerare i costi operativi . Senza una specifica chiara a cui ancorare il processo di generazione del codice, gli sviluppatori possono trovarsi intrappolati in lunghi cicli di prompt. Questo approccio può consumare migliaia di token per risolvere errori che una specifica ben definita avrebbe potuto evitare del tutto. 

Immaginiamo uno scenario che molti sviluppatori del settore conoscono bene. Hai lavorato a una nuova funzionalità per diversi giorni o settimane, ed è quasi pronta per il rilascio. Poi, sotto la pressione di una scadenza imminente, affretti le ultime modifiche attraverso una serie di cambiamenti guidati da prompt AI.

Le funzioni del codice generato, che siano scritte in Python o in un altro linguaggio, possono sembrare corrette dal punto di vista dell'utente. Tuttavia, nel processo sono emerse diverse vulnerabilità, sono stati introdotti conflitti tra dipendenze e la gestione dei casi limite e i test sono stati completamente trascurati.

Una specifica formale definita a monte fornisce al team una fonte di verità condivisa per governare ogni fase del ciclo di vita dello sviluppo software (SDLC), indipendentemente da chi stia scrivendo il codice.

Esistono diversi approcci e modelli per lo sviluppo basato sulle specifiche, con diversi livelli di manutenzione delle specifiche e diversi compromessi. Più che una progressione rigidamente "migliore", la scelta giusta dipende dal codice sorgente, dal team e dal tipo di problema da risolvere. È necessario valutare le esigenze e i vincoli del team prima di sceglierne uno.

Nello sviluppo spec-first, queste vengono scritte prima della generazione di qualsiasi codice, sotto forma di user story, criteri di accettazione o documento formale dei requisiti. Una volta definita la chiarezza iniziale e generato il codice, le specifiche non vengono necessariamente tenute aggiornate. Una specifica potrebbe diventare obsoleta man mano che il software evolve. Il suo scopo principale era fornire chiarezza iniziale senza una manutenzione continua. Questo aspetto è considerato il "punto di ingresso dell'SDD". ¹

Nello sviluppo spec-anchored, le specifiche evolvono insieme al software. Via via che i requisiti cambiano e vengono aggiunte funzionalità, la specifica viene aggiornata per rispecchiare lo stato attuale del sistema. Questo è particolarmente utile per i progetti al servizio di iniziative di più ampie.

I test automatizzati fungono da ponte tra documentazione e implementazione, spesso integrati in una pipeline CI/CD per garantire che i due rimangano sincronizzati ed eseguibili durante l'intero ciclo di vita dello sviluppo. Questo equilibrio tra struttura e flessibilità rende lo sviluppo spec-anchored un approccio pratico e scalabile per la maggior parte dei team di ingegneria.¹

All'estremo opposto dello spettro si colloca lo sviluppo spec-as-source, ovvero la forma più orientata all'AI. Nello sviluppo spec-as-source, le modifiche alla specifica attivano automaticamente modifiche al codice. Nessun essere umano esegue mai direttamente il refactoring del codice.

Questo livello di autorità della specifica richiede un elevato grado di fiducia nella qualità e nella coerenza della pipeline di generazione del codice AI, che oggi rimane intrinsecamente non deterministica. Nella pratica, questo significa che può essere meno rigoroso senza una forte supervisione umana. Prima di adottare questo approccio, i team dovrebbero valutare attentamente la maturità del proprio stack tecnologico e del proprio spec kit, la criticità dei sistemi coinvolti e la loro capacità di convalidare l'output generato dall'AI.¹

Nel mondo reale, molti team adottano approcci ibridi:

• Trattare le specifiche come artefatti versionati e componibili, simili agli Architecture Decision Record (ADR), invece di mantenerle sempre completamente aggiornate.
• Utilizzare sistemi esterni (ad esempio issue tracker) come fonte di verità per introdurre una separazione intenzionale.
• Evitare un'eccessiva automazione in progetti ad alta complessità o guidati dalla community, dove un controllo rigoroso delle modifiche è critico.

Ogni approccio ha punti di forza e limiti; il contesto conta più della rigorosa adesione a un unico modello.

A seconda del livello di autorità della specifica che si preferisce, una specifica efficace può avere forme diverse. Tuttavia, supponendo che ci si collochi in una posizione intermedia dello spettro e si selezioni lo sviluppo spec-anchored, una specifica dovrebbe descrivere cosa il sistema deve fare in termini chiari e verificabili. Questa specifica evita di vincolarsi prematuramente a come verrà implementata.

La specifica dovrebbe essere sufficientemente dettagliata da includere le definizioni di input e output, lo schema dei dati, i casi limite e i criteri di successo. Tuttavia, dovrebbe essere sufficientemente flessibile da poter evolvere man mano che il problema viene compreso meglio. Soprattutto, una buona specifica dovrebbe accelerare lo sviluppo: se non ti aiuta a scrivere codice migliore più velocemente o non riduce i malintesi, probabilmente è più dettagliata del necessario. 

Per illustrare come appare nella pratica una specifica efficace, consideriamo questo esempio per una funzionalità di autenticazione utente: 

Stiamo implementando una funzionalità di accesso utente per un'applicazione web.  
Utilizziamo le seguenti specifiche come singola fonte affidabile.  
Non facciamo ipotesi su alcun requisito non elencato qui. 
 
FUNZIONALITÀ: Accesso utente 
 
 PANORAMICA: 
Consentire agli utenti registrati di autenticarsi in modo sicuro utilizzando il proprio indirizzo e-mail  
 e la password. 
 
CRITERI DI ACCETTAZIONE: 
1. Il modulo di accesso deve accettare un indirizzo e-mail e una password 
2. Se le credenziali sono valide, reindirizza l'utente alla dashboard 
3. Se le credenziali non sono valide, visualizza un messaggio di errore generico  
   senza specificare quale campo è errato 
4. Blocca l'account per 15 minuti dopo 5 tentativi consecutivi di accesso  
   non riusciti. 
5. Trasmetti le password solo tramite HTTPS - mai memorizzarle in testo semplice
 
FUORI AMBITO: 
- Login tramite social (OAuth) 
- Autenticazione a due fattori 
- Flusso di reset della password 
 
CASI LIMITE: 
- Intercetta i campi vuoti lato client prima dell'invio 
- Reindirizza le sessioni scadute alla pagina di login con un messaggio informativo 
- Il modulo deve rimanere funzionale anche se JavaScript è disabilitato 
 
Non iniziare l'implementazione finché non hai confermato la comprensione  
dei criteri di accettazione.

Si tratta di documenti simili alle specifiche funzionali redatte dai product manager, ma con un ambito ben circoscritto a ciò che l'implementazione deve includere, ovvero i relativi criteri di accettazione, e alle modalità per gestire in modo adeguato gli edge.

Nella maggior parte dei casi, questa specifica risiederebbe nel repository del progetto ("repo") su GitHub come un file Markdown comeSPEC.md o/docs/auth-login.md , versionato tramite Git insieme al codice sorgente. L'agente AI Coding potrebbe accedervi se l'utente lo incolla nel prompt oppure, preferibilmente, facendo riferimento al file tramite una CLI e permettendo all'agente di leggerlo dalla directory del progetto. Ad esempio, "Implementa la funzionalità descritta in /docs/auth-login.md ."

Nelle pipeline più automatizzate, il file di specifica viene passato come parte del prompt di sistema o della finestra di contesto all'inizio dell'attività, fornendo all'agente le istruzioni prima che inizi.

Per quanto tempo e debito tecnico lo sviluppo basato sulle specifiche possano fare risparmiare, è anche importante ricordare che è possibile dedicare troppo tempo all'over-engineering. Se si passano tre settimane a discutere il nome di una singola chiave JSON o di specifici endpoint API per una funzionalità che potrebbe essere eliminata tra un mese, si vanifica lo scopo dello sviluppo basato sulle specifiche.  

Non bisogna concentrarsi troppo sulla modellazione di ogni possibile scenario futuro, preferendo invece specifiche leggere e in continua evoluzione rispetto a specifiche esaustive e "definitive". Il consiglio è quello di scrivere ciò che serve per andare avanti, convalidarlo rapidamente nel codice e iterarlo man mano che la realtà cambia. Un principio generale è che il costo di affinare la specifica dovrebbe essere sempre inferiore al costo di correggere incomprensioni nell'implementazione. Quando questo equilibrio si inverte, è il momento di smettere di perfezionare e iniziare a sviluppare.

Con l'emergere dell'AI Coding, il test-driven development (TDD) e il behavior-driven development (BDD) hanno ispirato una nuova ondata: lo spec-driven development, ovvero lo sviluppo basato sulle specifiche. Mentre il TDD chiede agli sviluppatori di definire i risultati attesi attraverso i test e il BDD di definire il comportamento tramite la collaborazione, lo sviluppo basato sulle specifiche pone prima una domanda più fondamentale: abbiamo definito chiaramente cosa stiamo costruendo e per chi?^2,3

Man mano che gli agenti AI assumono una quota sempre maggiore del lavoro di implementazione, la qualità di quel lavoro diventa direttamente proporzionale alla qualità delle istruzioni che ricevono. Una specifica ben scritta non vincola il processo di sviluppo, bensì lo accelera all'interno del moderno sistema software.