Claude Code e il workflow di sviluppo assistito dall'AI

Sei mesi fa ho iniziato a usare Claude Code come il mio strumento di sviluppo principale. Non come un giocattolo che apro occasionalmente per il boilerplate, ma come l'interfaccia predefinita per scrivere, fare debug e refactoring del codice in ogni progetto su cui lavoro. Il cambiamento non è stato istantaneo — ci sono volute settimane per adattare le abitudini, imparare cosa delegare e cosa mantenere manuale, e costruire workflow che mi rendono effettivamente più veloce piuttosto che più lento.

Questo articolo è un resoconto pratico di come appare quel workflow nella pratica quotidiana, quali pattern producono i migliori risultati e dove lo sviluppo assistito dall'AI ancora non è all'altezza.

Configurare l'ambiente

Claude Code gira nel tuo terminale. Ha accesso diretto al tuo filesystem, può leggere e scrivere file, eseguire comandi shell e interagire con git. Questo è fondamentalmente diverso da un AI basato su chat che opera su frammenti di codice che incolli — Claude Code vede l'intero progetto, comprende la struttura delle directory e può apportare modifiche su più file in un'unica operazione.

La configurazione che rende tutto questo produttivo:

I file CLAUDE.md sono la configurazione più importante che scriverai. Sono file di istruzioni che Claude Code legge automaticamente — uno globale in ~/.claude/CLAUDE.md per gli standard che si applicano a tutti i tuoi progetti, e uno per progetto nella root del repository per le convenzioni specifiche del progetto.

Il mio CLAUDE.md globale stabilisce gli standard di codifica: dimensione massima del file (~300 righe), regole di estrazione dei componenti, requisiti di testing, convenzioni per i commit. Il file a livello di progetto specifica lo stack tecnologico, i pattern architetturali, le convenzioni di naming e qualsiasi regola specifica del dominio. Questo non è opzionale — senza questi file, Claude Code genera codice che funziona ma non corrisponde allo stile o alle convenzioni del tuo progetto.

I server MCP estendono ciò a cui Claude Code può accedere. Io collego un server database (così Claude può interrogare direttamente il mio database di sviluppo), un server di ricerca file e server specifici per progetto per cose come i dati analytics. La configurazione MCP si trova in .mcp.json nella root del progetto. Ogni server è un processo separato con cui Claude Code comunica attraverso il Model Context Protocol.

L'integrazione git è incorporata ma necessita di guardrail. Configuro Claude Code per non fare mai force-push, non fare mai amend dei commit senza che venga richiesto e non saltare mai i pre-commit hook. Queste sono il tipo di azioni distruttive che sono facili da annullare quando le fai tu stesso, ma catastrofiche quando un AI le fa senza che tu te ne accorga.

Integrazione nel workflow quotidiano

Il pattern mattutino

Inizio ogni sessione di codifica aprendo Claude Code nella directory del progetto e dandogli contesto su cosa sto lavorando oggi. Non una specifica dettagliata — una o due frasi sulla funzionalità, il bug o il refactoring che sto affrontando.

"Sto aggiungendo le preferenze di notifica email alla pagina delle impostazioni utente. Gli utenti dovrebbero poter attivare/disattivare le notifiche per: nuovi messaggi, aggiornamenti del progetto e riepiloghi settimanali. Le impostazioni dovrebbero essere persistite nel database e sincronizzate con il nostro servizio email."

Questo stabilisce l'intento. Claude Code ha poi il contesto per prendere decisioni migliori sulla posizione dei file, il naming e l'architettura per ogni richiesta successiva nella sessione.

Pattern di generazione del codice

Le richieste di generazione del codice più efficaci sono specifiche sul cosa e flessibili sul come. Le buone richieste descrivono il comportamento, i vincoli e i punti di integrazione. Le cattive richieste descrivono l'implementazione passo dopo passo — a quel punto, tanto vale scrivere il codice da soli.

Buona richiesta: "Aggiungi un endpoint PATCH al router delle impostazioni utente che accetta un corpo JSON con le preferenze di notifica. Valida che ogni chiave di preferenza sia uno dei tipi consentiti. Persisti nella tabella user_settings. Restituisci le preferenze aggiornate."

Cattiva richiesta: "Crea una funzione chiamata updateNotificationPrefs che prende req e res, destruttura body.preferences, itera su di esse, chiama db.update per ognuna e restituisce un 200."

La prima richiesta dà a Claude Code spazio per applicare le best practice — userà la libreria di validazione che il tuo progetto già utilizza, seguirà i pattern di gestione degli errori stabiliti nelle altre route e corrisponderà al formato di risposta dei tuoi endpoint esistenti. La seconda richiesta produce esattamente ciò che hai descritto, anche se ciò che hai descritto non è ideale.

Operazioni multi-file

Qui è dove Claude Code supera genuinamente la codifica tradizionale. Quando una funzionalità tocca più file — una migrazione del database, un service layer, un route handler, un componente React e i test — Claude Code può creare o modificare tutti in un'unica operazione mantenendo la coerenza tra tutti.

"Aggiungi una colonna notification_preferences JSONB alla tabella users, crea una migrazione per essa, aggiungi un metodo nel service per aggiornare le preferenze con validazione, esponilo attraverso il router API e crea il componente React per la pagina delle impostazioni che chiama l'endpoint."

Claude Code genera tutti questi file, importa i moduli giusti, usa i nomi corretti di tabelle e colonne attraverso la migrazione, il service e il layer API, e crea un componente frontend che corrisponde al contratto API. Farlo manualmente significa passare costantemente da un file all'altro e incrociare i nomi. Averlo fatto in modo atomico è un risparmio di tempo significativo.

Affinamento interattivo

I migliori risultati vengono dalla conversazione iterativa, non dalle richieste a singolo colpo. Genero l'implementazione iniziale, la rivedo e poi affino:

"Il componente delle preferenze di notifica va bene, ma dovrebbe usare aggiornamenti ottimistici — aggiorna la UI immediatamente e annulla se la chiamata API fallisce. Inoltre, aggiungi uno stato di caricamento per il fetch iniziale."

Questo funziona perché Claude Code ha il contesto completo di ciò che ha appena generato. Modifica l'esatto componente, aggiunge il pattern di aggiornamento ottimistico usando l'approccio di state management che il tuo progetto usa, e preserva tutto il resto che ha creato.

Debug con l'AI

Il debug è dove Claude Code fornisce il miglioramento di produttività più drammatico. Il ciclo di debug tradizionale è: leggi l'errore, formula un'ipotesi, aggiungi logging, riproduci, leggi i log, aggiusta l'ipotesi, ripeti. Claude Code comprime tutto questo.

Diagnosi degli errori

Quando incontro un errore, incollo lo stack trace o il messaggio di errore e dico "questo errore si verifica quando provo a salvare le preferenze di notifica dopo aver attivato l'opzione riepilogo settimanale." Claude Code può:

1. Leggere i file sorgente rilevanti per comprendere il percorso del codice
2. Identificare le cause potenziali basandosi sullo stack trace e sul trigger descritto
3. Controllare problemi comuni come type mismatch, null check mancanti o race condition
4. Suggerire una correzione con una spiegazione del perché funziona

Per bug semplici — un await mancante, un nome di proprietà sbagliato, un errore off-by-one — Claude Code identifica e corregge il problema più velocemente di quanto io possa localizzare manualmente la riga rilevante. Per bug complessi che coinvolgono state management, timing asincrono o interazioni tra più sistemi, restringe significativamente lo spazio di ricerca anche quando non produce la correzione esatta.

Analisi dei log

"Ecco le ultime 50 righe del log del server. L'API sta restituendo errori 500 in modo intermittente sull'endpoint /api/settings. Cosa sta andando storto?"

Claude Code legge i log, identifica i pattern (l'errore si verifica sempre quando il corpo della richiesta supera una certa dimensione, o quando due richieste colpiscono la stessa risorsa contemporaneamente) e propone una diagnosi. Può poi applicare la correzione direttamente — regolando un limite del body parser, aggiungendo un mutex o correggendo una race condition.

Debug guidato dai test

Quando incontro un bug che non riesco a riprodurre facilmente nel browser, chiedo a Claude Code di scrivere un test che fallisce catturando lo scenario esatto:

"Scrivi un test che salva le preferenze di notifica con un oggetto vuoto, poi salva di nuovo con preferenze valide. Il secondo salvataggio dovrebbe sovrascrivere il primo, ma penso che stia facendo merge invece."

Il test o passa (smentendo la mia ipotesi) o fallisce (confermando il bug e dandomi un caso riproducibile). In entrambi i casi, ho un test che posso mantenere.

Strategie di refactoring

Il refactoring è un caso d'uso perfetto per l'assistenza AI perché è meccanicamente complesso ma concettualmente semplice. Sai come dovrebbe apparire il codice dopo il refactoring — la sfida è fare tutte le modifiche in modo coerente senza rompere nulla.

Estrazione di componenti

"Questo componente Dashboard è di 450 righe. Estrai il pannello statistiche, il feed delle attività e la sezione azioni rapide in componenti separati. Tienili nella stessa directory. Preserva tutti i props e lo state management."

Claude Code legge il componente, identifica i confini logici, estrae ogni sezione nel proprio file con le interfacce dei props appropriate e aggiorna il Dashboard per comporre i nuovi componenti. Gestisce gli import, le definizioni dei tipi e lo state che deve essere sollevato o passato.

Rinominazione e ristrutturazione

"Rinomina il modulo user in account in tutto il progetto. Questo include il nome della directory, tutti i nomi dei file, tutti i percorsi di import, tutti i riferimenti nella codebase e l'alias della tabella del database nel query layer."

Questo è un lavoro manuale tedioso e soggetto a errori. Claude Code lo fa in un passaggio, cattura riferimenti che avresti mancato e può eseguire la suite di test dopo per verificare che nulla si sia rotto.

Migrazione di pattern

"Stiamo migrando dal vecchio pattern di gestione degli errori (try/catch in ogni route handler) al pattern centralizzato con error middleware. Ecco un esempio del nuovo pattern. Applicalo a tutti i route handler nella directory /api/settings."

Claude Code legge l'esempio, comprende il pattern e lo applica in modo coerente su tutti i file. Gestisce i casi limite — route con più blocchi try/catch, route con logica di cleanup che deve rimanere, route che catturano tipi di errore specifici.

Mantenere il contesto in progetti grandi

La sfida più grande con lo sviluppo assistito dall'AI è il contesto. Claude Code ha una finestra di contesto — un limite su quante informazioni può considerare contemporaneamente. In un progetto piccolo, può leggere tutto. In un grande monorepo, non può.

CLAUDE.md come documentazione architetturale

Il tuo file CLAUDE.md non è solo per gli standard di codifica. Usalo per descrivere l'architettura del tuo progetto ad alto livello:

## Architecture
- API routes are in /src/routes, one file per resource
- Business logic is in /src/services, called by route handlers
- Database access uses Drizzle ORM, schemas in /src/db/schema
- Frontend components are in /src/components, organized by feature
- Shared UI components are in /src/components/ui
- State management uses Zustand, stores in /src/stores

Questo permette a Claude Code di navigare il progetto in modo intelligente anche quando non ha letto ogni file. Sa dove cercare gli schemi del database, dove mettere i nuovi componenti e come si collegano i layer.

Lettura strategica dei file

Non chiedere a Claude Code di "leggere l'intero progetto." Invece, indicagli le parti rilevanti:

"Leggi il service delle impostazioni utente, la route API delle impostazioni e il componente delle preferenze di notifica. Voglio aggiungere il rate limiting all'endpoint di aggiornamento delle preferenze."

Questo dà a Claude Code esattamente il contesto di cui ha bisogno senza sprecare la finestra di contesto su file irrilevanti. Può richiedere file aggiuntivi se ne ha bisogno, ma partire focalizzati è meglio.

Continuità della sessione

Le sessioni di codifica lunghe accumulano contesto naturalmente attraverso la conversazione. Ma quando inizi una nuova sessione, quel contesto sparisce. Gestisco questo:

1. Mantenendo CLAUDE.md aggiornato con le decisioni architetturali recenti
2. Iniziando ogni sessione con una breve dichiarazione di contesto su cosa sto lavorando
3. Usando messaggi di commit git che Claude Code può leggere per comprendere i cambiamenti recenti

Il log git è una fonte di contesto sottovalutata. Quando Claude Code legge gli ultimi 10 messaggi di commit, comprende cosa è cambiato di recente e può evitare conflitti con il lavoro in corso.

Cosa funziona e cosa no

Dove l'assistenza AI eccelle

Boilerplate e operazioni CRUD. Creare un nuovo endpoint API con validazione, gestione degli errori e test è per l'80% meccanico. Claude Code genera questo più velocemente e in modo più coerente di quanto io lo digiti.

Coerenza cross-file. Quando una modifica deve toccare 8 file (definizione del tipo, schema, migrazione, service, route, componente, test, documentazione), Claude Code mantiene la coerenza tra tutti. Io inevitabilmente dimentico di aggiornarne uno.

Generazione di test. Descrivere il comportamento che vuoi testare e lasciare che Claude Code scriva il test è più veloce che scriverlo manualmente, e cattura casi limite a cui non avrei pensato. "Scrivi test per il service delle preferenze di notifica. Copri: input valido, input vuoto, chiavi di preferenza non valide, errori del database e aggiornamenti concorrenti."

Code review e analisi. "Ci sono potenziali race condition in questo file?" o "Cosa succede se questa funzione viene chiamata con un utente null?" Claude Code analizza il codice e identifica problemi che sono facili da perdere durante la revisione manuale.

Imparare nuove API e librerie. Quando devo usare una libreria che non conosco, Claude Code può generare pattern di utilizzo corretti perché ha visto la documentazione e migliaia di esempi di utilizzo. Questo è più veloce che leggere la documentazione per ogni firma di funzione.

Dove l'assistenza AI non è all'altezza

Logica di business complessa. Quando la logica richiede una comprensione profonda del dominio di business — le regole sono sfumate, i casi limite sono specifici del dominio, i requisiti sono ambigui — il codice generato dall'AI spesso sembra ragionevole ma manca sottigliezze critiche. Scrivo sempre la logica di business core da solo e uso Claude Code per l'impalcatura attorno ad essa.

Codice performance-critical. Claude Code genera codice corretto, ma non necessariamente ottimale. Per hot path, loop stretti o operazioni sensibili alla memoria, scrivo l'implementazione da solo e uso Claude Code per generare i benchmark e i test attorno.

Decisioni architetturali. Claude Code può implementare qualsiasi architettura che descrivi, ma non dovrebbe scegliere l'architettura per te. I trade-off tra un microservizio e un monolite, tra SQL e NoSQL, tra rendering lato server e lato client — richiedono la comprensione del tuo team, della tua scala, della tua timeline e dei tuoi utenti. L'AI non ha quel contesto.

Codice security-sensitive. Flussi di autenticazione, crittografia, controllo degli accessi — li scrivo manualmente e li faccio revisionare da un umano. Claude Code può generare codice di autenticazione che funziona, ma "funziona" e "è sicuro" sono standard diversi.

Quando NON usare l'assistenza AI

Ci sono situazioni in cui ricorrere a Claude Code nuoce attivamente alla tua produttività:

Quando hai bisogno di comprendere profondamente il codice. Se stai facendo debug di un problema complesso o imparando come funziona un sistema, lasciare che l'AI scriva la correzione significa che non capisci il problema. A volte devi leggere ogni riga manualmente. La comprensione è il punto, non la correzione.

Quando il task richiede meno di 30 secondi. Rinominare una variabile, correggere un typo, regolare un valore CSS — fallo e basta. L'overhead di descrivere la modifica a Claude Code supera il tempo per farla da solo.

Quando la specifica non è chiara. Se non sai cosa vuoi costruire, Claude Code costruirà qualcosa di confidenzialmente sbagliato. Chiarisci i tuoi requisiti prima, poi delega l'implementazione.

Quando revisionare il codice generato dall'AI richiederebbe più tempo che scriverlo. Per funzioni brevi e critiche, scrivere 15 righe di codice richiede meno tempo che leggere 15 righe di codice generato dall'AI, verificarne la correttezza e potenzialmente correggere problemi. Il punto di pareggio varia per complessità, ma esiste.

Consigli pratici

Dopo mesi di uso quotidiano, questi sono i pattern che producono costantemente i migliori risultati:

Sii esplicito sulle convenzioni. "Usa il pattern di gestione degli errori esistente" è meglio di niente, ma "Usa il wrapper asyncHandler e lancia AppError con i codici di stato appropriati" è meglio. Più sei specifico sul come, meno devi correggere dopo.

Rivedi ogni modifica. Claude Code ti mostra le diff prima di applicarle. Leggi ogni diff. Non scorrendo velocemente — leggendo davvero. Questo è il punto in cui catturi i problemi. Saltare la revisione perché "probabilmente l'AI ha fatto giusto" è come i bug arrivano in produzione.

Usa richieste incrementali. Invece di descrivere un'intera funzionalità in un messaggio, costruiscila gradualmente: prima il layer database, poi il service layer, poi l'API, poi il frontend. Rivedi ogni layer prima di passare al successivo. Questo ti dà checkpoint e mantiene ogni generazione focalizzata.

Mantieni aggiornato il tuo CLAUDE.md. Quando prendi decisioni architetturali, aggiorna CLAUDE.md. Quando adotti un nuovo pattern, documentalo. Quando deprechi un approccio, annotalo. Questo file è la tua leva più potente per influenzare la qualità del codice.

Lascia che legga prima di scrivere. Chiedi esplicitamente a Claude Code di leggere i file rilevanti prima di apportare modifiche. "Leggi le route esistenti delle impostazioni e poi aggiungi una nuova route che segue lo stesso pattern." Questo produce codice che corrisponde al tuo progetto molto meglio della generazione da zero.

Lo sviluppo assistito dall'AI non riguarda il digitare di meno. Riguarda il dedicare il tuo sforzo cognitivo alle decisioni che contano — architettura, logica di business, esperienza utente — e delegare la traduzione meccanica di quelle decisioni in codice. Claude Code è il miglior strumento che ho trovato per quella delega, ma è comunque uno strumento. Il giudizio dello sviluppatore è ciò che rende l'output buono.