Claude Code e il deploy: il rollback resta un comando che scrivi tu

Il deploy manuale ha un rituale fisso. Guardi lo stato del repository, controlli i tipi, lanci i test, fai la build, incroci le dita e pubblichi. Il costo non è nei quindici minuti che ci passi: è che per farlo devi uscire dal lavoro vero, entrare in modalità operativa, e poi impiegare un'altra mezz'ora per rientrare nel flusso.

Ho spostato questo rituale dentro Claude Code su due sistemi diversi: il sito che stai leggendo, e una pipeline di generazione video che gira su Google Cloud Run. Ti racconto il workflow esatto, incluse le due volte in cui si è rotto e nessuna automazione se n'è accorta.

Prima una premessa che serve a inquadrare tutto il resto. Claude Code non ha un rollback automatico. Non esiste un meccanismo nativo che intercetta un problema in produzione e ripristina lo stato precedente. Gli hook, che sono il meccanismo di automazione più profondo che offre, fanno due cose: bloccano un'azione prima che accada, o reagiscono dopo che è accaduta. Nessuna delle due è un ripristino. Se leggi da qualche parte che il tuo agente riporta indietro il deploy da solo, quel pezzo lo devi scrivere tu, e sotto ti mostro come.

Cos'è Claude Code, e cosa cambia rispetto alla chat

Claude Code è un agente che opera nel terminale. Legge il codebase, esegue comandi, modifica file, interroga API. La differenza rispetto a Claude in chat non è la qualità delle risposte: è che qui l'agente ha capacità di azione. Può navigare directory, leggere file, lanciare script e concatenare operazioni in sequenza senza che tu gli riporti l'output a mano.

Sul come installarlo la documentazione è cambiata rispetto a un anno fa. Il metodo raccomandato oggi è l'installer nativo:

curl -fsSL https://claude.ai/install.sh | bash

Il vecchio percorso via npm esiste ancora ed è finito tra le opzioni avanzate. Ci sono anche Homebrew, WinGet e i gestori di pacchetti Linux. Serve un account su un piano Pro, Max, Team, Enterprise o Console: il piano gratuito di claude.ai non lo include. Il quadro completo delle funzionalità l'ho messo in Claude Code: guida completa.

Il primo livello: il file di contesto

Il pezzo che fa più lavoro è anche il più noioso. È un file di testo nella radice del progetto, si chiama CLAUDE.md, e Claude Code lo legge a ogni sessione senza che glielo chieda.

Dentro ci sta quello che una persona nuova dovrebbe sapere prima di toccare il repository: struttura delle cartelle, convenzioni di codice, comandi di build e test, quali variabili d'ambiente servono, cosa non si tocca mai. Nel mio caso ci sono anche le regole che valgono su tutti i progetti, tipo che i percorsi negli script schedulati devono essere assoluti, e che prima di ogni commit va letto lo stato del repository invece di aggiungere tutto in blocco.

Questo file è la differenza tra un agente che ti chiede tre cose a ogni sessione e uno che parte già orientato. Se stai valutando da dove cominciare, comincia da qui: costa mezz'ora una volta sola.

Il secondo livello: il prompt di deploy

Il comando che uso è letteralmente una parola. Quello che c'è dietro è una procedura scritta, che nel mio caso vive come skill invocabile e che in forma discorsiva suona così:

Esegui il deploy. Verifica lo stato git e che il branch sia allineato al remoto. Controlla i tipi. Lancia la suite di test. Fai la build di produzione. Se qualcosa fallisce, fermati, mostrami l'errore e proponi il fix senza applicarlo. Se passa tutto, committa con un messaggio in imperativo presente e pusha.

La riga che conta è la penultima. Il comportamento predefinito su fallimento è fermarsi e mostrare, non correggere e proseguire. Un agente che si auto-corregge in silenzio durante un deploy è un agente che sta scrivendo codice che nessuno ha letto in un ramo che sta per andare in produzione.

Sul sito, la sequenza mappa esattamente sugli script del progetto: la build è una catena che rigenera i tipi dallo schema del CMS e poi compila, i test girano su file dedicati, il controllo dei tipi è un passaggio separato. Il deploy vero e proprio non lo fa Claude Code: lo fa Vercel, che pubblica in automatico a ogni push sul branch collegato. Sopra c'è una pipeline di integrazione continua su GitHub che rigira installazione, test, lint e controllo dei tipi a ogni push e a ogni pull request.

Questa distinzione vale la pena dirla chiaramente, perché è la fonte di metà della confusione sull'argomento: quella pipeline è integrazione continua, non consegna continua. Verifica, non pubblica. Il collegamento tra il push e il sito online è l'integrazione tra GitHub e Vercel, e Claude Code sta a monte di entrambi.

Il terzo livello: gli hook

Gli hook sono il meccanismo con cui leghi un comando a un evento del ciclo di vita dell'agente. La documentazione ufficiale elenca oltre trenta eventi: l'avvio e la chiusura di sessione, il momento prima e dopo l'uso di uno strumento, il fallimento di uno strumento, lo stop, la compattazione del contesto, l'avvio e la fine di un subagente.

Quello che un hook può fare è preciso, e conviene sapere dove finisce. Sul momento prima di uno strumento può negare l'azione: è il punto in cui blocchi un git push --force o un comando che tocca un file che non deve essere toccato. Su tutti gli altri può leggere, registrare, notificare, o passare l'esito a un altro processo.

Quello che un hook non può fare è annullare qualcosa che è già successo. Il modello è prevenzione e reazione. Il ripristino è una cosa che scrivi tu.

Nel mio setup ho un solo hook attivo, e non riguarda il deploy: alla chiusura di sessione lancia uno script che cattura quello che ho imparato e lo mette in coda per la memoria persistente. Il deploy, sia del sito che della pipeline, parte sempre da un comando umano. È una scelta: gli eventi che vale la pena automatizzare sono quelli che accadono cento volte al giorno, e il deploy non è tra questi. Su come usare gli hook per il controllo qualità, che è il caso in cui rendono di più, ho scritto Claude Code Hooks.

Vale la pena sapere che esistono altre due leve, perché sono quelle che confondo più spesso con gli hook quando qualcuno me le descrive. La prima è la modalità senza interfaccia: lanci claude -p con una richiesta, l'agente la esegue e chiude. È il pezzo che ti serve se vuoi mettere Claude Code dentro uno script o un job schedulato, e su come costruire quel tipo di ricorrenza ho scritto in task schedulati con Claude Code. La seconda sono i subagenti: sessioni con contesto separato che fanno un lavoro e riportano un riassunto. Nel deploy li uso per la verifica, perché un contesto pulito nota cose che quello lungo ha smesso di vedere.

Il quarto livello: lo script con i gate

Sulla pipeline che gira su Cloud Run il deploy è più delicato, perché non c'è un'anteprima da guardare prima di pubblicare: o il job funziona, o produce contenuto sbagliato che finisce online. Lì ho scritto uno script con sette fasi in sequenza, ognuna con un criterio di accettazione esplicito.

1. Preflight. Repository pulito e allineato al remoto, controllo dei tipi senza errori, smoke test superato. Se una di queste tre fallisce lo script si ferma prima di toccare qualunque cosa.
2. Regressione. Confronto delle firme crittografiche dei fotogrammi generati contro immagini di riferimento versionate. Serve a intercettare i cambiamenti visivi che nessun test funzionale vede.
3. Registrazione del rollback. Lo script legge il digest dell'immagine attualmente in produzione e scrive su file il comando esatto che la ripristina. Lo scrive, non lo esegue.
4. Guardia sull'ambiente. Verifica che le variabili attese esistano e che nessuna credenziale stia per finire dentro l'immagine.
5. Build. Costruzione dell'immagine sul servizio di build gestito.
6. Aggiornamento e verifica. Aggiorna il job e ricontrolla che il digest in produzione sia davvero quello appena costruito, non quello di prima.
7. Collaudo. Esecuzione a vuoto su un ambiente di prova, con pubblicazione disattivata.

La fase tre è quella su cui torno sempre, perché è la risposta pratica alla premessa di questo articolo. Il rollback automatico non esiste come funzione: esiste come comando che qualcuno ha scritto in anticipo, quando aveva le informazioni per scriverlo bene, e che al momento del bisogno si limita a incollare. Lo script accetta anche un parametro opzionale che lo esegue da solo se il collaudo della fase sette fallisce, ma il comportamento predefinito resta stampare e lasciar decidere.

Se stai deployando automazioni su Cloud Run, i dettagli di costo e configurazione li ho misurati in deploy di automazioni Claude su Cloud Run.

Le due volte in cui si è rotto tutto

Questa è la parte utile, perché nessuno dei due guasti è stato intercettato da niente di automatico.

14 giugno. Un progetto Vercel smette di pubblicare. Nessun errore di build, nessun messaggio: i deploy risultano bloccati e basta, senza codice di errore. Il comando di ripubblicazione risponde che non si può ripubblicare e suggerisce un commit nuovo. La causa: dopo un ciclo di eliminazione e reimportazione del progetto, l'autore dei commit non corrispondeva più a un'identità autorizzata sul team, e la piattaforma rifiutava i deploy da git in silenzio. Il fix è una riga di configurazione git con l'indirizzo email giusto.

Nessun gate lo avrebbe preso. I test passavano, i tipi erano puliti, la build locale funzionava. Il guasto stava in un livello sopra il codice.

20 giugno. La pipeline video smette di pubblicare, questa volta con un errore esplicito sulla firma delle credenziali cloud. Il codice non era cambiato. Era cambiata l'immagine di base: il tag che usavo era mobile, un rebuild aveva portato dentro una versione minore nuova di Node, e quella versione rompeva la firma verso il servizio di credenziali. Il fix è stato bloccare la versione esatta dell'immagine nel Dockerfile.

Anche qui, un rollback automatico non avrebbe risolto: sarebbe tornato a un'immagine che al rebuild successivo si sarebbe rotta di nuovo allo stesso modo. Il guasto era nel fatto che la ricetta non era deterministica.

La lezione che porto da entrambi: le automazioni di deploy prendono gli errori dentro il tuo codice. I guasti veri arrivano quasi sempre da fuori, e per quelli l'unica difesa è la verifica dell'esito reale. Non "il comando ha risposto zero": il servizio è vivo, l'endpoint risponde, il digest in produzione è quello che ho appena costruito.

Lo script che ho cancellato

Il 17 luglio ho archiviato uno script di deploy generico che avevo in giro da mesi. Serviva un progetto ormai morto, e in un'occasione aveva stampato "Deploy completato" senza aver deployato niente: il comando sottostante era fallito e lo script non guardava il codice di uscita.

Quello è stato il momento in cui ho smesso di considerare l'automazione del deploy come una cosa buona di per sé. Uno script che riporta un esito falso è peggio del deploy a mano, perché il deploy a mano almeno ti lascia guardare lo schermo. La regola che mi sono dato da allora: ogni passaggio che dichiara un successo deve avere accanto una verifica indipendente che quel successo sia vero.

Cosa automatizzare davvero, in ordine

Se stai partendo ora, questo è l'ordine di ritorno per fatica investita.

Il file di contesto viene per primo. Costa mezz'ora, la recuperi in tre sessioni.

La procedura di deploy scritta viene seconda. Non serve un tool: serve che i passaggi siano scritti nello stesso ordine in cui vanno fatti, e che il comportamento su fallimento sia esplicito.

I gate di preflight vengono terzi, e solo dove sbagliare costa. Sul sito bastano i test e il controllo dei tipi, perché c'è un'anteprima da guardare. Su un job che pubblica da solo servono le sette fasi.

Gli hook vengono per ultimi, e solo per gli eventi ad alta frequenza. Legare un hook al deploy quando deployi tre volte a settimana è complessità senza ritorno.

Oltre il deploy, gli stessi meccanismi coprono code review, generazione di test, refactoring, migrazioni di dati, documentazione. I cinque flussi su cui ho un ritorno misurabile li ho raccolti nella guida gratuita ai workflow Claude, e i pattern completi con i template di file di contesto pronti stanno in Claude Mastery, dieci moduli a 19 euro.

Se invece hai un deploy che ti fa male ogni volta e vuoi che lo guardiamo insieme sul tuo stack, la call di scoping dura trenta minuti e serve a decidere quale pezzo automatizzare per primo. Nella mia esperienza non è quasi mai quello che ti aspetti.