Il primo progetto¶
È arrivato il momento di costruire qualcosa. Questo capitolo guida passo dopo passo nella realizzazione di un primo progetto completo, dall'idea al risultato funzionante, usando Claude Desktop.
Il progetto è volutamente semplice ma utile. Non un esercizio didattico fine a sé stesso, ma uno strumento che risolve un problema concreto e che si continuerà a usare anche dopo averlo costruito.
Scegliere il progetto giusto¶
Un buon primo progetto ha alcune caratteristiche precise. Deve risolvere un problema reale, altrimenti mancherà la motivazione per portarlo a termine. Deve essere abbastanza semplice da essere completato in una singola sessione di lavoro, altrimenti la complessità rischia di scoraggiare. Deve produrre un risultato tangibile che si può testare immediatamente, perché il feedback immediato è ciò che rende il processo efficace.
Altrettanto importanti sono le caratteristiche da evitare. Un primo progetto non dovrebbe richiedere account su servizi esterni, perché ogni integrazione è una fonte potenziale di problemi. Non dovrebbe trattare dati sensibili, per i motivi discussi nel capitolo precedente. Non dovrebbe essere esposto a internet, per evitare complicazioni di sicurezza e deployment.
Il progetto ideale è uno strumento locale, che gira sul proprio computer, che risolve un problema che si incontra regolarmente.
Come nasce l'idea¶
Il progetto raccontato in questo capitolo nasce dalla pratica quotidiana, lavorando allo sviluppo di un'altra applicazione, Claude ha proposto di usare la libreria PyMuPDF4LLM per trasformare i PDF in formato markdown prima di passarli al modello. La riduzione di peso era significativa, perché un PDF è un formato progettato per la resa grafica e il suo peso è dovuto in larga parte alla gestione della formattazione, dei font, del layout e di altri elementi che non sono il testo in sé. La conversione in markdown elimina tutto questo e conserva solo il contenuto testuale strutturato.
L'intuizione successiva è stata che questa conversione non serviva solo per quel progetto specifico. Ogni volta che si carica un PDF come documento di riferimento in una conversazione con un modello linguistico, nella stragrande maggioranza dei casi importa il testo, non la formattazione. Un PDF da 15 megabyte potrebbe diventare un markdown da poche centinaia di kilobyte, con tutto il contenuto rilevante intatto, con un conseguente risparmio di token. Per file particolarmente pesanti o conversazioni particolarmente lunghe, la differenza è concreta.
Il passo finale è stato chiedersi come altri avrebbero potuto trarne vantaggio. La libreria PyMuPDF4LLM si usa da terminale o dentro a script Python, il che la rende inaccessibile a chiunque non abbia dimestichezza con la riga di comando. Un'interfaccia grafica avrebbe trasformato uno strumento per sviluppatori in uno strumento per tutti.
Questo è il percorso tipico di un progetto di vibe coding. Non si parte da un'idea astratta, si parte da un problema incontrato lavorando. La soluzione emerge dal contesto e diventa un progetto quando si riconosce che il problema è condiviso.
Preparazione¶
Con l'idea chiara, il primo passo è preparare l'ambiente di lavoro seguendo il metodo descritto nel capitolo precedente.
La specifica¶
La conversazione in Chat parte dalla descrizione del problema e dell'idea di soluzione. In questo caso la richiesta iniziale è stata diretta: un'interfaccia grafica standalone in cui l'utente apre l'applicazione, carica o trascina un file PDF e ottiene il corrispondente file markdown. L'applicazione deve funzionare interamente in locale, senza inviare dati a servizi esterni, e deve essere rilasciabile su GitHub per permettere ad altri di installarla.
Claude ha risposto con tre proposte di architettura. La più pratica era un'applicazione Python con Flask come server locale: l'utente lancia uno script e il browser si apre automaticamente sulla pagina di conversione. Nessuna installazione complessa, nessun servizio cloud, nessuna dipendenza da piattaforme esterne.
Questa è una delle dinamiche più importanti dei primi minuti di un progetto. Claude non va direttamente alla soluzione, propone alternative e lascia che sia l'autore a scegliere. La scelta architetturale è una decisione dell'autore, non dell'AI. In questo caso la decisione si è basata su un criterio pratico: Flask è una tecnologia consolidata, la struttura è semplice, e il risultato è un'interfaccia web accessibile a chiunque sappia usare un browser.
L'installazione delle dipendenze¶
Il progetto richiede Python e due librerie: PyMuPDF4LLM per la conversione dei PDF e Flask per il server locale. L'installazione avviene con un singolo comando da terminale:
pip install pymupdf4llm flask
Se Python non è già installato sul computer, è necessario scaricarlo dal sito ufficiale python.org. L'installazione è guidata, l'unica accortezza è assicurarsi di selezionare l'opzione "Add Python to PATH" durante il processo, un dettaglio che evita problemi successivi.
Il comando pip install è l'equivalente di installare un'applicazione, si esegue una volta e il risultato resta disponibile. Non è necessario capire cosa fa nel dettaglio, così come non è necessario capire cosa fa l'installazione di qualsiasi altro software.
La scelta della modalità¶
La costruzione è stata fatta in Cowork. La scelta ha una motivazione precisa. Cowork può creare file, organizzare cartelle e lavorare in autonomia sulla struttura del progetto. Per un'applicazione che deve produrre più file (il codice Python, i template HTML, i fogli di stile, gli script di avvio), questa autonomia è un vantaggio significativo rispetto a Chat.
In pratica il lavoro si è svolto con la sequenza descritta nel capitolo precedente: la fase di ragionamento e le scelte architetturali sono avvenute in Chat, poi il progetto è passato a Cowork per la costruzione vera e propria.
Costruzione guidata¶
Questa sezione segue la cronologia reale del progetto. Non è una cronologia idealizzata, include i problemi incontrati, le soluzioni trovate e le decisioni prese strada facendo, perché è da queste situazioni che si impara il metodo.
Il prototipo¶
Il primo risultato è arrivato in pochi minuti. Cowork ha generato autonomamente la struttura del progetto, creando il file Python con il server Flask, la pagina HTML con l'area di trascinamento per i PDF, il meccanismo di conversione, la gestione dei file temporanei. Il prototipo si apriva nel browser, accettava un PDF e produceva un file markdown. Insomma funzionava.
La velocità con cui si ottiene un primo risultato funzionante è una delle caratteristiche più sorprendenti del vibe coding. E anche una delle più pericolose, perché genera l'illusione che il progetto sia quasi finito. In realtà il prototipo è solo il punto di partenza. I problemi emergono dall'uso, non dalla costruzione.
I primi problemi¶
I problemi sono arrivati immediatamente, non dal codice ma dall'uso dell'applicazione.
Le immagini inutilizzabili. La prima versione convertiva le immagini del PDF in stringhe base64, lunghi blocchi di caratteri incomprensibili inseriti direttamente nel markdown. Aperto con un editor di testo base, il risultato è un muro di caratteri senza senso che rende il documento illeggibile. L'opzione è stata rimossa, sostituita con la possibilità di salvare le immagini come file separati.
I percorsi assoluti. Quando si sceglieva di estrarre le immagini come file separati, il markdown conteneva riferimenti a cartelle temporanee del server. Percorsi come /tmp/uploads/12345/immagine.png che non esistono più una volta chiusa l'applicazione. La soluzione è stata creare un archivio ZIP contenente il file markdown e una cartella con le immagini, tutti con percorsi relativi corretti.
I launcher mancanti. Per pubblicare l'applicazione su GitHub servivano script di avvio per Windows e per Mac/Linux, in modo che l'utente potesse lanciare l'applicazione con un doppio clic invece di dover aprire un terminale. Un dettaglio che sembra ovvio a posteriori ma che non era nella specifica iniziale.
Nessuno di questi problemi è stato trovato leggendo il codice, sono stati tutti trovati usando l'applicazione, provandola come la userebbe chiunque altro. Questo è il punto chiave del vibe coding per chi non programma, si può anche non capire come funziona il codice, ma è necessario capire se il risultato funziona. La capacità di testare il prodotto è la competenza fondamentale.
La correzione ha seguito ogni volta lo stesso schema. Si descrive il problema a Claude, possibilmente con uno screenshot o un esempio concreto, e si lascia che trovi la soluzione. Non è necessario suggerire come risolvere il problema, ma occorre saperlo descrivere con precisione.
Il design¶
Una volta risolti i problemi funzionali, l'applicazione faceva quello che doveva fare ma l'aspetto era generico e poco curato. A questo punto è iniziata la fase di lavoro sull'estetica, che ha introdotto una dinamica diversa.
La richiesta a Claude è stata accompagnata da un'indicazione precisa, cioè proporre delle alternative e aspettare prima di applicarne una. La formulazione è stata "raccontale e aspetta prima di applicarle". L'intenzione era valutare le opzioni prima che Claude ne implementasse una, evitando il rischio di dover disfare un lavoro già fatto.
Claude ha descritto cinque stili diversi, ciascuno con una personalità visiva distinta. Due erano interessanti: uno stile editoriale monocromatico e una variante più netta dello stesso approccio. Anziché scegliere sulla base delle descrizioni ho chiesto di preparare i mockup di entrambi per un confronto visivo.
La scelta finale è caduta sullo stile più deciso: angoli netti, tipografia bold, un accento di rosso come unico colore. Un'estetica professionale che comunicava serietà senza bisogno di decorazioni.
Questa fase illustra un principio importante. Nel vibe coding il controllo non si esercita solo sul "cosa" ma anche sul "come" e sul "quando". Chiedere a Claude di proporre senza applicare, di mostrare mockup prima di implementare, di aspettare il giudizio prima di procedere sono tutte forme di controllo sul processo che non richiedono competenze tecniche.
Il problema del trasferimento¶
L'implementazione del nuovo design ha provocato uno dei problemi più ostinati della sessione, e anche uno dei più istruttivi.
Il trasferimento del file HTML dalla sandbox di Cowork al PC Windows ha corrotto il CSS, rendendo l'interfaccia completamente rotta, testo grezzo senza alcuno stile, pulsanti deformati, layout inesistente. Il tipo di problema che, a prima vista, sembra catastrofico.
La soluzione è stata mandare uno screenshot a Claude per mostrare esattamente cosa si vedeva. Descrivere il problema a parole sarebbe stato meno efficace, perché il problema era visivo e la sua natura non era chiara. Claude ha riscritto il file compattando il codice per ridurre i problemi nel trasferimento.
La lezione è doppia. Da un lato, quando qualcosa si rompe in modo incomprensibile, mostrare il problema è spesso più efficace che descriverlo. Dall'altro, le difficoltà più ostinate in un progetto di vibe coding spesso non riguardano la logica dell'applicazione ma "dettagli" come trasferimenti di file, configurazione dell'ambiente, compatibilità tra sistemi. Sono problemi che si risolvono con pazienza e iterazione, anche senza competenze di programmazione.
Le feature non previste¶
A questo punto l'applicazione funzionava e aveva un aspetto professionale. Ma durante l'uso sono emerse esigenze che non facevano parte della specifica iniziale.
Un esempio, il progetto era destinato a GitHub e doveva essere bilingue, inglese come lingua predefinita e italiano come alternativa, con un selettore di lingua per passare dall'una all'altra. Claude in genere mette questo selettore nell'angolo in alto a destra, ma su schermi grandi risulta separato da troppo spazio bianco dall'area di lavoro. La soluzione è stata chiedere di spostare il selettore, la posizione l'ho indicata passandogli uno screenshot con una croce nel punto in cui volevo fosse messo, sotto il pulsante di conversione, una posizione che funzionava bene sia visivamente sia tecnicamente.
La necessità di questa fase conferma che un progetto non è mai completamente definito all'inizio. Nuove esigenze emergono durante la costruzione, dall'uso, dal contesto, dalla consapevolezza crescente di ciò che l'applicazione potrebbe fare. Il metodo spec.md + todo.md descritto nel capitolo precedente è un punto di partenza, non un contratto rigido. La specifica evolve con il progetto.
Il ciclo fondamentale¶
Nello sviluppo di un'app si ritrova un pattern, indipendentemente dal fatto che il problema sia funzionale, estetico o di contesto.
Descrivere. Si spiega a Claude cosa si vuole ottenere, o cosa non funziona nel risultato attuale. La descrizione può essere un testo, uno screenshot, un messaggio di errore copiato e incollato. Più è precisa, migliore sarà il risultato.
Generare. Claude produce la soluzione. Potrebbe essere il codice iniziale di una nuova funzionalità, la correzione di un problema, la riscrittura di un componente. Non è necessario leggere o capire ciò che Claude produce.
Testare. Si prova il risultato. L'applicazione si apre nel browser? Il PDF viene convertito? Il file markdown è leggibile? Le immagini sono gestite correttamente? Il design corrisponde a quanto richiesto? Ogni domanda ha una risposta immediata e verificabile senza competenze tecniche.
Correggere. Se qualcosa non va, si torna al primo passaggio. Si descrive il problema e il ciclo ricomincia.
La differenza tra le fasi non è nel pattern ma nel suo sviluppo, si passa dal "funziona o non funziona" al "funziona ma non ancora come volevo".
Quando il ciclo si blocca¶
A volte il ciclo descrivere-generare-testare-correggere non converge. Si descrive un problema, Claude propone una soluzione, la soluzione introduce un nuovo problema, si corregge, e il problema originale riappare.
Riconoscere un loop è il primo passo per uscirne. Se dopo tre o quattro iterazioni sullo stesso problema la situazione non migliora, continuare nella stessa direzione raramente porta a un risultato. Le strategie che funzionano sono di due tipi.
La prima è cambiare il contesto. Aprire una nuova conversazione e descrivere il problema da zero, senza lo storico dei tentativi falliti. A volte Claude resta intrappolato in un approccio che non funziona e ripartire con una descrizione pulita gli permette di trovare una strada diversa.
La seconda è ridurre l'ambizione. Se l'obiettivo è troppo complesso per essere raggiunto in un singolo passaggio, scomporlo in parti più piccole. Invece di chiedere "fai funzionare il selettore lingua con il layout responsive e l'animazione", chiedere prima solo "fai funzionare il selettore lingua", poi il layout, poi l'animazione. Ogni pezzo verificato singolarmente prima di combinarli.
Quando fermarsi e ripensare¶
C'è un momento, in ogni progetto, in cui la domanda giusta non è "come risolvo questo problema" ma "questo problema vale la pena di essere risolto". Una funzionalità che richiede dieci iterazioni per funzionare potrebbe non essere essenziale. Un aspetto del design che non si riesce a ottenere come si vorrebbe potrebbe essere accettabile in una forma leggermente diversa.
Questa capacità di giudizio, sapere quando un risultato è abbastanza buono, è una competenza dell'autore che nessuna AI può sostituire.
Cosa abbiamo imparato¶
Il progetto è passato da un'idea a un'applicazione funzionante con interfaccia grafica, supporto bilingue e un'estetica professionale in una singola sessione di lavoro. Ecco i punti che si ritroveranno in ogni nuovo progetto.
- Le decisioni architetturali sono dell'autore.
- Il vibe coding non elimina il testing, lo rende ancora più importante.
- Un progetto non è mai completamente definito all'inizio.
- Le difficoltà più ostinate riguardano l'infrastruttura, non la logica.
Il progetto descritto in questo capitolo è disponibile come repository pubblico su GitHub e può essere installato e utilizzato da chiunque seguendo le istruzioni nel README. Il capitolo successivo affronta progetti più complessi, con meno guida passo-passo e più autonomia nella conduzione del lavoro.