Vibe coding: cosa serve davvero per farlo funzionare

Il vibe coding ha un problema di comunicazione. Il nome suggerisce leggerezza, un approccio rilassato alla creazione di software, descrivi quello che vuoi e l’AI si occupa del resto. Nella pratica è un’altra cosa, e dopo nove mesi di lavoro con questo approccio ho raccolto il metodo che ho costruito strada facendo in un manuale, pubblicato in italiano e in inglese su docs.ai-know.pro. Questo articolo racconta da dove nasce e perché.

Andrej Karpathy, cofondatore di OpenAI, ha coniato il termine nel febbraio 2025 con una definizione volutamente provocatoria, ci si affida all’AI, si accettano le modifiche senza leggere il codice, si lascia che il progetto cresca oltre la propria comprensione. Un anno dopo lo stesso Karpathy ha dichiarato il concetto superato, proponendo al suo posto l’agentic engineering, dove la parola che conta non è più “vibe” ma “engineering”.

Ho iniziato a usare Claude per costruire applicazioni nell’estate del 2025. In un’altra vita professionale ho fatto lo sviluppatore e l’analista, più di vent’anni fa e con linguaggi che nel frattempo sono diventati archeologia. Dell’esperienza di sviluppo ho portato poco nel vibe coding, i linguaggi sono diversi, gli strumenti sono diversi, il modo stesso di lavorare non ha quasi nulla in comune. L’esperienza da analista invece si è rivelata sorprendentemente attuale, saper scomporre un problema, definire requisiti, distinguere cosa serve da cosa sembra servire. In nove mesi di progetti di natura molto diversa tra loro la costante è stata questa: la competenza che fa funzionare il vibe coding non è tecnica ma analitica.

Cosa pensa la gente vs cosa succede davvero

La narrativa più diffusa sul vibe coding è che basti descrivere quello che si vuole e l’AI lo costruisce. È una versione semplificata ma non è inventata, i video dimostrativi che circolano online mostrano proprio questo, qualcuno descrive un’applicazione e nel giro di pochi minuti l’applicazione esiste. Quello che i video non mostrano è tutto il resto, le ore di progettazione precedenti, i cicli di correzione successivi, le volte in cui il risultato non funziona e bisogna capire perché.

Il ciclo reale del vibe coding inizia con la descrizione dell’obbiettivo, poi si entra nel loop di generazione-test-correzione. A volte si butta via tutto e si ricomincia con un’idea più chiara di quello che si vuole. Nella mia esperienza il tempo dedicato a scrivere codice (o meglio, a far scrivere codice) è una frazione del tempo totale. La parte più consistente se ne va nel capire cosa costruire, nel descriverlo in modo abbastanza preciso da ottenere un risultato utile, e nel verificare che il risultato faccia effettivamente quello che dovrebbe.

C’è poi un aspetto che la narrativa dominante tende a trattare come un dettaglio quando invece è il punto centrale. Il vibe coding non è una pratica unica, è uno spettro. A un estremo c’è chi accetta tutto quello che l’AI produce senza guardarlo, all’estremo opposto c’è chi rivede e comprende ogni riga generata. In mezzo c’è una posizione più pragmatica, quella in cui si valuta il risultato nel suo funzionamento senza necessariamente leggere ogni riga di codice, ma con sufficiente attenzione da accorgersi quando qualcosa non va.

Nella pratica la posizione sullo spettro non è fissa. Si può partire con fiducia su un compito semplice e diventare molto più attenti quando il progetto diventa complesso o quando si trattano dati che non sono solo propri. Chi comincia senza esperienza di programmazione si trova naturalmente nella posizione di massima fiducia, quella in cui si accetta il risultato perché non si hanno gli strumenti per valutare il meccanismo sottostante. Il percorso naturale è spostarsi progressivamente verso la posizione intermedia, dove la fiducia è informata e non cieca.

Pensare prima di costruire

La tentazione più naturale quando si scopre il vibe coding è aprire Claude e iniziare subito a chiedere. L’interfaccia invita a farlo, si scrive una richiesta e in pochi secondi compare del codice che sembra funzionare. Il problema è che “sembra funzionare” e “fa quello che serve” sono due cose diverse, e la distanza tra le due si riduce quasi sempre prima della tastiera, non durante.

Il primo passo non è tecnico. È chiedersi se il progetto che si ha in mente è adatto al vibe coding, e la risposta dipende da una serie di variabili concrete. Un’applicazione per uso personale che organizza appunti è un caso ideale, se qualcosa non funziona l’unica persona coinvolta è chi l’ha costruita. Un servizio che gestisce dati di altre persone è un caso diverso, perché entrano in gioco obblighi normativi come il GDPR che prescindono dal modo in cui l’applicazione è stata costruita. Un’applicazione esposta su internet è un caso diverso ancora, perché riceverà tentativi di accesso automatizzati nel giro di ore dalla pubblicazione. Il vibe coding non è inadatto a nessuno di questi casi in assoluto, ma il livello di attenzione e le competenze necessarie cambiano in modo significativo dall’uno all’altro.

Una volta stabilito che il progetto è nel perimetro giusto resta il lavoro più importante, definire con precisione cosa si vuole ottenere. Nella pratica quotidiana questo si traduce in un metodo che nel manuale viene descritto come spec.md + todo.md. Il primo file è una specifica di progetto, un documento che descrive cosa l’applicazione deve fare, per chi, con quali vincoli e quali limitazioni. Il secondo è il piano di lavoro che ne deriva, la sequenza di passi concreti necessari per arrivarci. Non è un’invenzione, è il modo in cui l’analisi dei requisiti funziona da decenni nello sviluppo software tradizionale, adattato a un contesto in cui il codice lo scrive qualcun altro (in questo caso un’AI).

La differenza tra partire con una specifica e partire con una richiesta generica si vede nei risultati. «Fammi un’app per gestire i contatti» produce qualcosa, ma quel qualcosa riflette le assunzioni dell’AI su cosa significhi “gestire contatti”, non quelle di chi l’ha chiesto. «Un’applicazione locale che salva nome, email e note su un file JSON, con ricerca per nome e possibilità di esportare in CSV, senza connessione a internet» produce un risultato molto più vicino a quello che serve. La precisione della descrizione è direttamente proporzionale all’utilità del risultato, e scrivere quella descrizione è un lavoro che richiede tempo e chiarezza di idee.

Quando il vibe coding si svolge all’interno di un progetto strutturato, e ancora di più quando si dedica un progetto Claude a uno specifico progetto software, entra in gioco un terzo file, CLAUDE.md. Contiene le istruzioni persistenti per quel progetto, le decisioni tecnologiche già prese, le convenzioni da rispettare, gli errori da non ripetere. È la memoria del progetto, il documento che evita di ridiscutere le stesse scelte a ogni sessione di lavoro. Nella pratica si rivela tanto utile quanto la specifica iniziale, perché il vibe coding non è quasi mai un’attività che si esaurisce in una sessione.

Cosa ho costruito

In nove mesi di lavoro con Claude ho costruito progetti di natura molto diversa tra loro. Non li elenco come un portfolio ma perché la varietà racconta qualcosa di utile sul metodo e sui suoi limiti.

I primi progetti sono stati semplici, strumenti a funzione singola, utility per elaborare documenti, script di automazione per operazioni ripetitive o anche solo per un uso una tantum. Il tipo di progetto in cui il vibe coding funziona quasi come la narrativa promette, si descrive quello che serve, Claude lo costruisce, si testa e nel giro di qualche ora si ha qualcosa di usabile. La specifica è breve, i cicli di correzione sono pochi, il rischio di errori gravi è basso.

La complessità è cresciuta per gradi. Un’applicazione web in React per la navigazione strutturata di scenari decisionali ha richiesto giorni di lavoro, non ore, e gran parte di quel tempo è andato nella progettazione dell’interfaccia e nella definizione dei flussi utente, non nel codice. Ho costruito anche dei server MCP, tra cui un sistema per connettere Claude a NotebookLM con strutturazione automatica dei prompt, hanno posto un problema diverso, quello di progettare il comportamento di uno strumento che altri avrebbero usato senza la mia supervisione. I simulatori interattivi per la formazione hanno richiesto di pensare contemporaneamente alla correttezza del modello e alla chiarezza didattica.

Il progetto più articolato è stato un sistema completo di documentazione con generazione automatica di PDF, lo stesso che ospita il manuale di cui si parla in questo articolo. In questo caso il vibe coding ha mostrato sia la sua forza sia i suoi confini. La forza è che un sistema del genere, senza l’AI, avrebbe richiesto competenze di sviluppo web che non ho mai avuto ed avrei dovuto studiare a lungo per crearmele. Il confine è che la complessità del progetto ha superato più volte la capacità di Claude di tenere insieme tutti i pezzi in una singola sessione di lavoro, rendendo necessaria una gestione attenta delle sessioni, del contesto e della documentazione di progetto.

Un altro progetto significativo è stata un’arena di discussione tra agenti AI, un sistema capace di orchestrare dibattiti strutturati tra prospettive diverse su un tema dato, in pratica la gestione di un team di esperti. L’aspetto interessante è che il progetto stesso è partito da una sessione di brainstorming in Chat per definire le specifiche, prima di diventare un’applicazione costruita in Cowork. Il passaggio dalla conversazione al software illustra bene la progressione naturale che il manuale descrive nel capitolo dedicato alle tre modalità di Claude Desktop.

Tutti questi progetti sono open source e disponibili su GitHub. Nessuno è nato con l’ambizione di diventare un prodotto, sono strumenti costruiti per risolvere problemi concreti nel mio lavoro. Il fatto che siano pubblici e che altri li usino è una conseguenza, non un obiettivo iniziale.

Perché un manuale

Il manuale non nasce da un piano editoriale. Nasce dal bisogno di rimettere in ordine quello che nove mesi di pratica avevano prodotto, un insieme di metodi, errori, soluzioni e abitudini di lavoro che funzionavano ma che non avevo mai formalizzato. Scriverlo è stato un modo per capire meglio quello che facevo già.

Il risultato è un percorso in nove capitoli che parte dai concetti e arriva alla pubblicazione del codice. I primi capitoli inquadrano il vibe coding per quello che è nella pratica, non per quello che la narrazione diffusa racconta, compresa l’evoluzione del pensiero di chi il termine lo ha inventato. La parte centrale entra nell’operatività, l’ambiente di lavoro con Claude Desktop, le tre modalità (Chat, Cowork e Code), la configurazione degli strumenti, e soprattutto il metodo per progettare prima di costruire. La parte finale è pratica, un primo progetto guidato passo per passo, progetti più complessi tratti dall’esperienza reale, le best practice per lavorare bene con Claude, la sicurezza, la pubblicazione.

Il manuale è pensato per un profilo preciso, professionisti che usano già Claude e che vorrebbero fare qualcosa in più con lo strumento che già conoscono. Non si rivolge a sviluppatori, che hanno percorsi e strumenti propri, né a chi non ha mai aperto Claude, perché il manuale assume una familiarità di base con l’interfaccia e con il modo di lavorare in conversazione, oltre ad avere attivato un piano a pagamento. Il lettore ideale è qualcuno che ha già capito cosa può fare Claude con il testo, con l’analisi, con la ricerca, e si chiede se può spingersi oltre.

Una precisazione su cosa il manuale non è. Non è un corso di programmazione, chi lo legge non imparerà a programmare e non è questo l’obiettivo. Non è nemmeno un tutorial che promette di costruire un’applicazione in dieci minuti, perché quel tipo di promessa racconta solo la parte facile della storia. Il manuale dedica più spazio al pensare che al fare, e la scelta è intenzionale.

Chiusura

Il vibe coding è uno strumento reale e accessibile, ma non è la scorciatoia che il nome sembra promettere. Richiede la stessa disciplina di qualsiasi altro lavoro fatto bene, capire cosa si vuole, descriverlo con precisione, verificare i risultati, correggere, ripetere. La parte in cui l’AI scrive il codice è quella che fa meno fatica.

Per chi volesse farsi un’idea dell’approccio prima di leggere il manuale dall’inizio, il quarto capitolo, Pensare prima di costruire, è probabilmente il punto di ingresso più rappresentativo. È il capitolo in cui il metodo si vede meglio, e anche quello in cui le aspettative si calibrano in modo più utile.

Il manuale è rilasciato con licenza Creative Commons, è disponibile sia per la lettura online che per il download in formato PDF sia in italiano che in inglese.