Pensare prima di costruire¶

La tentazione più comune nel vibe coding è iniziare subito a chiedere a Claude di scrivere codice. È comprensibile, la tecnologia sembra magica e si vuole vedere subito un risultato, ma un buon risultato è l'ultimo elemento di una catena di passaggi, tutti necessari per arrivare fino in fondo.

Questo progetto è adatto al vibe coding?¶

Prima di aprire Claude e iniziare a descrivere un'applicazione, vale la pena fermarsi un momento. Non tutti i progetti sono ugualmente adatti al vibe coding, e saperlo prima evita frustrazioni, rischi e lavoro sprecato.

Non si tratta di una distinzione binaria tra "sì" e "no". Si tratta piuttosto di una scala di rischio crescente. Un'applicazione per uso personale che non tratta dati sensibili è il terreno ideale per il vibe coding. Un servizio a pagamento con autenticazione utenti e dati di terzi richiede competenze professionali che vanno oltre la capacità di descrivere bene un'idea.

Per orientarsi, conviene valutare il progetto da più punti di vista.

Destinazione del progetto. Un'applicazione per uso personale, che gira sul proprio computer e che nessun altro userà mai, è il caso più semplice. Se qualcosa non funziona, l'unica persona coinvolta è chi l'ha costruita. Il rischio cresce quando l'applicazione viene condivisa con altri, anche gratuitamente, perché a quel punto qualcun altro dipende dal suo funzionamento. Cresce ancora se viene venduta o se diventa un servizio a pagamento, perché entrano in gioco aspettative, obblighi e responsabilità.

Dati e sensibilità. Un'applicazione che organizza appunti personali è diversa da una che gestisce contatti di clienti, fatture o cartelle cliniche. Quando un progetto tratta dati di altre persone, si entra nel territorio della normativa sulla protezione dei dati personali (GDPR in Europa), con obblighi specifici che prescindono dal modo in cui l'applicazione è stata costruita. Quando tratta dati finanziari, i requisiti di sicurezza e affidabilità diventano ancora più stringenti.

Account e servizi esterni. Molti progetti utili collegano servizi esistenti: leggere email, pubblicare su un blog, interrogare un database. Ognuno di questi collegamenti usa credenziali, come chiavi API, token di accesso o password, che danno all'applicazione permessi sul proprio account. Un errore nel codice che gestisce queste credenziali può esporre l'account a rischi concreti. Il principio guida è il privilegio minimo, ovvero dare all'applicazione solo i permessi strettamente necessari, mai l'accesso completo a un account quando ne basta uno limitato.

Autenticazione. Se l'applicazione gestisce il login di altri utenti, con username, password e sessioni, la complessità aumenta in modo significativo. La gestione dell'autenticazione è uno degli aspetti più delicati dello sviluppo software, e gli errori in quest'area possono avere conseguenze serie. È una delle situazioni in cui il coinvolgimento di uno sviluppatore esperto è fortemente consigliabile.

Esposizione. Un'applicazione che gira solo sul proprio computer è protetta dalla rete locale. Un'applicazione accessibile da internet è esposta a chiunque, compresi utenti con intenzioni non costruttive. La differenza non è teorica: un'applicazione web pubblica riceve tentativi di accesso automatizzati nel giro di ore dal suo deploy. Il capitolo sulla sicurezza approfondirà questo aspetto.

Affidabilità. Per uno strumento personale, un'interruzione di servizio è un fastidio. Per uno strumento che altri usano nel loro lavoro quotidiano, è un problema serio e la domanda da farsi è cosa succede se l'applicazione smette di funzionare una notte, magari nel weekend? Se la risposta è "niente di grave, la sistemo quando posso", il vibe coding è adeguato. Se la risposta è "persone o processi si bloccano", servono garanzie che il vibe coding da solo non può offrire.

Manutenzione. Ogni applicazione che funziona oggi potrebbe smettere di funzionare domani. Le librerie si aggiornano, le API cambiano, i servizi esterni modificano le loro interfacce. Un progetto personale può restare fermo per mesi senza conseguenze. Un progetto usato da altri richiede attenzione continua, e la persona che lo mantiene deve essere in grado di capire cosa si è rotto e perché.

Impatto sulle persone. Chi costruisce un'applicazione è responsabile di ciò che quell'applicazione fa. Questo vale indipendentemente da come è stata costruita e da dove viene eseguita. Il fatto che un progetto sia personale e giri esclusivamente sul proprio computer non crea una zona franca, né dal punto di vista legale né da quello etico. Ci sono usi che restano illeciti o inaccettabili anche in assenza di qualsiasi esposizione esterna, e il vibe coding non sposta la responsabilità dall'autore alla macchina.

In Italia la Legge 132/2025 sull'intelligenza artificiale, in vigore dal 10 ottobre 2025, rende espliciti alcuni di questi principi. Ogni contenuto generato o modificato con sistemi di AI deve essere dichiarato come tale. La diffusione di immagini, video o audio alterati con AI senza il consenso della persona rappresentata è un reato. L'uso dell'intelligenza artificiale come strumento per commettere un illecito è una circostanza aggravante. Si tratta di una legge-quadro con implicazioni ampie, e chi costruisce applicazioni che generano o manipolano contenuti fa bene a conoscerne i principi fondamentali.

Quando poi l'applicazione coinvolge altre persone, producendo raccomandazioni, classificazioni o decisioni che le riguardano, la responsabilità cresce ulteriormente. Un errore nel codice di un organizzatore di appunti è un inconveniente. Un errore nel codice di uno strumento che influenza scelte su altri può danneggiare qualcuno concretamente.

La regola pratica che emerge da queste dimensioni è lineare. Un progetto per uso personale, che non tratta dati sensibili e non è esposto a internet, è il candidato ideale per il vibe coding. Man mano che le dimensioni di rischio si sommano, aumenta la necessità di coinvolgere competenze professionali. Non per sostituire il vibe coder, ma per affiancare competenze specifiche dove servono.

Il punto non è scoraggiare dall'iniziare. Al contrario, sapere dove si collocano i confini permette di muoversi con sicurezza all'interno di quei confini, e di chiedere aiuto quando serve.

Chiarirsi le idee¶

Il vibe coding non inizia con un progetto definito. Inizia con qualcosa di più vago: un problema ricorrente nel proprio lavoro, un'operazione che si ripete sempre uguale, un'intuizione su qualcosa che potrebbe funzionare meglio. Il passaggio da quell'intuizione a un progetto concreto è il primo lavoro da fare, e spesso è il più importante.

Claude può aiutare fin da questo momento. Usare Chat per un brainstorming, descrivendo una situazione che non funziona o un'idea ancora grezza e chiedendo a Claude di fare domande, esplorare possibilità, proporre soluzioni, è spesso il modo in cui un'esigenza sfumata diventa un progetto con una forma riconoscibile. "Passo due ore alla settimana a copiare dati da un foglio Excel all'altro" non è ancora un progetto, ma è il punto di partenza di una conversazione da cui un progetto può emergere.

Quando l'idea ha preso forma, conviene fermarsi a rispondere ad alcune domande prima di iniziare a costruire. Quale problema risolve questa applicazione? Chi la userà? Cosa deve fare, concretamente? Cosa non deve fare? Esiste già qualcosa di simile, e se sì perché non va bene?

Sono domande semplici, ma la loro assenza è la causa più frequente di progetti che partono in una direzione, cambiano rotta più volte e finiscono in un risultato che non soddisfa nessuno. L'AI amplifica questa dinamica perché risponde a qualsiasi richiesta, anche a quelle confuse. Di fronte a istruzioni vaghe non si ferma a chiedere chiarimenti: produce qualcosa, e quel qualcosa è spesso plausibile ma sbagliato nelle premesse.

Oltre al "cosa", vale la pena ragionare anche sul "come", almeno nelle sue linee generali. Anche senza competenze tecniche si possono fare scelte consapevoli. L'applicazione deve funzionare solo sul proprio computer o deve essere raggiungibile da altri? Deve leggere dati da qualche parte, e se sì da dove? Deve produrre un file, mostrare un'interfaccia, inviare una notifica? Queste scelte influenzano il tipo di progetto che Claude costruirà e il livello di complessità che ne deriva.

Non serve un documento formale. Serve la chiarezza mentale che permette di spiegare il progetto a un collega in due minuti, in modo che quel collega capisca cosa si sta costruendo e perché. Se non si riesce a farlo con un essere umano, non si riuscirà a farlo con Claude.

La fase di progettazione¶

Quando si ha chiaro cosa si vuole costruire, il passo successivo è tradurre quell'idea in un piano che Claude possa seguire. La tentazione è saltare direttamente alla costruzione, ma il tempo investito nella progettazione ne fa risparmiare molto di più nelle fasi successive. Un progetto ben descritto produce meno errori, meno riscritture e un risultato più vicino alle aspettative.

Come si progetta dipende dalla modalità di lavoro scelta.

Pianificare in Chat¶

Chi lavora in Chat non ha bisogno di strumenti dedicati, perché il dialogo con Claude è già, per sua natura, un processo di raffinamento progressivo. Il punto è rendere questo processo intenzionale.

Prima di chiedere a Claude di costruire qualcosa, conviene descrivere il progetto e chiedere esplicitamente di analizzarlo. Quali componenti servono? Quali problemi potrebbe incontrare? Quale approccio è più adatto? Claude risponde con una proposta, si discute, si aggiusta, si ripete. Il codice viene scritto solo quando il piano è chiaro per entrambi.

La differenza tra "fammi un'app che fa X" e "analizziamo insieme cosa serve per fare X, poi costruiamo" è la stessa differenza tra sperare che vada bene al primo tentativo e sapere cosa si sta costruendo.

Pianificare per Cowork¶

Cowork lavora in autonomia. Una volta avviato un compito, Claude pianifica, esegue e consegna il risultato senza chiedere conferme intermedie. Questo rende la progettazione ancora più importante, perché tutto ciò che non è stato chiarito prima diventa una decisione che Claude prenderà da solo.

In pratica, la progettazione per Cowork è il lavoro che si fa prima di premere invio. Le istruzioni devono essere più complete e strutturate di quanto servirebbe in Chat, perché non ci sarà la possibilità di correggere il tiro durante l'esecuzione. Il risultato che si ottiene dipende quasi interamente dalla qualità delle istruzioni iniziali.

Il pattern più efficace, già descritto nel capitolo precedente, è usare Chat per la fase di ragionamento e poi passare a Cowork per l'esecuzione. In Chat si definisce cosa serve, si discutono le alternative, si arriva a un piano dettagliato. Quel piano diventa l'istruzione per Cowork.

La modalità pianificazione in Code¶

Code offre quattro modalità operative, selezionabili dal menu a tendina nella barra inferiore dell'interfaccia. La terza opzione, Modalità pianificazione, è pensata esattamente per separare il ragionamento dall'esecuzione.

Quando è attiva, Claude può leggere tutto il progetto, analizzare i file, cercare pattern e proporre una strategia, ma non può modificare nulla. Nessun file viene toccato, nessun comando viene eseguito. Il risultato è un piano strutturato che descrive quali file modificare, in quale ordine e perché.

A quel punto si rivede il piano, si chiede di modificarlo se necessario, e si itera fino a quando è soddisfacente. Solo dopo l'approvazione si passa a una delle modalità operative e si lascia eseguire.

Le quattro modalità, nell'ordine in cui appaiono nel menu, corrispondono a livelli crescenti di autonomia. Richiedi autorizzazioni chiede conferma prima di ogni modifica. Accetta automaticamente le modifiche esegue senza chiedere. Modalità pianificazione analizza senza modificare. Ignora autorizzazioni accetta tutto, compresi i permessi di sistema, ed è pensata per ambienti controllati.

Descrivere ciò che si vuole¶

Nel vibe coding la descrizione del progetto non è un prompt nel senso abituale del termine. Non è una domanda a cui Claude risponde, è una specifica di progetto che Claude traduce in codice. La qualità della specifica determina la qualità del risultato.

Una buona specifica si costruisce in due passaggi. Il primo è un abstract che descrive il progetto in modo sintetico, legando fra loro i quattro elementi fondamentali: cosa fa l'applicazione (l'obiettivo), in quale situazione e per chi (il contesto), entro quali limiti deve muoversi (i vincoli) e cosa ci si aspetta di vedere quando funziona (l'output atteso). L'abstract dà a Claude il quadro d'insieme prima dei dettagli, e questo migliora sensibilmente la qualità delle decisioni che prenderà durante la costruzione.

Il secondo passaggio è l'approfondimento di ciascun elemento. L'obiettivo diventa una lista di funzionalità concrete. Il contesto spiega chi userà l'applicazione e in quale flusso di lavoro si inserisce. I vincoli specificano tecnologie, formati, servizi da integrare o da evitare. L'output atteso descrive l'interfaccia, il comportamento e i casi d'uso principali.

La differenza si vede con un esempio. Una descrizione vaga come "fammi un'app per gestire i miei appunti" lascia a Claude ogni decisione. Un abstract come "un'applicazione web locale per scrivere appunti in markdown, salvarli come file nella cartella Documenti, cercarli per parola chiave e visualizzarli con la formattazione" è già molto meglio, ma lascia ancora aperte domande importanti. Come si scrivono gli appunti, in un editor dedicato o in un campo di testo semplice? Come si assegna il nome al file, lo sceglie l'utente o viene generato dal titolo? La ricerca è sul titolo o anche sul contenuto?

Una specifica completa risponde a queste domande:

Un'applicazione web locale per gestire appunti in markdown. L'interfaccia ha due pannelli affiancati: a sinistra l'elenco degli appunti esistenti con un campo di ricerca, a destra l'editor. L'editor usa un campo di testo con evidenziazione della sintassi markdown. Sotto il titolo, un'anteprima dal vivo mostra il risultato formattato. Il nome del file viene generato automaticamente dal titolo dell'appunto, convertendo gli spazi in trattini e rimuovendo i caratteri speciali. I file vengono salvati nella cartella Documenti/Appunti. La ricerca funziona sia sul titolo sia sul contenuto del file.

Questo non significa che la prima descrizione debba raggiungere questo livello di dettaglio. Il vibe coding è un processo iterativo, e Claude può aiutare a raffinare la specifica attraverso il dialogo. Ma partire con almeno un buon abstract riduce drasticamente il numero di iterazioni necessarie.

Un criterio pratico per valutare se la descrizione è abbastanza chiara: immaginarla rivolta a un collega competente ma che non sa nulla del progetto. Se quel collega capirebbe cosa deve costruire, Claude lo capirà. Se quel collega farebbe domande, è meglio rispondere a quelle domande prima di premere invio.

Un ultimo aspetto, facile da trascurare. Descrivere cosa l'applicazione non deve fare è spesso altrettanto utile quanto descrivere cosa deve fare. "Non deve richiedere un database esterno", "non deve avere un sistema di login", "non deve modificare file fuori dalla sua cartella" sono vincoli che evitano a Claude di prendere decisioni che poi tocca smontare.

Il metodo spec.md + todo.md¶

Quando un progetto supera la complessità di una singola richiesta in Chat, conviene scrivere la specifica in un file separato. Due documenti di testo nella cartella del progetto, uno per la specifica e uno per le attività, sono sufficienti a dare struttura al lavoro.

Il file spec.md è la versione scritta dell'abstract e dell'approfondimento descritti nella sezione precedente. Contiene la descrizione del progetto, il pubblico a cui è destinato, le funzionalità previste, i vincoli tecnici e qualsiasi decisione già presa. Non ha un formato rigido, ma deve rispondere alle stesse domande: cosa fa, per chi, come, con quali limiti. Più la specifica è chiara, meno ambiguità restano a Claude.

Il file todo.md è una lista ordinata di attività, ciascuna abbastanza piccola da poter essere completata e verificata in un singolo passaggio. L'idea è scomporre il progetto in passi che Claude esegue uno alla volta, verificando il risultato di ciascuno prima di passare al successivo.

Un esempio concreto. Per l'applicazione di appunti in markdown descritta nella sezione precedente, il todo.md potrebbe avere questa struttura:

## Todo

- [ ] Creare la struttura del progetto (cartelle, file HTML, CSS e JS di base)
- [ ] Implementare l'editor markdown con campo di testo ed evidenziazione sintassi
- [ ] Aggiungere l'anteprima dal vivo sotto l'editor
- [ ] Implementare il salvataggio come file nella cartella Documenti/Appunti
- [ ] Generare il nome del file dal titolo dell'appunto
- [ ] Creare il pannello laterale con l'elenco degli appunti esistenti
- [ ] Aggiungere la ricerca per titolo e contenuto
- [ ] Testare il flusso completo: creare, salvare, cercare, riaprire

Il flusso di lavoro segue una sequenza naturale. Si parte dal brainstorming in Chat per definire l'idea e si compila spec.md con la descrizione completa, costruendolo insieme a Claude attraverso il dialogo. Quando la specifica è stabile, la generazione del piano di lavoro si può affrontare in modi diversi a seconda della modalità scelta.

In Chat si può chiedere a Claude di scomporre la specifica in attività ordinate e generare direttamente il todo.md. È un compito di analisi che Claude fa bene, perché ha appena lavorato sulla specifica e ne conosce la struttura. Il todo.md va rivisto e aggiustato, ma partire da una proposta generata è più rapido che scriverlo da zero.

In Cowork si può passare direttamente con il solo spec.md. Cowork crea autonomamente il proprio piano di lavoro prima di eseguire, scomponendo il progetto in passaggi che affronta in sequenza. In questo caso il todo.md esplicito non serve, perché la pianificazione è parte del flusso operativo di Cowork.

In Code si può usare la modalità pianificazione descritta nella sezione precedente. Claude legge il spec.md, analizza il progetto e produce un piano strutturato senza toccare nulla. Si rivede il piano, si itera, e solo dopo l'approvazione si passa all'esecuzione.

La differenza tra le tre strade è nel grado di controllo. Con il todo.md scritto in Chat si decide in anticipo l'ordine e la granularità dei passaggi. Con Cowork si delega anche la scomposizione, fidandosi della qualità della specifica iniziale. Con la modalità pianificazione di Code si rivede e approva il piano prima dell'esecuzione.

Dopo ogni attività completata, conviene verificare che tutto funzioni prima di procedere alla successiva. In Code questo è anche il momento giusto per fare un commit, ovvero salvare una versione del progetto a cui si può tornare se qualcosa va storto nei passaggi successivi. Il capitolo sulla sicurezza spiegherà come farlo in pratica.

Questo metodo non è obbligatorio e non serve per ogni progetto. Per un progetto semplice che si costruisce in una conversazione in Chat, sarebbe eccessivo. Ma quando il progetto ha più di quattro o cinque componenti che devono funzionare insieme, avere una mappa scritta di dove si sta andando e a che punto si è fa la differenza tra un progetto che arriva in fondo e uno che si perde per strada.

Il file CLAUDE.md¶

Nel capitolo precedente il file CLAUDE.md è stato presentato come documento di istruzioni permanenti, condiviso tra Cowork e Code. Qui il tema è pratico: cosa metterci e come farlo evolvere con il progetto.

CLAUDE.md è un file di testo nella cartella del progetto che Claude legge automaticamente all'inizio di ogni sessione. Contiene istruzioni che restano valide per tutta la durata del progetto, a differenza dei messaggi in chat che si perdono quando la conversazione finisce o viene compattata.

Il contenuto tipico rientra in tre categorie.

Decisioni tecnologiche. Le scelte di fondo del progetto: quale linguaggio, quali librerie, quale struttura di cartelle, quale formato per i dati. Scrivere queste decisioni nel CLAUDE.md evita che Claude proponga alternative diverse a ogni nuova sessione. Se il progetto usa React con TypeScript e i dati vanno salvati in JSON, dirlo nel CLAUDE.md significa non doverlo ripetere ogni volta.

Convenzioni. Le regole che il codice deve seguire: come nominare i file, come organizzare le funzioni, quale stile di formattazione usare, in quale lingua scrivere i commenti. Sono preferenze che non hanno una risposta giusta o sbagliata, ma che devono restare coerenti in tutto il progetto.

Errori da non ripetere. Questa è la categoria più utile e quella che cresce più naturalmente. Ogni volta che Claude commette un errore o prende una decisione sbagliata, aggiungere un'istruzione che lo previene per il futuro trasforma un problema in un miglioramento permanente. "Non usare localStorage, i dati vanno salvati su file" oppure "non modificare mai i file nella cartella config senza chiedere conferma" sono esempi di istruzioni nate da errori concreti.

Un CLAUDE.md per un progetto di vibe coding potrebbe avere questo aspetto:

# Progetto: Gestore appunti markdown

## Stack tecnologico
- HTML, CSS e JavaScript vanilla (nessun framework)
- I dati vengono salvati come file .md nella cartella Documenti/Appunti
- Nessun database, nessun server esterno

## Convenzioni
- Nomi dei file in italiano con trattini come separatore
- Commenti nel codice in italiano
- Un file JS per ogni funzionalità principale

## Attenzione
- Non creare mai file fuori dalla cartella del progetto
- Non usare localStorage: i dati vanno salvati su file
- Testare sempre il salvataggio e il caricamento dopo ogni modifica

Il file non deve essere lungo né formale. Deve contenere le informazioni che servono a Claude per lavorare bene su questo specifico progetto. All'inizio sarà breve, poche righe sullo stack e le convenzioni di base. Col tempo crescerà, arricchito dalle lezioni apprese durante la costruzione.

In Code il CLAUDE.md ha anche una gerarchia. Il file nella cartella principale del progetto si applica a tutto il progetto. File CLAUDE.md in sottocartelle possono aggiungere istruzioni specifiche per quella parte del codice. Un file globale nella cartella dell'utente si applica a tutti i progetti. Per la maggior parte dei progetti di vibe coding, un singolo file nella cartella principale è sufficiente.