Una fuga di codice, a volte, può diventare qualcosa di incredibilmente utile. È esattamente quello che è successo con Claude Code, uno degli agenti AI per lo sviluppo software più chiacchierati del momento. Il suo funzionamento interno è venuto a galla attraverso file esposti nel registry npm e analisi indipendenti condotte successivamente. Da questa scoperta è nato Claude Code Unpacked, una guida visuale messa insieme in pochissimo tempo che ha permesso di capire davvero come funziona l’architettura di questi sistemi, troppo spesso raccontati in modo superficiale o addirittura fuorviante.
Come funziona Claude Code?
Il contesto è quello di una fase di forte espansione degli agenti autonomi per lo sviluppo software: strumenti capaci di orchestrare comandi, manipolare file e interagire con ambienti locali. L’analisi del codice ha rivelato dimensioni tutt’altro che trascurabili, con oltre 500.000 linee di codice e un livello di complessità che va ben oltre il semplice utilizzo di modelli linguistici. Dietro l’interfaccia di Claude Code si nasconde una logica articolata, fatta di strumenti, controlli e gestione dello stato.
La guida visuale mette in evidenza un punto che viene spesso sottovalutato: il valore non sta solo nei modelli, ma nell’infrastruttura che li governa. Claude Code si basa su un agentic loop, cioè un ciclo iterativo in cui il modello genera azioni, le esegue tramite strumenti e valuta i risultati. Il cuore del sistema poggia su un catalogo di comandi che include operazioni su file, esecuzione di shell e ricerca nel codice. Alcuni strumenti risultano “gated”, cioè soggetti a controlli espliciti prima dell’esecuzione, introducendo un livello di sicurezza operativo che impedisce al modello di compiere azioni distruttive senza conferma. Dettaglio interessante: tra le utility consolidate spicca l’uso di ripgrep, preferito ai classici strumenti Unix per la ricerca testuale ad alte prestazioni. Una scelta che conferma come, nonostante la complessità apparente, molte funzionalità si basino su componenti già noti e ben ottimizzati.
Gestione dello stato e manutenzione del codice
Uno degli aspetti più dibattuti riguarda la gestione dello stato interno. Il sistema originale utilizza Markdown per rappresentare la progressione delle attività, una scelta che però espone il flusso a possibili incoerenze: un modello può ignorare o alterare contenuti testuali senza vincoli reali. Alcuni sviluppatori hanno proposto alternative più robuste, come l’uso di database SQLite cifrati con AES. In quello scenario, lo stato diventa un elemento verificabile e non modificabile arbitrariamente dal modello. Il passaggio da testo libero a struttura vincolata introduce una differenza sostanziale: il sistema non può avanzare se non soddisfa determinate condizioni crittografiche.
Per quanto riguarda le dimensioni, il codice emerso supera le 500.000 linee senza nemmeno considerare i test. Una cifra che, analizzata in termini ingegneristici, suggerisce un team di sviluppo significativo oppure un’elevata produzione automatizzata. Il fenomeno del cosiddetto vibe coding emerge con chiarezza: codice generato rapidamente, spesso ridondante e poco strutturato. Alcuni elementi lo confermano in modo evidente: directory generiche come “utils” usate come contenitori universali, scarsa separazione delle responsabilità e duplicazioni logiche. Non si tratta di anomalie isolate, ma di segnali tipici di codice prodotto con forte assistenza automatica. Una base di codice ampia non è di per sé un problema; lo diventa quando la manutenzione richiede interventi complessi e poco prevedibili. Negli ambienti agentici, ogni errore può propagarsi attraverso il ciclo decisionale del modello, amplificando l’impatto di bug apparentemente marginali.
Dal codice statico a un’esperienza esplorabile e interattiva
Il primo elemento distintivo del progetto Claude Code Unpacked è la scelta metodologica alla base: invece di limitarsi a descrivere il sistema, lo sviluppatore ha costruito una vera e propria mappa interattiva del codice. Partendo da un codebase estremamente esteso come quello di Claude Code, ha effettuato una scomposizione per domini funzionali (tools, comandi, servizi, componenti UI) e li ha resi navigabili attraverso una struttura visuale gerarchica. L’obiettivo dichiarato era proprio quello di creare una “quick reference” per orientarsi rapidamente nella complessità di Claude Code e organizzare in modo ragionato tutti i pattern osservati. Il risultato è uno strumento accessibile in punta di clic, che riduce drasticamente il costo cognitivo necessario per comprendere un sistema agentico reale.
Uno degli aspetti più sofisticati del progetto è la capacità di isolare e rappresentare i pattern fondamentali del sistema. L’autore non si limita a mostrare file e cartelle, ma estrae concetti chiave come l’agent loop, il sistema di tool e il catalogo dei comandi, rendendoli elementi navigabili e comprensibili anche senza leggere il codice originale. Questo tipo di astrazione richiede una reinterpretazione semantica del software: si passa dal livello sintattico (funzioni, classi) a quello operativo (flussi, decisioni, orchestrazione). È esattamente ciò che manca nella maggior parte della documentazione tecnica tradizionale. Claude Code Unpacked introduce implicitamente un nuovo approccio alla documentazione dei sistemi software complessi: non più pagine statiche, ma esperienze interattive che simulano il comportamento del sistema. La sequenza animata dell’agent loop, ad esempio, permette di “vedere” il flusso decisionale dell’AI passo dopo passo, un approccio particolarmente efficace per i sistemi agentici, dove il comportamento emerge da iterazioni e condizioni dinamiche.
