Come programmo con l'IA: il mio flusso reale con Claude Code

Programmo con l'IA tutti i giorni. Non come aiuto occasionale: come parte del flusso.

Qui c'è come lo faccio davvero, con quello che funziona e quello che mi è andato male.

La prima cosa: scrivere il contesto una volta sola

L'errore più caro che ho fatto all'inizio è stato rispiegare il progetto in ogni conversazione.

Adesso ogni mio repository ha un file CLAUDE.md nella radice. È un documento che il modello legge all'inizio e che contiene quello che servirebbe a uno sviluppatore nuovo il primo giorno:

• I comandi. Come si avvia, come si compila, come si verifica.
• L'architettura. Cosa c'è in ogni cartella e perché.
• Le decisioni che non si toccano. Nel mio sito, per esempio, c'è una regola: si naviga sempre con il Link che rispetta la lingua, mai con un link normale. Questo ha risolto un errore di SEO che avevo già fatto una volta.
• Le trappole. Cose che sembrano giuste e rompono la build.

Il file del mio sito personale occupa due pagine circa. Scriverlo bene costa mezz'ora. Si ripaga alla seconda sessione.

Non conta che sia lungo. Conta che contenga quello che non si deduce leggendo il codice.

Come assegno il lavoro

Un incarico fatto male dà codice che compila e non serve. Un incarico fatto bene è metà del lavoro.

Io lo divido in tre parti.

Cosa voglio ottenere, in termini di risultato, non di passi. «Voglio che la scheda di progetto mostri la galleria su mobile senza caricare le immagini grandi» è meglio di «aggiungi un componente galleria».

Dove vive quella cosa, in file precisi. Se gli dico dove guardare, non si inventa una struttura parallela.

Cosa non può rompere. Qui ci guadagno di più. «Non cambiare il markup dell'h1», «non aggiungere dipendenze nuove», «questo deve continuare a generarsi in modo statico nelle quattro lingue».

Quella terza parte non la scrive quasi nessuno. È quella che evita l'80% dei disastri.

Cosa gli do e cosa no

Dopo più di un anno passato a farlo ho una divisione abbastanza netta.

Gli do tutto:

• Tradurre un componente in un'altra lingua o adattare i testi a quattro locali.
• Modifiche ripetitive su molti file. Rinominare, migrare un'API, applicare un pattern nuovo in venti punti.
• Scrivere la prima versione di qualcosa che ho già fatto: un form, una tabella con filtri, un endpoint CRUD.
• Leggere codice altrui e spiegarmelo. Qui mi fa risparmiare più tempo e il rischio è minimo.
• Test e controlli che io scriverei controvoglia.

Non gli do:

• Decidere l'architettura dei dati. Come si isolano in Savia i dati di un'azienda da quelli di un'altra l'ho deciso io, su carta, prima di scrivere una riga.
• Niente che tocchi sicurezza o permessi senza che io lo riveda riga per riga.
• La parte del design dove serve criterio. Un modello ti dà un'interfaccia corretta. La differenza tra corretta e buona la metti ancora tu.

La regola che uso è questa: se non saprei rivedere il risultato, non lo delego. L'IA non sostituisce il capire quello che stai facendo. Moltiplica quello che già capisci.

La build è il giudice

Questa parte la considero la più importante di tutto l'articolo.

Il mio sito non ha test. Ha una cosa che in pratica funziona altrettanto bene: il comando di compilazione genera in modo statico tutte le pagine nelle quattro lingue. Se manca una traduzione, se un JSON è chiuso male, se una rotta non esiste, la build fallisce.

Quindi l'istruzione permanente è: non dirmi che è fatto finché la build non passa.

Questo cambia il lavoro del tutto. Senza un controllo automatico, rivedere il codice generato ti costa più che averlo scritto. Con il controllo, tu guardi il risultato e la macchina si occupa della parte meccanica.

Scrivere è diventato più economico. Verificare no. E adesso c'è molto più da verificare.

Per questo, quando inizio un progetto nuovo, la prima cosa che monto è il modo di verificarlo. Prima della prima funzionalità.

Andare per pezzi

Un incarico grande dà risultati scadenti. Divido sempre.

Un esempio vero, la sezione blog di questo stesso sito:

1. Leggere i file di contenuto e tirare fuori i metadati. Verificare che escano gli otto articoli.
2. La pagina di elenco, senza design curato. Verificare che si veda.
3. La pagina dell'articolo con il markdown renderizzato.
4. Metadati, canonical e hreflang. Verificare nell'HTML generato.
5. Sitemap e dati strutturati.
6. Design.

Ogni passo si rivede prima del successivo. Se il passo 3 è venuto storto, lo sistemo lì. Non dopo aver montato sei strati sopra.

Quando una cosa si storce parecchio, preferisco ricominciare la conversazione da zero con il contesto corretto invece di discutere. Insistere su una conversazione lunga che ha già preso la strada sbagliata quasi mai costa poco.

Cosa mi è andato male

Nel caso serva come avviso.

Accettare codice che non capivo. Compilava, faceva quello che avevo chiesto, e due settimane dopo non sapevo perché fosse scritto così. Ora, se non riesco a spiegare perché funziona, lo riscrivo finché ci riesco.

Lasciargli riorganizzare le cartelle da solo. Una modifica che avevo chiesto in un componente è finita per toccare otto file. Tutto corretto. Nessuno di quegli otto era quello che volevo toccare io. Da allora delimito il perimetro per iscritto.

Fidarmi delle dipendenze suggerite. Un pacchetto che risolve il problema può essere senza manutenzione da tre anni. Quello lo guardo io, sempre.

Cosa è cambiato davvero

Non è che scriva più codice. È che arrivo a finire cose che prima lasciavo a metà.

Il lavoro noioso costa più del tempo che occupa: è quello che ti fa lasciare i progetti incompiuti. Quando quella parte smette di fare male, finisci di più.

L'altra cosa cambiata è cosa mi distingue. Scrivere il codice non è più la merce rara. Sapere cosa va costruito, per chi e perché, sì.

Prima di sostituire professioni, l'IA sta sostituendo compiti. Vale la pena sapere quali sono i tuoi.