Progetti più complessi¶

Il primo progetto ha mostrato il ciclo fondamentale (descrivere -> generare -> testare -> correggere), il risultato può essere un'applicazione singola, un framework, un'interfaccia. Funziona, è utile, risolve un problema concreto.

Questo capitolo racconta due progetti di natura diversa. Il primo è un sistema di documentazione fatto di componenti che devono funzionare insieme (configurazione + script + pipeline di automazione + fogli di stile), il secondo è un'arena di discussione tra agenti AI (architettura client-server + chiamate API a servizi esterni + orchestrazione di processi indipendenti).

Dopo il capitolo precedente do per buono che il metodo sia stato acquisito, qui non c'è una guida passo dopo passo ma il racconto si concentra sulle decisioni, sui problemi che emergono quando la complessità cresce, e su ciò che si impara affrontandoli.

Un sistema di documentazione¶

Il sito che ospita questo manuale è esso stesso un progetto di vibe coding. Non è nato come esercizio ma da un'esigenza professionale precisa e la sua costruzione illustra un tipo di complessità diverso da quello di un'applicazione singola.

Il problema¶

Nella mia attività di formatore e divulgatore sulle AI generative, condivido regolarmente tutorial e manuali. Per mesi il formato è stato il PDF, pratico da distribuire, familiare a tutti, facile da creare. Ma i PDF hanno un limite strutturale, sono statici, aggiornare un manuale significa rigenerare l'intero file, redistribuirlo, sperare che chi lo aveva scaricato trovi la versione nuova. In un campo che cambia ogni settimana, questo diventa un problema serio.

L'idea era costruire un posto in cui i manuali fossero sempre aggiornati, navigabili, ricercabili, e dove chi arriva potesse vedere subito cosa c'è di disponibile. Non un blog con articoli sparsi, ma una piattaforma di documentazione strutturata. Con l'obiettivo strategico di posizionarmi come riferimento su argomenti specifici, in particolare l'ecosistema di Claude e NotebookLM. E con un'ambizione ulteriore, raggiungere un pubblico internazionale pubblicando ogni manuale sia in italiano sia in inglese.

Le scelte architetturali¶

La discussione iniziale è avvenuta in Chat. La descrizione del problema e degli obiettivi ha portato Claude a proporre MkDocs con il tema Material for MkDocs, ospitato su GitHub Pages. La scelta si basava su criteri concreti: - i contenuti si scrivono in markdown, un formato leggibile e modificabile con qualsiasi editor di testo - il deploy è automatico, si pubblica con un commit su GitHub - il tema Material offre navigazione, ricerca, modalità chiara e scura, tutto già pronto - infine il costo è zero, sia per lo strumento sia per l'hosting.

Nessuna di queste scelte è stata proposta da me, non avendo la competenza tecnica per valutare le alternative tra generatori di siti statici, confrontare i sistemi di hosting o scegliere un tema. La divisione del lavoro è stata netta, ho raccontato cosa volevo, Claude ha proposto un ventaglio di ipotesi tecniche, spiegandomi per ognuna le caratteristiche e le conseguenze nell'adottarla. In base a queste spiegazioni ho scelto tra le opzioni proposte.

Questa dinamica è diversa da quella del primo progetto. Con PyMuPDF4LLM GUI la scelta architetturale è stato un singolo passo, con il sistema di documentazione c'è stata una sequenza di scelte seguendo una sorta di struttura ad albero, con ogni nodo che influenzava le proposte del livello successivo.

La costruzione progressiva¶

A differenza di un'applicazione che si costruisce e poi si usa, il sistema di documentazione è cresciuto per strati successivi. Il primo strato è stato un sito minimale con un solo manuale, una configurazione di base e il deploy su GitHub Pages. Funzionava, era online, si poteva leggere. Il primo manuale pubblicato riguardava proprio MkDocs e GitHub Pages, documentando il processo di costruzione mentre avveniva.

Il secondo strato ha aggiunto la struttura per ospitare più manuali. Il sito è un monorepo, un unico repository che contiene tutte le guide come sezioni separate. La navigazione usa tab tematici nella barra superiore che raggruppano i manuali per categoria, con la sidebar che mostra l'indice del manuale selezionato. Questa organizzazione è stata progettata per scalare: aggiungere un nuovo manuale significa creare una cartella, aggiungere le pagine e aggiornare la configurazione, senza toccare nulla di ciò che già esiste.

Il terzo strato è stato il più complesso: la generazione automatica dei PDF. L'idea era che chi preferisce il formato tradizionale possa scaricare l'intero manuale come PDF, con copertina, indice generato automaticamente, numerazione delle pagine e footer con la licenza. Ma a differenza di un'esportazione banale, il sistema doveva generare un PDF che fosse un prodotto editoriale curato, non un dump del sito web.

Il problema più ostico¶

La pipeline PDF è stata la parte che ha richiesto più iterazioni. Il sistema finale coinvolge quattro componenti separati che devono lavorare insieme, un plugin di MkDocs che genera un PDF per ogni singola pagina, uno script Python che genera automaticamente un indice analizzando la struttura dei capitoli, un secondo script che assembla i PDF individuali e un workflow di GitHub Actions che orchestra l'intero processo a ogni pubblicazione.

Ciascuno di questi componenti ha funzionato relativamente presto in isolamento. I problemi sono emersi dall'interazione unendo i pezzi, l'ordine di assemblaggio dei PDF non corrispondeva all'ordine dei capitoli nella navigazione, l'indice generato includeva la copertina tra i capitoli, il foglio di stile per la stampa interferiva con gli elementi del sito web. Ogni correzione a un componente rischiava di rompere qualcosa in un altro.

La lezione è che in un sistema fatto di componenti interdipendenti, il testing deve diventare più esigente. Non basta verificare che ogni pezzo funzioni, bisogna verificare che funzionino insieme. E il ciclo descrivere-generare-testare-correggere si applica non ai singoli componenti ma al sistema nel suo insieme: si pubblica, si scarica il PDF, si controlla il risultato, si corregge.

I risultati¶

Il sistema di documentazione è online da metà dicembre 2025. In quattro mesi i manuali hanno totalizzato quasi 900 download PDF, con la guida su NotebookLM che da sola ne rappresenta quasi il 90%, distribuiti tra la versione italiana e quella inglese. Il sito si è posizionato in prima pagina su Google per ricerche come "Claude NotebookLM" o "NotebookLM MCP".

Ma il risultato più significativo non è nei numeri. Il sistema di documentazione ha generato altri progetti. La necessità di pubblicare regolarmente sul blog ha portato alla creazione di una skill dedicata per la scrittura e l'ottimizzazione degli articoli. La necessità di misurare i risultati ha portato all'integrazione di un sistema di analytics con tracciamento personalizzato dei download. Ogni componente aggiunto ha esteso le capacità della piattaforma, che a sua volta ha suggerito nuove possibilità.

Questo è un pattern che si incontra quando un progetto di vibe coding smette di essere un'applicazione isolata e diventa un sistema: ogni pezzo che si aggiunge apre la porta ad altri pezzi. Il sistema cresce organicamente, guidato dalle esigenze reali che emergono dall'uso.

Un'arena di discussione tra agenti¶

Il secondo progetto nasce da un'intuizione diversa. Non dalla necessità di risolvere un problema pratico immediato, ma dall'osservazione di un'assenza, tra le applicazioni basate sull'intelligenza artificiale, nessuna sembrava mettere al centro l'architettura agentica come strumento utilizzabile da tutti.

L'idea¶

L'obiettivo era costruire qualcosa di pratico, facile da usare e agnostico rispetto al fornitore di AI. Il target era ampio ma con tratti comuni: professionisti autonomi, piccoli studi, piccole e medie imprese. Persone che non sono esperti tecnici ma che hanno una predisposizione ad approfondire gli aspetti pratici dell'AI, ad esempio imparare a usare le API. Persone che avrebbero bisogno di un team di esperti per analizzare un problema da prospettive diverse, ma che non possono permetterselo per motivi di budget o di tempistiche. E persone che trattano informazioni riservate, avvocati con i fascicoli dei clienti, consulenti con i dati finanziari, medici con le cartelle cliniche, e che quindi hanno bisogno di una soluzione che funzioni interamente in locale, senza che i dati escano dal proprio computer.

L'idea concreta era un'arena di discussione strutturata in cui partecipanti virtuali, ciascuno con un ruolo, una prospettiva e uno stile comunicativo definiti, discutono uno scenario fornito dall'utente. Un moderatore apre la discussione, i partecipanti argomentano per più round rispondendosi a vicenda, e alla fine il moderatore emette un verdetto motivato. Questa situazione, il panel di esperti, trova applicazioni in campi molto diversi, ad esempio analisi legale, revisione clinica, pianificazione strategica, valutazione del rischio, dibattito accademico.

La genesi¶

Questo progetto illustra una dinamica che il capitolo precedente ha solo accennato, il vibe coding che inizia prima di sapere che si sta facendo vibe coding. Ne avevo già parlato in questo articolo.

Nella mia esperienza, il progetto è nato come conversazione in Chat. Ho descritto l'idea, il tipo di applicazione che immaginavo, il pubblico a cui era destinata. Claude ha iniziato a proporre soluzioni, a esplorare le implicazioni architetturali, a suggerire funzionalità. La conversazione è passata gradualmente dal "ne stiamo discutendo" al "lo stiamo progettando" senza un momento preciso in cui la transizione è avvenuta. A un certo punto il progetto esisteva come specifica, e il passaggio alla costruzione, in Cowork, è stato naturale.

Questo percorso è probabilmente quello più comune per chi usa l'AI quotidianamente. Non si parte da una decisione formale ("oggi costruisco un'applicazione"), si parte da un problema o da un'idea e la conversazione con l'AI porta naturalmente verso una soluzione costruibile.

L'architettura¶

L'applicazione finale ha un'architettura che riflette i requisiti iniziali, è composta da un file HTML che contiene tutta l'interfaccia, la logica e lo stile, e un server proxy in Python che fa da intermediario tra il browser e i servizi AI. Il server proxy usa solo la libreria standard di Python, nessuna dipendenza esterna da installare.

Queste scelte, tutte proposte da Claude, rispondono ai vincoli del progetto. L'assenza di dipendenze rende l'installazione banale, si scarica il progetto, si lancia lo script Python, si apre il browser. Niente npm install, niente Docker, niente configurazione complessa. Il supporto multi-provider, Anthropic, OpenAI, Google Gemini, DeepSeek e qualsiasi servizio compatibile con le API di OpenAI, garantisce l'agnosticismo rispetto al fornitore. E il supporto per modelli locali tramite Ollama, LM Studio o altro framework risolve il requisito della privacy, quando si usa un modello locale nessun dato esce dal computer.

Il concetto architetturale più interessante è quello alla base del funzionamento, ogni partecipante alla discussione è una chiamata API indipendente. Ogni agente riceve il proprio ruolo, la trascrizione cumulativa della discussione e le istruzioni per il turno corrente, ma non ha accesso al processo generativo degli altri partecipanti. Non "sa" cosa hanno pensato gli altri, vede solo cosa hanno detto. Questa separazione produce voci autenticamente distinte, perché ogni agente parte da un contesto pulito e costruisce la propria argomentazione in modo indipendente.

La complessità nuova¶

Rispetto al primo progetto, ADA introduce un tipo di complessità che non si può risolvere semplicemente testando l'interfaccia. L'architettura client-server, con il browser che comunica con il proxy e il proxy che comunica con il servizio AI, aggiunge punti di possibile rottura invisibili all'utente. Un errore di autenticazione con il provider, un timeout su un modello locale lento, un problema di certificati SSL su Windows sono tutti problemi che non si manifestano come "il pulsante non funziona" ma come messaggi di errore tecnici che richiedono interpretazione.

Qui il ruolo dell'autore cambia. Nel primo progetto il testing era prevalentemente funzionale. Il PDF si converte? Il markdown è leggibile? Le immagini sono gestite correttamente? In un progetto con architettura più articolata, una parte del testing diventa diagnostica. Bisogna saper leggere un messaggio di errore, anche senza capirne i dettagli tecnici, e riportarlo a Claude in modo che possa proporre una soluzione. La capacità di comunicare un problema con precisione diventa ancora più importante della capacità di risolverlo.

Un'altra dimensione di complessità riguarda il consumo di risorse. Ogni turno di discussione è una chiamata API che include il documento allegato, la trascrizione cumulativa e le istruzioni. Con un documento di 100 kilobyte, due partecipanti e due round di discussione, il sistema effettua otto chiamate API ciascuna delle quali trasporta l'intero documento. Per i provider cloud questo si traduce in costi, per i modelli locali in tempi di elaborazione. Comprendere questa dinamica non richiede competenze tecniche, ma richiede la capacità di ragionare su come l'architettura influenza l'uso pratico.

Il collegamento con il primo progetto¶

C'è un collegamento diretto tra questo progetto e quello del capitolo precedente che vale la pena raccontare. PyMuPDF4LLM GUI, il convertitore di PDF in markdown, è nato dall'osservazione di una soluzione implementata dentro ADA. Per gestire il consumo di token dei documenti allegati, Claude aveva proposto di integrare la libreria PyMuPDF4LLM per convertire i PDF in markdown prima di passarli al modello, riducendo drasticamente il peso del testo. Osservando quella soluzione al lavoro, l'intuizione è stata che la stessa conversione poteva essere utile a chiunque lavori con i PDF nelle conversazioni con i modelli linguistici, non solo dentro ADA ma in qualsiasi contesto. Il pensiero successivo è che per rendere facilmente usabile la libreria, progettata per l'uso da terminale o tramite script, serviva un'interfaccia grafica. Il progetto del capitolo precedente è nato così.

Questo percorso, un progetto che genera un'idea per un altro progetto, è una delle dinamiche più produttive del vibe coding. Non avviene per pianificazione ma per esposizione, lavorare a un problema mette in contatto con soluzioni che si applicano anche altrove.

I risultati¶

Il progetto è disponibile come repository pubblico su GitHub e può essere installato e utilizzato da chiunque seguendo le istruzioni nel README. L'architettura si è rivelata sufficientemente solida da essere adattata anche come skill, dove la stessa logica di discussione strutturata con agenti indipendenti funziona senza bisogno di un proxy esterno, perché Claude stesso diventa il modello che genera gli interventi dei partecipanti.

Cosa cambia quando la complessità cresce¶

I due progetti raccontati in questo capitolo, insieme a quello del capitolo precedente, permettono di osservare come cambia il lavoro quando la complessità aumenta.

La prima differenza riguarda la costruzione progressiva. Un'applicazione semplice si può costruire in una sessione e ottenere un risultato funzionante. Un sistema come la piattaforma di documentazione cresce per strati, ciascuno dei quali aggiunge una capacità e introduce nuove interazioni da gestire. Questo richiede un approccio diverso alla pianificazione: non si progetta tutto all'inizio, si progetta il primo strato funzionante e poi si aggiungono componenti sulla base delle esigenze reali che emergono dall'uso.

La seconda differenza riguarda il ruolo dell'autore. Nel primo progetto la competenza principale è il testing funzionale, verificare che il risultato faccia ciò che deve fare. Nei progetti più ambiziosi si aggiungono competenze diverse: la capacità di prendere decisioni architetturali scegliendo tra opzioni proposte da Claude, la capacità di diagnosticare problemi che non si manifestano in modo evidente, la capacità di ragionare sulle implicazioni di lungo termine delle scelte fatte. Nessuna di queste richiede competenze di programmazione, ma tutte richiedono la capacità di pensare in modo sistematico.

La terza differenza è che un progetto genera altri progetti. Il sistema di documentazione ha generato la skill per il blog, il sistema di analytics, e una serie di strumenti complementari. ADA ha generato l'idea per PyMuPDF4LLM GUI e successivamente la skill che porta la stessa architettura dentro Claude Desktop. Questo è un effetto che non si può pianificare ma che si verifica regolarmente: lavorare a un problema espone a soluzioni che si applicano anche altrove, e ogni progetto completato diventa un fondamento su cui costruire il successivo.

Infine, c'è una differenza che riguarda la gestione delle sessioni di lavoro. Un progetto semplice si esaurisce in una conversazione. Un progetto complesso richiede più sessioni, e questo introduce il problema della continuità: Claude non ricorda le conversazioni precedenti a meno che non gli si fornisca il contesto. Strumenti come il file CLAUDE.md, la specifica del progetto e il file di stato diventano indispensabili non come burocrazia ma come memoria del progetto, il ponte tra una sessione e la successiva.