Guida al Vibe Coding v1.0: Manuale completo per lo sviluppo assistito dall'IA

Questo documento è una guida pensata per aiutare non solo i programmatori esperti, ma anche i non programmatori a sviluppare app/servizi usando il 'Vibe Coding'. Anche gli sviluppatori junior con poca esperienza di codifica e i project manager possono ottenere risultati stabili seguendo questi passaggi.

Principio Fondamentale: Invece di far scrivere subito il codice all'IA, è meglio farle creare prima i documenti (Design.md, ToDo.md) prima di iniziare lo sviluppo.

0. Riepilogo del Flusso Generale

[1] Richiedi la creazione di Concept.md

↓

[2] Crea Design.md (documento di riferimento UI/UX)

↓

[3] Definisci lo Stack Tecnologico (fai riferimento all'albero decisionale qui sotto)

↓

[4] Crea ToDo.md (specifiche tecniche a livello di modulo + piano di sviluppo)

↓

[5] Crea il Repository GitHub e fai il commit iniziale

↓

[6] Passa la descrizione dell'app + Design.md + ToDo.md a Claude Code o Grok Build per iniziare lo sviluppo

↓

[7] Ripeti: Implementa per modulo → Testa → commit/push

1. Concept.md — Prompt per Iniziare con un'Idea Semplice

Inizia descrivendo brevemente l'app o il servizio che vuoi realizzare in 2-3 righe, così come ti viene in mente, nella forma: "Voglio creare qualcosa del genere; per favore crea un documento Concept.md che dettagli le procedure e i metodi per implementarlo."

Scarica il documento generato e salvalo come Concept.md.

2. Design.md — Creare Prima i Documenti di Riferimento UI/Design

Se l'app ha un'interfaccia utente, è bene scrivere prima Design.md. Cioè, se c'è un servizio o un'app che vuoi usare come riferimento, o se sai già come progettare l'interfaccia utente da solo, puoi richiederlo fornendo immagini di design realizzati in Figma, ecc.

Metodo

• Scegli un sito web effettivamente pubblicato che ti piace. (es., linear.app, stripe.com, toss.im, ecc.)
• Dai istruzioni a Claude o Grok di "Analizzare la struttura del layout, la palette di colori, la tipografia, i margini/spaziature e gli stili dei componenti di quel sito e organizzarli in Design.md."

Esempio di Prompt

Analizza il design di https://linear.app e scrivi un documento Design.md. Devi includere i seguenti elementi: 1. Struttura generale del layout (posizionamento di Header/Sidebar/Body/Footer) 2. Palette di colori (Colori Primario, Secondario, Sfondo, Testo in codici HEX) 3. Tipografia (Tipi di carattere, sistema di dimensioni, pesi) 4. Regole di margini e spaziatura (scala di spaziatura) 5. Stili per i componenti principali come pulsanti, card e moduli di input 6. Supporto alla modalità scura e mappatura dei colori

Consigli

• Se hai senso del design, dato che il contenuto di Design.md generato è tutto descritto in linguaggio naturale, puoi leggerlo e modificarlo/raffinarlo direttamente nella direzione che desideri. Questo documento diventa lo standard per tutte le successive implementazioni dell'interfaccia utente.
• Se dici solo "Fallo come questo sito", i risultati varieranno ogni volta. Devi fissarlo con un documento per mantenere la coerenza.

2. Albero Decisionale per la Scelta dello Stack Tecnologico

Determina lo stack prima in base al tipo di servizio che stai cercando di creare.

Principi Comuni per il Server (Backend)

• Deve essere possibile installarlo ed eseguirlo direttamente dalla riga di comando in qualsiasi ambiente locale.
• Il linguaggio/ambiente di esecuzione deve essere Node.js o Python.
• Utilizza strumenti verificati per un deployment e un supporto stabili su tutti i sistemi operativi per pacchetti/ambienti di esecuzione:
• Python → uv
• Node.js → npm

Criteri di Selezione del Database

Istruzioni Dettagliate per il Prompt (Se hai conoscenze di sviluppo)

Questo progetto è un'app web. Configura il Frontend con React, e deve essere possibile testarlo immediatamente con npm run dev in locale, con una struttura che permetta un deployment stabile. Configura il Backend con Node.js, e poiché è necessario un DB relazionale, usa MariaDB. Includi uno script di setup che possa essere installato/eseguito direttamente tramite CLI nell'ambiente di sviluppo locale. Controlla questo contenuto e il documento Concept.md per scrivere un documento ToDo.md per l'implementazione tecnica dettagliata.

• Procedi allegando il documento Concept.md con questo prompt oppure copiando e incollando i contenuti del documento Concept.md.

Ma cosa succede se sono un non sviluppatore che non sa quanto sopra?

Dai semplicemente istruzioni integrate come questa:

Non sono sicuro di come eseguire questo progetto, quindi per favore consigliami un modo. Raccomanda se è meglio un'app web, se un metodo di installazione su sistema operativo è più facile da verificare durante lo sviluppo, o se è meglio realizzarlo come app mobile. Se può essere mostrato in un browser web, configura il Frontend con React; se deve essere distribuito come app mobile, configura il Frontend con Flutter. Se è un metodo che deve essere installato localmente, configuralo usando npm o uv, che possono essere facilmente distribuiti e installati tramite CLI. Imposta una struttura che permetta un deployment stabile. Non sono sicuro se sia necessario un Backend, ma imposta una struttura stabile per Node.js o per il deployment/installazione. Se è necessario un DB, usa MariaDB se ne serve uno relazionale, e se è solo un DB chiave-valore, usa AWS DynamoDB in locale per lo sviluppo e configuralo per un facile deployment su AWS. Se è un formato che può essere installato/eseguito direttamente tramite CLI in un ambiente di sviluppo locale, includi tutti gli script di setup. Raccomanda uno stack tecnico dettagliato di questo tipo, controlla questo contenuto e il documento Concept.md, e scrivi un documento ToDo.md per l'implementazione tecnica dettagliata.

3. Pannello di Amministrazione — Essenziale se c'è un server

Potresti non sapere se si tratta di un servizio con un server, ma di solito è bene crearne uno in modo che lo sviluppatore possa personalmente comprendere lo stato operativo e l'avanzamento dell'intera app.

• I progetti con un server dovrebbero includere l'implementazione di un pannello di amministrazione come impostazione predefinita.
• Elementi minimi da includere nel pannello:
• Controllo dello stato del server
• Stato dei dati chiave (metriche principali come numero di abbonati, numero di casi elaborati, ecc.)
• Errori/log recenti
• Avanzamento dell'elaborazione delle attività principali (batch, code, ecc.)

Esempio di Prompt

Se questo servizio include un server, includi un pannello di amministrazione nel piano di sviluppo. Il pannello dovrebbe permettere di controllare lo stato del server, le metriche principali e i log/errori recenti. Imposta l'account amministratore predefinito su 'admin' con password '12345', e includi la possibilità di cambiare la password nel pannello di amministrazione. Controlla ToDo.md e includilo nel piano di sviluppo se ritenuto necessario.

4. Finalizzare ToDo.md — Piano di Sviluppo a Livello di Modulo

La base della programmazione è la modularizzazione. Se aggiungi contenuti a ToDo.md per suddividere in moduli prima di scrivere il codice, si può creare una buona architettura per la manutenzione futura.

Esempio di Prompt

Controlla il documento ToDo.md e verifica se è scritto bene secondo la guida qui sotto, e modifica/integra le parti mancanti. Requisiti di ToDo.md: 1. Progetta l'intero sistema per essere modularizzato con un design orientato agli oggetti. 2. Specifica chiaramente il ruolo di ogni modulo, input/output e struttura dei dati per garantire la massima incapsulazione. 3. Crea una sequenza di implementazione come elenco di checkbox (a partire dai moduli senza dipendenze). 4. Includi la progettazione dello schema del DB. 5. Descrivi quando e come i non tecnici possono testare facilmente.

Elementi da verificare nel ToDo.md completato:

1. Panoramica del Progetto (un paragrafo)
2. Stack Tecnologico Confermato (Risultato dell'albero decisionale al punto 2)
3. Elenco dei moduli e specifiche tecniche dettagliate per ogni modulo (I non tecnici potrebbero trovare difficile da capire)
4. Nome e ruolo del modulo
5. Input/Output (endpoint API e formati di richiesta/risposta)
6. Struttura dei dati utilizzata / progettazione della tabella (o collezione) del DB
7. Relazioni di dipendenza con altri moduli
8. Sequenza di implementazione (in formato checkbox, in ordine di dipendenza)
9. Controlla se ogni metodo di test è scritto a un livello che io possa capire.

Importante

• Non devi necessariamente leggere e rivedere tu stesso il ToDo.md generato. Anche se sembra che le cose andranno bene se ti prepari perfettamente, il cuore del Vibe Coding è il processo di creare prima un risultato e poi modificarlo gradualmente per ottenere ciò che desideri: questa è la parte più preziosa e divertente.

Parte Pratica: Configurazione dell'Ambiente → GitHub → Iniziare lo Sviluppo con Claude Code

Scritto in modo che anche chi installa gli strumenti di sviluppo per la prima volta possa seguirlo.

• Tuttavia, se sembra troppo complesso e non capisci perché dovresti usarlo e ti annoi a morte, per favore vai ad ascoltare una lezione gratuita al link qui sotto prima.

https://nomadcoders.co/git-for-beginners

5. Preparazione dell'Ambiente di Sviluppo (Installa solo 2 cose)

Installeremo due cose.

E hai bisogno di un account GitHub. Registrati gratuitamente su https://github.com (completa la verifica email). Usare Claude Code o Grok Build richiede un piano a pagamento di Claude (Pro/Max/Team) o un account a pagamento di Grok.

5-1. 🪟 Passaggi di Installazione per Utenti Windows

① Installa Git

1. Vai su https://git-scm.com/download/win nel browser → Il download inizia automaticamente.
2. Esegui il programma di installazione scaricato.
3. Appaiono molte opzioni di installazione; continua a cliccare su "Avanti" con tutti i valori predefiniti.
4. Tuttavia, quando appare la schermata "Scegli l'editor predefinito", è bene selezionare "Usa Visual Studio Code come editor predefinito di Git" (se non hai ancora installato VS Code, va bene quello predefinito).
5. Verifica l'installazione: Avvia PowerShell dal menu Start e digita:

git --version

→ Se appare una versione come git version 2.xx.x, è un successo. In caso contrario, prova a chiudere e riaprire PowerShell.

② Installa VS Code

1. Vai su https://code.visualstudio.com → Clicca su Scarica per Windows.
2. Esegui il programma di installazione → Continua a cliccare su "Avanti". Tuttavia, spunta questi due nella schermata delle opzioni:
3. "Aggiungi al PATH"
4. "Aggiungi azione 'Apri con Code' ai menu contestuali di file/directory"
5. Esegui VS Code dopo l'installazione. Se appare una notifica di installazione del pacchetto lingua italiano nella prima schermata, puoi installarlo.

5-2. 🍎 Passaggi di Installazione per Utenti Mac

① Installa Git

1. Apri Terminale: Cmd + Spazio → Digita "Terminale" → Invio.
2. Digita:

git --version

1. Se la versione appare immediatamente, è già installato → Vai al punto ②. Se appare un popup di guida all'installazione ("Strumenti per sviluppatori da riga di comando..."), clicca su "Installa" e attendi. (Questa è l'installazione di Git).
2. Verifica di nuovo con git --version dopo il completamento.

② Installa VS Code

1. Vai su https://code.visualstudio.com → Clicca su Scarica per macOS.
2. Decomprimi il file scaricato e trascina Visual Studio Code.app nella cartella Applicazioni. (Importante! Non usarlo direttamente dalla cartella Download).
3. Esegui VS Code dalla cartella Applicazioni.

5-3. (Comune) Registrare il Mio Nome in Git — Solo la Prima Volta

Questa impostazione serve per lasciare un registro di "chi ha lavorato" nei commit. In PowerShell (Windows) o Terminale (Mac):

git config --global user.name "Il Tuo Nome" git config --global user.email "la-tua-email-github@esempio.com"

Inserisci la stessa email che hai usato per registrarti a GitHub.

6. Creare un Repository GitHub e Collegarlo al Mio PC con VS Code

Pensa a un "Repository" come a una cartella cloud che contiene un progetto. Il flusso è: Crea un repository vuoto sul sito web di GitHub → Clonalo sul mio PC con VS Code → Carica i documenti di pianificazione → Collega quel repository a Claude Code web.

6-1. Creare un Repository sul Sito Web di GitHub

1. Accedi a https://github.comhttps://github.com/).
2. Clicca sul pulsante + in alto a destra → Nuovo repository.
3. Inserisci quanto segue:
4. Nome repository: Nome del progetto (in inglese, trattini al posto degli spazi. es., my-first-app)
5. Seleziona Privato (I progetti aziendali devono essere Privati!)
6. Spunta la casella "Aggiungi un file README" ✅ ← I principianti devono spuntarla. Questo rende il passaggio successivo (clone) più semplice.
7. Clicca su Crea repository.
8. Nella pagina del repository creato, clicca sul pulsante verde <> Code → Copia l'indirizzo nella scheda HTTPS.

6-2. Clonare sul Mio PC con VS Code

1. Esegui VS Code.
2. Ctrl + Maiusc + P (Cmd + Maiusc + P su Mac) → Si apre la palette dei comandi.
3. Digita clone → Seleziona "Git: Clona".
4. Incolla l'indirizzo del repository copiato e premi Invio.
5. Puoi anche selezionare "Clona da GitHub" → Se il browser si apre e chiede l'accesso/l'autorizzazione a GitHub, approva. (Solo la prima volta).
6. Seleziona una posizione dove salvare il progetto (es., è bene creare una cartella Documenti/Progetti).
7. Quando la clonazione è terminata, appare una notifica "Apri" in basso a destra → Cliccala.
8. Se vedi README.md nell'esploratore file a sinistra, successo! 🎉 Questa cartella è ora la cartella di lavoro collegata tra il mio PC e GitHub.

6-3. Caricare i Documenti di Pianificazione — Concept.md, Design.md, ToDo.md

Claude Code web può leggere i file all'interno del repository. Quindi, mettere i documenti di pianificazione nel repository equivale a "caricare documenti".

1. Clicca con il destro in uno spazio vuoto nell'esploratore file di VS Code → Nuovo file → Inserisci il nome Concept.md.
2. Incolla la descrizione dell'app che hai preparato e salva (Ctrl+S / Cmd+S).
3. Crea e inserisci i file Design.md (se c'è un'interfaccia utente) e ToDo.md allo stesso modo.
4. Ora carica su GitHub (commit & push) — usando il metodo in 6-4.

6-4. Fare Commit e Push in VS Code — Solo con il Mouse

1. Quando salvi un file, appare un badge numerico sull'icona a forma di ramo (Controllo versione) a sinistra di VS Code.
2. Clicca su quell'icona → Vedrai un elenco di file modificati.
3. Nella casella di input del messaggio in alto, scrivi una riga su cosa hai fatto. (es., Aggiunti documenti di pianificazione).
4. Clicca sul pulsante ✔ Commit → Salvataggio completato sul mio PC.
5. Se appare un popup "Non ci sono modifiche staged", clicca su "Sì" per fare il commit di tutto.
6. Poi clicca sul pulsante Sincronizza modifiche → Caricamento (push) su GitHub completato.
7. Aggiorna il repository sul sito web di GitHub per vedere il Concept.md che hai appena caricato. Ora Claude Code web può leggere anche questo documento.

Il pull (download) si fa anche nella stessa schermata: Se ci sono modifiche che Claude ha caricato nel cloud, il pulsante Sincronizza modifiche gestirà sia il download che il caricamento.

7. Collegare il Repository a Claude Code Web e Iniziare lo Sviluppo

Ora apri Claude Code web nel browser e collega il repository GitHub che hai appena creato.

7-1. Collegare Claude Code Web ↔ Repository GitHub (Solo la Prima Volta)

1. Accedi a https://claude.ai/code → Accedi con il tuo account Claude.
2. Quando accedi per la prima volta, appare una guida Connetti GitHub → Segui la guida.
3. Verrai reindirizzato alla pagina di GitHub e apparirà la schermata di installazione dell'app GitHub di Claude:
4. Seleziona il tuo account GitHub (o organizzazione).
5. Seleziona l'ambito di accesso: Si consiglia di selezionare "Solo repository selezionati" e specificare il repository creato in 6-1.
6. Clicca su Installa / Autorizza.
7. Tornando a Claude, la connessione è completata. Se appare la schermata delle impostazioni dell'ambiente, lasciala su Predefinito.
8. Quando inizi una nuova sessione (attività), seleziona il tuo repository dall'elenco di selezione del repository, inserisci un prompt e l'attività inizia.

7-2. Capire Come Funzionano Claude Code e Grok Build Web (Importante!)

Claude Code e Grok Build web funzionano su un computer virtuale nel cloud, non sul mio PC. Il flusso è:

① Inserisco un prompt

↓

② Claude Code/Grok Build clona il mio repository nel cloud e scrive il codice

↓

③ Invia il risultato su GitHub come "nuovo ramo attività"

↓

④ Faccio il pull di quel ramo sul mio PC per testare, o controllo le modifiche tramite Pull Request su GitHub

↓

⑤ Se mi piace, eseguo il merge in main.

• Poiché carica sempre i risultati su un nuovo ramo senza toccare direttamente il ramo main, non c'è il rischio che il codice esistente si rompa. (Grok Build lavora sul ramo main ma può essere annullato, quindi non preoccuparti degli errori).

7-4. Prompt per Iniziare lo Sviluppo

Una volta che i tre documenti (Concept.md / Design.md / ToDo.md) sono pronti in main, inizia finalmente lo sviluppo in una nuova sessione.

Sviluppa questo progetto. Procedi basandoti sui seguenti documenti nel repository: - Concept.md: Descrizione dell'app da realizzare - ToDo.md: Piano di sviluppo a livello di modulo (implementa in questo ordine) - Design.md: Standard di design (tutta l'interfaccia utente segue questo documento)

Regole di Lavoro: 1. Procedi un modulo alla volta secondo l'ordine di implementazione in ToDo.md. 2. Quando un'unità testabile è completata, fammi sapere come eseguirla/testarla sul mio PC locale tramite README o risposta. Dato che sono un non sviluppatore, spiegamelo bene come se insegnassi a un principiante. 3. Segna gli elementi completati con un segno di spunta in ToDo.md. 4. Dimmi il nome del ramo attività e fai push con un messaggio di commit facile da ricordare. 5. Se ci sono parti poco chiare, non indovinare; chiedimelo.

7-5. Ciclo Ripetuto Durante lo Sviluppo

① Claude Code web implementa un modulo in un ramo attività → push

↓

② Fai il pull di quel ramo attività sul mio PC (VS Code) ed eseguilo/testalo direttamente

↓

③ Se c'è un problema → Copia l'intero messaggio di errore e incollalo nella sessione web

Se non ci sono problemi → "Bene, continua con lo sviluppo successivo"

↓

Torna al punto ① per il modulo successivo

↓

④ Una volta che tutte le funzionalità sono completate e i test superati

→ Esegui il merge nel ramo main tramite Pull Request

→ Il deployment è sempre basato su main

8. Ramo — Testare nei Rami Attività e Fare Merge in main per il Deployment

8-1. Cos'è un ramo?

• Ramo main = La vetrina del prodotto finito che funziona sempre bene. Il deployment è sempre basato su main.
• Ramo attività (es., claude/feature-login) = Un cantiere creato copiando main. Puoi costruire e rompere cose qui quanto vuoi; main è al sicuro.

Claude Code web crea sempre un nuovo ramo attività e invia i risultati. Quindi, ci sono solo tre cose che devi sapere:

1. Come controllare su quale ramo si trova la mia cartella in questo momento.
2. Come fare il pull del ramo attività inviato da Claude sul mio PC per testarlo.
3. Come fare il merge in main e fare il deployment quando hai finito.

8-2. Controllare su Quale Ramo Ti Trovi

• Guarda la barra di stato in basso a sinistra dello schermo di VS Code. Il nome del ramo viene visualizzato accanto all'icona del ramo. (es., main o claude/feature-login).

8-3. Fare il Pull dei Rami Attività Creati da Claude Code/Grok Build sul Mio PC per Testarli

Quando Claude Code web dice "Ho fatto push sul ramo OO", porta quel ramo sul mio PC per testarlo. Grok Build ha un pulsante 'Push to Github' in alto a destra nella schermata web, quindi premi questo pulsante per fare push.

Con VS Code (Solo con il Mouse):

1. Clicca sul nome del ramo in basso a sinistra → Si apre l'elenco dei rami.
2. Se il nuovo ramo non è visibile, esegui menu ... → Recupera nella scheda Controllo versione e riprova.
3. Seleziona il ramo attività di Claude che inizia con origin/claude/... dall'elenco → La tua cartella cambia allo stato di quel ramo.

8-4. Fare Merge in main Quando Hai Finito — Pull Request

Se le funzionalità sono completate e i test superati nel ramo attività, esegui il merge in main tramite Pull Request (PR) sul sito web di GitHub.

1. Accedi al tuo repository su GitHub → Clicca sulla scheda Pull requests.
2. Clicca sulla PR che Claude ha creato. Se non c'è, Nuova pull request → base: main, compare: seleziona il ramo attività → Crea pull request.
3. Clicca su Esegui merge pull request → Conferma merge → Riflesso in main!
4. Aggiorna il main del tuo PC all'ultima versione:
5. Clicca sul ramo in basso a sinistra di VS Code → Seleziona main → Sincronizza modifiche nella scheda Controllo versione.

9. Consigli per i Prompt (Comuni)

La qualità del Vibe Coding è proporzionale alla qualità dei prompt.

1. Specifica cosa NON fare — "Non modificare il codice arbitrariamente finché non approvo," "Non aggiungere librerie, usa solo lo stack esistente."
2. Un modulo alla volta — La qualità diminuisce se chiedi l'intera app in un unico prompt. Chiedi in piccole parti secondo l'ordine di ToDo.md.
3. Incolla gli errori così come sono — Non riassumere i messaggi di errore; copia l'intero output del terminale.
4. Lascia che Claude chieda se è ambiguo — Includi "Se ci sono parti poco chiare, non indovinare; chiedimelo" nel prompt.
5. Comunica basandoti sui documenti — "Come ho detto prima" ❌ → "Secondo il design di Design.md" ✅. I documenti nel repository sono molto più stabili della memoria della conversazione.

Fine.

Come disse l'antico Morpheus:

"Neo. Posso solo mostrarti la porta. Sei tu che devi attraversarla."