Leggere codice con l'AI, non generarlo

Sono entrato in Spatie come back-end developer alla fine di gennaio 2026 e sono stato subito catapultato in un progetto cliente piuttosto grande. La codebase era in sviluppo da giugno 2025 e, quando sono arrivato, era ancora solo a metà, con oltre 150.000+ righe di codice.

È un bel po' di codice da recuperare.

La codifica agentica ha fatto passi da gigante negli ultimi mesi, quindi invece di puntare l'AI sul problema "genera più codice", ho provato il contrario. Le ho chiesto di aiutarmi a capire il codice che c'era già.

Da dove ho iniziato

Per fortuna, i miei colleghi avevano già impostato un buon flusso di lavoro con l'AI sul progetto:

• Laravel Boost
• Un paio di Claude Skills, sia specifici del progetto che globali
• File AGENTS.md e CLAUDE.md sostanziosi
• Una cartella docs/ con note sulla logica di business che erano state chiaramente abbandonate dopo poche settimane

Due di questi hanno fatto il lavoro più pesante.

Laravel Boost è quello sottovalutato. È un server MCP che dà a Claude accesso live a schema, rotte, config, artisan e tinker. Così quando chiedevo "Esiste già un servizio che gestisce X?", Claude poteva usare Boost invece di indovinare dai nomi dei file.

Per quanto riguarda le skill, ho fatto più affidamento su php-guidelines-from-spatie per le nostre convenzioni PHP e Laravel, e su laravel-inertia-react-structure per il frontend. Tra questi, Claude conosce il nostro stile di codice e le nostre convenzioni senza che io debba ripeterle a ogni prompt.

Questa è una base solida, ma non sostituisce la comprensione effettiva del sistema. Quindi ho chiesto a Claude di darmi una panoramica ad alto livello dell'intera codebase.

Da dove iniziare

La prima cosa che consiglierei di provare è la codebase-onboarding skill. Installala, puntala sul tuo progetto e ti restituisce due file:

• Una guida di onboarding che copre stack tecnologico, architettura, punti di ingresso, ciclo di vita delle richieste, convenzioni e attività comuni.
• Un file CLAUDE.md specifico del progetto che copre stack, stile di codice, test e comandi di build.

Se preferisci un approccio diverso, Repomix raggruppa l'intera codebase in un unico file adatto all'AI. Attiva output.compress per rimuovere il codice non strutturale (Tree-sitter sotto il cofano, riduce il conteggio dei token di circa il 70%) e output.tokenCountTree così puoi vedere dove va il tuo budget di contesto. Poi dai il file al tuo LLM, non dovrà scansionare gli stessi file più e più volte.

Inizierei da lì prima di qualsiasi altra cosa, poi userei prompt mirati per approfondire domini specifici.

Prompt che continuavo a usare

Una cosa prima di andare avanti: tratta qualsiasi cosa Claude ti dica sulla codebase come un'ipotesi, non come un fatto. Incrocia ogni affermazione non banale con il codice effettivo.

I seguenti prompt sono un assaggio delle domande che ho posto a Claude nelle prime settimane di lavoro sul progetto (o almeno quelle di cui non ho paura di condividere su internet).

Per conoscere la codebase:

Dammi una mappa di questa codebase. Quali sono i principali domini/moduli,
cosa possiede ciascuno e come si relazionano tra loro?

Descrivi il modello dati core. Quali sono le entità più importanti,
le loro relazioni e le decisioni di design non ovvie?

Dammi una mappa delle dipendenze di tutti i domini/moduli. Quali dipendono da
quali, eventuali dipendenze circolari e punti in cui i confini sembrano violati.

Suggerimento: chiedi un diagramma, non una descrizione in prosa. La skill fireworks-tech-graph prende una descrizione strutturale come questa e la esporta in SVG e PNG pronti per la pubblicazione. Una dipendenza circolare in un grafo è molto più ovvia della stessa cosa sepolta in un muro di testo.

Una tipica disposizione dei domini Laravel. Output anonimizzato del prompt codebase-map, renderizzato con fireworks-tech-graph

Quando volevo approfondire:

Cosa assume questa codebase sull'ambiente circostante che non è ovvio
dal codice stesso? (valori di config, servizi esterni,
driver di code/queue/cache, assunzioni sul database, ecc.)

Per un dominio specifico:

Osserva il dominio [X]. Per quali problemi è stato chiaramente progettato
per risolvere e come li risolve?

Sembrano ovvi col senno di poi, ma avere un piccolo set di prompt di riferimento mi ha evitato di riscrivere variazioni ogni volta che aprivo un nuovo branch.

Dove Claude ha sbagliato

Claude è stato sicuro di sé ma sbagliato su molte cose durante le mie prime settimane. Non fidarti ciecamente dell'output dell'AI, soprattutto su una codebase di cui nessuno dei due ha contesto.

L'esempio più chiaro: il nostro setup di sviluppo locale funziona tramite Docker, con un Makefile che avvolge la maggior parte dei comandi CLI, come npm, composer o php artisan. Né CLAUDE.md né AGENTS.md lo dicevano. Così quando Claude andava a eseguire qualcosa, di default seguiva il percorso felice di Laravel, php artisan direttamente sull'host, invece dei target make che usiamo realmente. Host sbagliato, PHP sbagliato, un sacco di errori.

## Artisan Commands
.PHONY: artisan
artisan: ## Run artisan command (Usage: make artisan route:list)
    docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) php artisan $(if $(CMD),$(CMD),$(filter-out $@,$(MAKECMDGOALS)))
## Package Management Commands
.PHONY: composer
composer: ## Run composer command (Usage: make composer require package)
    docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) composer $(if $(CMD),$(CMD),$(filter-out $@,$(MAKECMDGOALS)))
## Frontend Commands
.PHONY: npm-dev
npm-dev: ## Start Vite development server
    docker-compose -f $(COMPOSE_FILE) exec $(APP_CONTAINER) npm run dev
# ...

Questa è colpa nostra, non di Claude. La guida di Anthropic su CLAUDE.md è chiara. I comandi di build e run dovrebbero stare lì. Da allora abbiamo aggiunto quel contesto, ma è un promemoria che l'AI tende a default sul percorso felice del framework. Ovunque il tuo progetto diverga (wrapper Docker, Makefile personalizzati, devcontainer, ...), scrivilo prima di fare onboarding a un umano o a un'AI.

È importante quando si usa l'AI per analizzare il codice, che riceva prima di tutto le informazioni corrette. Suddividi l'intero flusso di lavoro in prompt o contesto che Claude (o qualsiasi AI) possa usare in seguito con facilità e mantieni aggiornate quelle informazioni.

I domini come curva di apprendimento

Il progetto segue una struttura a domini. Ogni dominio ha una proprietà chiara, quindi una volta che Claude li ha mappati, puoi leggerne uno alla volta senza perderti.

Una breve parentesi se non hai ancora sentito parlare di sviluppo domain-driven: in un progetto Laravel "standard", i file sono raggruppati per tipo: tutti i modelli in app/Models, tutti i controller in app/Http/Controllers, tutti i job in app/Jobs, e così via. Per seguire il ciclo di vita di, ad esempio, un ordine, finisci per saltare tra quattro o cinque cartelle di primo livello.

Lo sviluppo domain-driven ribalta tutto. I file sono raggruppati per concetto di business. Ogni dominio (Identity, Orders, Billing, qualunque cosa il progetto necessiti) vive nella sua cartella con i suoi modelli, azioni, eventi, policy, ecc. Leggere una cartella da cima a fondo ti dà gran parte della storia senza uscire dalla directory.

// Una cartella di dominio specifica per ogni concetto di business
src/Domain/Invoices/
	├── Actions
	├── Commands
	├── QueryBuilders
	├── Collections
	├── DataTransferObjects
	├── Events
	├── Exceptions
	├── Listeners
	├── Models
	├── Rules
	└── States
src/Domain/Customers/
// …

Il nostro corso Laravel Beyond CRUD copre tutto questo in dettaglio. Il lato positivo? Un dominio è abbastanza piccolo da essere letto in una sola seduta sia da un umano che da un'AI, che è esattamente come l'analisi di Claude raggruppa il codice.

Detto questo, non hai bisogno di una codebase domain-driven per ottenere valore da questo flusso di lavoro. I prompt e gli strumenti sopra funzionano altrettanto bene su un layout Laravel più convenzionale. La suddivisione in domini ha semplicemente reso il mio onboarding ancora più fluido.

Dare a Claude il modello dati

Per la progettazione del database, il nostro team usa Luna Modeler. I file .dmm che produce sono in realtà solo JSON dietro le quinte, il che significa che puoi inserirli direttamente in Claude e chiedergli di analizzare l'architettura. Combinato con la codebase stessa, questo dà al modello un sacco di contesto su cui ragionare.

Una visione sfocata dell'intero modello dati di questo progetto

Ciò che è stato utile non era solo lo schema, ma la storia che lo circonda. Un progetto cliente di lunga durata accumula molti momenti "abbiamo cambiato idea". Le tabelle che erano state modellate in un certo modo all'inizio vengono estese, divise o parzialmente deprecate man mano che il cliente reindirizza lo scope, o quando funzionalità successive introducono vincoli che nessuno aveva previsto.

Claude ha sottolineato dove il file .dmm e le migration raccontavano storie diverse. Osservando quelle stesse aree nel diagramma di Luna era ovvio quali parti dello schema fossero state modificate di più, le tabelle che erano state tirate in direzioni diverse nel tempo.

Questo si è rivelato il contesto di cui avevo bisogno quando ho iniziato a spedire funzionalità mie. Sapere quali tabelle avevano una forma stabile e quali erano state rimodellate tre volte mi ha permesso di fare scelte migliori su dove estendere, dove rifattorizzare e dove lasciare stare fino al prossimo giro di modifiche.

Concludendo

Entrare in un progetto già avviato da sette mesi significava qualche settimana di esplorazione prima di essere davvero produttivo e conoscere bene il progetto. Con gli strumenti giusti, quel lasso di tempo si è ridotto notevolmente. La maggior parte dei miei primi giorni è consistita nel far trasformare a Claude un monolite in qualcosa che potessi effettivamente navigare. Nelle settimane successive ho costruito le mie prime vere funzionalità importanti che si integravano perfettamente nei pattern esistenti.

Senza l'analisi iniziale e la revisione strutturata in uscita, lo stesso lavoro avrebbe richiesto molto più tempo e probabilmente sarebbe stato meno coerente con il resto del progetto.