Spec-Driven Development: come dare struttura all'AI, dall'idea al codice

Chiunque abbia scritto codice utilizzando un LLM conosce bene la sensazione: parti con una richiesta semplice, l’AI sembra capirti, ma una decina di prompt dopo ti ritrovi con file che non avevi richiesto, una libreria scelta chissà perché, una funzione per risolvere un problema che forse avresti potuto evitare. In breve, scopri che il tool è potente, altroché, ma è anche caotico e, se lasciato libero di agire, divaga.

E’ da questa esperienza che nasce la mia meraviglia quando alcuni mesi fa, in occasione della MokaWeek (di cui ho raccontato un po’ di cose nel mio reportage) partecipai al workshop per lo sviluppo di prodotti con l’AI, usando ARchetipo.

Ho deciso di appoggiarmi a questo tool in due occasioni: sia quando ho parlato di costruire micro-SaaS con l’AI alla conferenza ITDevCon Spring Edition, sia durante la recente live di coding sul mio canale Twitch, che vi vado ora a raccontare.

Ma che cos’è ARchetipo?

ARchetipo è un framework che permette di strutturare il lavoro di sviluppo software con l’AI usando un approccio Spec-Driven Development (SDD). In pratica, invece di buttarsi sul codice da subito, questo tool ti fa costruire un percorso di documenti che portano gradualmente dall’idea all’implementazione.

Lo Spec-Driven Development (SDD) è una metodologia di sviluppo software in cui la documentazione delle specifiche diventa la fonte primaria di verità. Quindi anziché scrivere direttamente il codice, lo sviluppatore redige prima specifiche strutturate usando un tool o un formato specifico.

Non si tratta di una metodologia appena nata, ma è tornata in auge grazie al fatto che salvando le specifiche in un formato testuale leggibile, ad esempio in formato Markdown, l’AI può farne uso per generare, validare e aggiornare un software in modo autonomo.

L’elevata accessibilità derivante dal formato testuale, che spesso viene salvato nella stessa cartella di progetto, ha un ulteriore beneficio: grazie a Git (o al sistema di controllo di versione che preferisci) è possibile archiviare, versionare e storicizzare anche le specifiche, unendole al codice che le implementa, generato ovviamente in buona parte dall’AI.

Le fasi del “motore” di ARchetipo

Il workflow di ARchetipo si articola in cinque fasi. Ciascuna di queste fasi produce un artefatto che alimenta la fase successiva. Si tratta in breve di file che l’AI produce, che “restano lì” e che la stessa AI rilegge nella fase seguente.

Nella mia live ho deciso di provare a realizzare questa idea: una lavagna virtuale da utilizzare come docente per corsi online, con un supporto particolare per rappresentare concetti, interazioni ed elementi tipici della programmazione.

Sorvolando sull’installazione e setup del progetto e del tool (per le quali ti rimando alla live per un approfondimento), ora ti racconto le varie fasi nell’ordine in cui generalmente andrebbero attraversate.

Inception (ma Christopher Nolan non c’entra)

La prima sorpresa è che ARchetipo non parte scrivendo cose, bensì interrogandoti: un team virtuale di specialisti, ciascuno con un nome e un ruolo ben specifici, prende la tua idea e comincia a metterla in discussione.

Ad esempio, il team mi ha chiesto perché mai la mia lavagna dovesse esistere, visto che di lavagne virtuali ne è pieno il mondo, ossia mi ha chiesto cosa manca in quelle attualmente disponibili sul mercato. Ha poi messo in dubbio il mio target: e se il pubblico non fosse proprio quello che avevo in mente? Infine, mi ha costretto a ridurre l’MVP all’osso, con domande del tipo “questa funzione ti serve dal giorno 1 o può tranquillamente aspettare la versione 2?”.

Questa specie di interrogatorio è tanto fastidiosa quanto utile: in cinque minuti mi sono accorto che metà delle cose che davo per scontate in realtà non reggevano; nel contempo, c’erano però altre idee inizialmente tralasciate che potevano essere prese in considerazione. E’ un brainstorming molto interessante.

Il risultato di questa fase è la creazione del cosiddetto Product Requirements Document, abbreviato in PRD, un file Markdown che raccoglie tutto: il nome del progetto (provvisorio), la vision del prodotto, le “personas” (nel mio caso sono l’insegnante che spiega e lo studente che partecipa al corso), il perimetro dell’MVP con uno sguardo alle funzioni future, le scelte architetturali (librerie, framework, ecc.) e i requisiti non funzionali come quelle relative alla sicurezza.

Da questo momento in poi, il PRD diventa la bussola vera e propria del progetto: nessuno degli “specialisti” del team AI ti rifarà le stesse identiche domande: il contesto in cui si è sviluppata la discussione ha prodotto il suo risultato e non deve essere ripetuto. Le fasi successive ripartiranno quasi da zero: avranno il PRD come base dalla quale partire.

Design: un mockup vale più di mille parole

Questa fase è opzionale, ma come si fa a non provarla?

Un’agente AI specializzata in UX (nel tool si chiama Livia) legge il PRD e genera dei mockup in HTML e CSS che puoi aprire, ad esempio con Visual Studio Code, per avere un’anteprima di quella che sarà l’interfaccia utente finale.

Questi prototipi vivono in una cartella isolata e posso fornire uno spunto per guidare la scrittura del codice successivamente. Sono quindi un riferimento visivo in più che l’AI userà come guida nelle fasi successive.

Coloro che hanno visto un “prototipo veloce” finire poi dritto in produzione sa perché questa distinzione netta tra mockup e progetto finale è importante. 😉

Spec: dall’idea al backlog

Qui il PRD viene elaborato dando origine a un backlog strutturato: il prodotto viene “spezzato” in epic (grandi gruppi di funzionalità) e user story (US) scritte dal punto di vista dell’utente.

Un esempio classico di US potrebbe essere questa: Come insegnante voglio inserire forme geometriche sulla lavagna.

Per ogni storia, l’AI assegna in automatico priorità, criteri di accettazione e dipendenze.

Certo, dedurre che il login vada implementato prima della feature di condivisione della lavagna è banale per chiunque, ma averlo formalizzato in un backlog ordinato - anche per casi molto più complessi e articolati di questo - elimina una quantità sorprendente di ambiguità.

Al termine di questa fase hai una lista di cose da fare che è vera, sensata, ordinata.

Plan: hai progetti per il futuro?

In questa fase ci avviciniamo (non pericolosamente) alla scrittura del codice, ma non lo “tocchiamo” ancora: si pianifica il lavoro tecnico di ogni storia prima di scrivere qualunque cosa.

Colui che non riesce a pianificare sta progettando di fallire. - Winston Churchill

Intervengono quattro agenti, ognuno con un ruolo diverso: un analista dei requisiti (Emanuele) si assicura che ogni task non abbia ambiguità; un architetto (Leonardo, nome azzeccatissimo) disegna le fondamenta e sceglie le tecnologie; uno sviluppatore full-stack (Ugo, probabilmente il più frustrato di tutti) ordina l’esecuzione sul codice; infine, la test architect (Mina) definisce cosa va testato e come, prima ancora che esista una riga da testare!

Nella mia live si può vedere in azione il piano per costruire le fondamenta del progetto: occorre creare l’infrastruttura e i file di configurazione (con TypeScript e Vite), aggiungere e configurare i package e il linter per tenere pulito il codice, definire la strategia di test partendo dagli “smoke test”.

E qui si arriva al punto che evidenzia il vantaggio di tutto il processo: l’AI non deve inventarsi soluzioni, deve solo eseguire. Abbiamo creato i binari, il guard-rail, le metaforiche briglie che guidano il potente cavallo dove vogliamo noi. Yee-haw! 🤠

Implement: si scrive codice, finalmente!

Nella fase di implementazione, lo sviluppatore AI scrive il codice seguendo esattamente il piano e i test automatici. Poi subentra un secondo agente, un revisore (Cesare), che controlla il codice in cerca di errori e incoerenze prima della consegna, perché esattamente come in un team umano tradizionale, tu non faresti mai il merge della tua PR senza che qualcuno dia un’occhiata… vero? 😅

Se utilizzi la dashboard integrata nella CLI di ARchetipo, puoi vedere le feature passare nei vari stati, dal planning all’implementazione fino allo stato “review”, pronta per la tua approvazione finale. Del resto, la revisione e l’approvazione finale è ancora una cosa che spetta a noi fare… almeno per il momento. 😁

Nella mia sessione live ho visto il tool lavorare in piena autonomia, creando la struttura del progetto, installando i pacchetti, facendo partire un prototipo della lavagna e verificandolo, senza che io dovessi intervenire a controllare.

Vedere questo flusso di lavoro dispiegarsi sotto i tuoi occhi, senza toccare un editor, ti fa realmente capire le enormi potenzialità dell’AI in questo ambito e il senso profondo dell’uso di questo metodo, accompagnato eventualmente da tool come ARchetipo.

Cosa mi porto (e ti porti) a casa

La tesi di fondo è semplice: “La potenza è nulla senza il controllo”, diceva quello.

All’AI servono binari. Non perché sia “stupida” ma perché senza vincoli riempie ogni spazio vuoto con un’invenzione plausibile. L’SDD e l’uso di tool come ARchetipo (ma ne esistono tanti altri) restringe progressivamente lo spazio delle decisioni autonome da parte dell’AI, finché nella fase di scrittura del codice - che è quella in cui è richiesto il maggior rigore - non resta quasi nulla da inventare.

Questo metodo consente inoltre di aggirare alcune delle limitazioni intrinseche degli LLM, come la gestione della memoria. I documenti progressivi (PRD, backlog, piani, ecc.) fanno sì che ogni specialista del team AI riceva solo il contesto stretto che gli serve. Niente chat chilometriche che degenerano in allucinazioni a metà strada. È un problema concreto di chi lavora con questi strumenti tutti i giorni che qui viene risolto “by design”. E poi a pensarci bene, è una condizione che vale anche nel mondo reale: quale collega ubriachereste di dettagli inutili per ciò che non gli/le compete o non è di suo interesse?

Il secondo vantaggio è la validazione forzata dell’idea. Tutti noi (developer soprattutto) ci innamoriamo di un progetto e apriamo l’editor dopo dieci minuti, per poi scoprire a metà che la nostra idea non aveva mercato o che mancava un pezzo. ARchetipo e la metodologia SDD ti obbliga a “difendere il prodotto” a parole prima di costruirlo. A tratti è frustrante, ma quasi sempre è salutare.

Il terzo vantaggio è la separazione dei ruoli: lo sviluppatore AI che scrive e il revisore che controlla sono agenti distinti, e questo banale dettaglio cambia la qualità del prodotto, poiché la commistione di questi ruoli in un unico contesto “ingolosirebbe” troppo l’AI ad auto-assolversi oppure a soddisfare sé stessa tramite scorciatoie tecnicamente indesiderabili.

Ne vale la pena? E me lo chiedi pure?

Se usi l’AI solo per snippet veloci nel tuo editor, questo metodo è chiaramente sovradimensionato, ma se la usi (o vorresti usarla) per costruire qualcosa di reale, l’overhead iniziale del workflow e della generazione degli artefatti si ripaga in fretta, mentre per progetti medio/grandi (a mio parere) si tratta di uno strumento imprescindibile.

Grazie a SDD accoppiati a tool come ARchetipo, trasformi un assistente AI generico e imprevedibile in un team strutturato, con dentro un product manager, un architetto, uno sviluppatore, un revisore, un tester, uno UX designer… in breve un team strutturato, fatto di agenti AI, che è esattamente quello che serve per produrre un software con l’AI che funziona davvero.