Come esplorare una codebase con Claude Code senza modificarla

Apri un repository che non conosci e chiedi: «Spiegami come funziona». La risposta può sembrare ordinata, ma resta difficile capire quali parti derivino dai file letti e quali siano collegamenti plausibili costruiti dal modello.

Per esplorare una codebase con Claude Code serve una domanda più concreta e una consegna verificabile. Il risultato non è un riassunto del repository: è una mappa limitata a una decisione, con percorsi, flussi, prove e incognite ancora aperte.

La guida ai workflow di Claude Code suggerisce di partire da una panoramica e restringere progressivamente su componenti, modelli e flussi di esecuzione. Il passaggio decisivo è trasformare questa sequenza in un documento che un'altra persona possa controllare.

Parti dalla decisione che devi prendere

“Capire il progetto” non ha un confine. Può significare trovare il punto in cui entra una richiesta, sapere dove viene salvato un dato oppure valutare se una modifica toccherà il sistema di autenticazione.

Scrivi prima la decisione che l'esplorazione deve rendere possibile. Per esempio:

• devo stimare l'impatto di un nuovo campo nel profilo;

• devo capire chi produce e chi consuma un report;

• devo individuare dove viene applicata una regola di autorizzazione;

• devo preparare il passaggio di consegne a un nuovo manutentore.

La decisione seleziona ciò che conta. Senza questo limite, Claude può continuare a leggere file utili in astratto e riempire il contesto senza avvicinarsi al problema.

Separa orientamento e implementazione

Durante l'orientamento chiedi letture, ricerche e comandi che osservano lo stato. Non chiedere ancora di correggere, rinominare o “migliorare ciò che trova”. Una proposta di modifica cambia la domanda: da “come funziona?” a “come dovrebbe funzionare?”.

Le best practice di Claude Code distinguono esplorazione, piano e implementazione quando il problema è incerto. Qui la consegna termina al primo passaggio. Se dalla mappa nascerà un intervento, apri un incarico separato con criteri di accettazione propri.

Una richiesta iniziale può essere:

Esplora il flusso con cui una modifica al profilo passa dalla UI al salvataggio.
Non modificare file. Riporta percorsi, simboli, test esistenti e punti non verificati.
Per ogni conclusione indica l'evidenza che hai letto o il comando che hai eseguito.

Il divieto di modifica non rende vera la risposta. Evita però che l'orientamento e la soluzione si confondano nello stesso delta.

Costruisci la mappa in cinque livelli

Una mappa utile può stare in cinque livelli. Non sono cartelle obbligatorie: sono domande che impediscono di saltare direttamente da un file al racconto dell'intero sistema.

Se un livello non ha evidenza, non riempirlo per simmetria. Scrivi “non verificato” e indica il prossimo controllo. Un vuoto dichiarato è più utile di un collegamento inventato.

Questo schema si affianca a un inventario dei workflow AI: l'inventario sceglie quale processo merita attenzione, mentre la mappa mostra come quel processo è rappresentato nel repository.

Passa da domande larghe a un flusso concreto

Inizia con la struttura: linguaggi, cartelle principali, comandi di avvio, test e documentazione. Poi scegli un solo comportamento e chiedi di seguirlo da un'estremità all'altra.

La documentazione ufficiale propone domande come “quali sono i modelli principali?” e “come viene gestita l'autenticazione?”, poi invita a trovare i file pertinenti e tracciare il flusso. Adatta il metodo al lessico del progetto. Se il team parla di “richiesta”, non sostituire automaticamente il termine con “ticket” o “ordine”.

Chiedi riferimenti puntuali:

Per ogni passaggio indica file, simbolo e motivo del collegamento.
Se deduci una relazione senza chiamata diretta, segnala che è un'inferenza.
Non includere componenti che non partecipano al flusso scelto.

Alla fine dovresti poter aprire i file nell'ordine indicato e ricostruire lo stesso percorso.

Tieni un quaderno delle evidenze

Una mappa senza provenienza diventa presto un'altra descrizione da fidarsi. Affiancale un quaderno breve con tre stati.

Per ogni riga annota percorso, simbolo o comando. Non incollare interi file: conserva solo il riferimento e il frammento necessario a sostenere la conclusione.

Claude Code costruisce il proprio contesto leggendo file e output durante la sessione, come spiega la guida How Claude Code works. Questo non significa che tutto il repository sia presente o ricordato allo stesso modo. Il quaderno rende esplicito ciò che la risposta usa davvero.

Controlla convenzioni e parole del progetto

Due moduli possono svolgere funzioni simili con regole diverse. Prima di generalizzare, chiedi dove sono dichiarate convenzioni, istruzioni di progetto, pattern di test e nomi del dominio.

Prepara un glossario minimo: termine, significato nel repository, file che lo dimostra. Serve soprattutto quando una parola comune ha un significato locale. “Cliente” potrebbe indicare un record commerciale, un'applicazione che chiama un'API o una libreria esterna.

Controlla anche le eccezioni. Se tre handler usano un servizio comune e il quarto accede direttamente al database, la mappa deve mostrare la deviazione. Non normalizzarla nel racconto solo perché sarebbe più elegante.

Chiedi una controprova

Quando la prima mappa è pronta, non chiedere soltanto di confermarla. Chiedi dove potrebbe essere sbagliata.

Puoi usare tre domande:

1. Quale file contraddice o limita questa spiegazione?

2. Quale percorso alternativo produce lo stesso effetto?

3. Quale comportamento non è coperto dai test trovati?

La controprova sposta Claude dalla sintesi alla ricerca di eccezioni. Se emerge un secondo ingresso, aggiorna la mappa o restringi il titolo: “flusso di aggiornamento dal pannello web” è più onesto di “flusso di aggiornamento del profilo” se esiste anche un'importazione in batch.

Concludi con una scheda di orientamento

La consegna finale deve poter vivere fuori dalla conversazione. Usa una scheda con:

• decisione da supportare;

• commit o stato osservato;

• ingresso e uscita del flusso;

• file e simboli principali;

• dati ed effetti laterali;

• prove esistenti;

• inferenze e incognite;

• prossima domanda, senza piano di modifica.

Collega la scheda al contratto di input di un workflow AI quando l'esplorazione prepara un incarico successivo. Chi riceve la mappa saprà quali elementi sono fatti, quali sono ipotesi e quali dati deve ancora fornire.

Quando fermare l'esplorazione

Fermati quando la decisione iniziale ha evidenze sufficienti, non quando ogni cartella ha una descrizione. Se puoi indicare il percorso del dato, gli effetti, i test e le incognite che cambierebbero la decisione, hai un risultato utilizzabile.

Continua invece se una conclusione dipende da un file non letto, da configurazione esterna o da un ambiente che non puoi osservare. In quel caso la consegna corretta non è una spiegazione più sicura: è un limite con il controllo necessario.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi applicare questa sequenza a un repository reale e trasformare l'esplorazione in una mappa che un collega possa verificare. Solo dopo si decide se serve un piano, una modifica o nessuna azione.