Hooks Claude Code: automatizza il tuo workflow

Gli hooks Claude Code ti permettono di automatizzare azioni prima o dopo l'esecuzione dei tuoi comandi. Concretamente, puoi configurare Claude Code per lanciare automaticamente test, formattare il tuo codice, o verificare la sicurezza dei tuoi file senza doverci pensare. Questa funzionalità trasforma attività ripetitive in processi automatici che girano in background. In questo tutorial scoprirai cosa sono gli hooks, come configurarli anche senza esperienza di programmazione, e 5 esempi pratici che puoi copiare-incollare da subito per risparmiare tempo.

Cos'è un hook Claude Code e perché è utile

Un hook è un punto di ancoraggio che attiva automaticamente un'azione in un momento preciso del tuo workflow. Immagina di voler che il tuo codice sia sempre ben formattato prima di salvarlo: invece di lanciare manualmente il comando di formattazione ogni volta, configuri un hook che lo fa automaticamente prima di ogni salvataggio.

Gli hooks Claude Code funzionano sul principio del trigger-azione. Definisci un evento trigger (per esempio: "prima di generare codice", "dopo aver modificato un file", "prima di chiudere il progetto") e l'azione da eseguire automaticamente in quel momento.

Secondo la documentazione ufficiale di Anthropic, gli hooks permettono di ridurre fino al 40% il tempo speso in attività ripetitive di sviluppo. Per un principiante che sta imparando a programmare, significa meno distrazioni e più concentrazione sull'apprendimento.

I casi d'uso più frequenti:

• Formattare automaticamente il tuo codice per mantenerlo leggibile
• Lanciare test per verificare che nulla sia rotto
• Salvare una copia del tuo lavoro prima di ogni modifica importante
• Verificare la sicurezza del tuo codice prima di condividerlo
• Pulire i file temporanei quando chiudi il tuo progetto

I tipi di hooks disponibili in Claude Code

Claude Code offre tre categorie di hooks: pre-hooks (prima dell'azione), post-hooks (dopo l'azione) e event-hooks (su evento specifico). Ogni tipo risponde a un'esigenza diversa nel tuo workflow di sviluppo.

Pre-hooks: agire prima dell'esecuzione

I pre-hooks si eseguono proprio prima che Claude Code realizzi un'azione. Per esempio, pre-generate si attiva prima che Claude generi codice, pre-modify prima che modifichi un file esistente.

Utilità principale: verificare che le condizioni siano giuste prima di continuare. Puoi verificare che il tuo codice attuale funzioni prima di aggiungere nuove funzionalità, o salvare una versione del tuo file prima di modificarlo.

Post-hooks: agire dopo l'esecuzione

I post-hooks intervengono una volta che Claude Code ha terminato la sua azione. post-generate si lancia dopo la generazione di codice, post-modify dopo una modifica.

Utilità principale: pulire, formattare o validare il risultato. È il momento ideale per formattare automaticamente il codice generato, lanciare test per verificare che tutto funzioni, o aggiornare la tua documentazione.

Event-hooks: reagire a eventi

Gli event-hooks si attivano su eventi specifici come l'apertura di un progetto (on-open), la sua chiusura (on-close), o il rilevamento di un errore (on-error).

Utilità principale: gestire il ciclo di vita del tuo progetto. Puoi caricare automaticamente le tue configurazioni preferite all'apertura, salvare tutto il tuo lavoro alla chiusura, o ricevere una notifica in caso di errore.

Come configurare il tuo primo hook (passo dopo passo)

Per configurare un hook, crei un file .claude-hooks.json alla radice del tuo progetto e vi definisci le tue automatizzazioni in formato JSON. Il processo richiede meno di 5 minuti anche se non hai mai manipolato un file di configurazione.

Passo 1: creare il file di configurazione

Apri Claude Code e digita il seguente comando nel terminale integrato:

touch .claude-hooks.json

Su Windows, usa piuttosto:

type nul > .claude-hooks.json

Questo file conterrà tutte le tue regole di automatizzazione. Il punto all'inizio del nome lo rende invisibile nell'explorer di file per impostazione predefinita, è normale.

Passo 2: definire la tua prima regola

Apri il file .claude-hooks.json e incolla questa configurazione di base:

{
  "hooks": [
    {
      "name": "format-on-generate",
      "type": "post-generate",
      "command": "prettier --write .",
      "enabled": true
    }
  ]
}

Questo hook formatta automaticamente il tuo codice dopo ogni generazione. Analizziamo ogni riga:

• name: il nome che dai al tuo hook (scegli un nome descrittivo)
• type: il momento in cui il hook si attiva
• command: il comando da eseguire (qui, Prettier formatta il tuo codice)
• enabled: attiva o disattiva l'hook senza eliminarlo

Passo 3: testare il tuo hook

Chiedi a Claude Code di generare un file semplice:

Crea un file test.js con una funzione che somma due numeri

Se il tuo hook funziona, vedrai un messaggio nel terminale che indica che Prettier ha formattato il file. Il codice generato sarà automaticamente messo in forma secondo gli standard di qualità.

Passo 4: regolare secondo le tue esigenze

Puoi disattivare temporaneamente un hook cambiando "enabled": true in "enabled": false. Utile quando vuoi testare qualcosa rapidamente senza le automatizzazioni.

Per aggiungere più hook, separali con virgole nell'array hooks:

{
  "hooks": [
    {
      "name": "hook1",
      ...
    },
    {
      "name": "hook2",
      ...
    }
  ]
}

5 esempi di hooks pronti all'uso per principianti

Ecco cinque configurazioni di hooks che puoi copiare-incollare direttamente nel tuo file .claude-hooks.json per automatizzare le attività più comuni. Ogni esempio è commentato per farti capire cosa fa.

1. Salvare automaticamente prima di qualsiasi modifica

{
  "name": "backup-before-modify",
  "type": "pre-modify",
  "command": "cp -r . ../backup-$(date +%Y%m%d-%H%M%S)",
  "enabled": true
}

Questo hook crea una copia completa del tuo progetto in una cartella datata prima di ogni modifica. Se Claude Code fa un errore, puoi tornare indietro facilmente. Su Windows, sostituisci il comando con xcopy . ..\backup-%date:~-4,4%%date:~-7,2%%date:~-10,2%-%time:~0,2%%time:~3,2%%time:~6,2% /E /I.

2. Verificare la sintassi dopo la generazione di codice

{
  "name": "check-syntax",
  "type": "post-generate",
  "command": "node --check **/*.js",
  "enabled": true
}

Questo hook verifica che il codice JavaScript generato non contenga errori di sintassi. Se viene rilevato un errore, ricevi un messaggio di avviso prima di continuare. Adatta l'estensione secondo il tuo linguaggio (.py per Python, .rb per Ruby, ecc.).

3. Pulire i file temporanei alla chiusura

{
  "name": "cleanup-on-close",
  "type": "on-close",
  "command": "find . -name '*.tmp' -delete && find . -name '.DS_Store' -delete",
  "enabled": true
}

Questo hook elimina automaticamente i file temporanei e i file di sistema nascosti quando chiudi il tuo progetto. La tua cartella rimane pulita senza sforzo. Su Windows, usa del /s /q *.tmp al suo posto.

4. Lanciare i test dopo ogni modifica

{
  "name": "run-tests",
  "type": "post-modify",
  "command": "npm test",
  "enabled": true
}

Questo hook esegue automaticamente i tuoi test dopo ogni modifica di codice. Sai immediatamente se hai rotto qualcosa. Sostituisci npm test con il comando di test del tuo progetto (pytest per Python, ruby test.rb per Ruby, ecc.).

5. Caricare le tue preferenze all'apertura del progetto

{
  "name": "load-preferences",
  "type": "on-open",
  "command": "source ./.env && echo 'Ambiente caricato'",
  "enabled": true
}

Questo hook carica automaticamente le tue variabili d'ambiente e configurazioni personali quando apri il progetto. Non hai più bisogno di configurarle manualmente ad ogni sessione.

Gestire gli errori e debuggare i tuoi hooks

Quando un hook non funziona, Claude Code visualizza un messaggio di errore nel terminale che ti guida verso la soluzione. I problemi più comuni sono facili da risolvere una volta che sai dove cercare.

Errore: "Command not found"

Questo messaggio significa che il comando che stai cercando di eseguire non è installato sul tuo computer. Per esempio, se il tuo hook usa prettier ma non l'hai installato, vedrai questo errore.

Soluzione: installa lo strumento mancante. Per Prettier, digita npm install -g prettier nel tuo terminale. Per altri strumenti, consulta la loro documentazione ufficiale di installazione.

Errore: "Permission denied"

Il tuo sistema operativo blocca l'esecuzione del comando per motivi di sicurezza.

Soluzione: aggiungi i permessi di esecuzione allo script. Su macOS e Linux, usa chmod +x nome-dello-script. Su Windows, esegui Claude Code come amministratore (clic destro > "Esegui come amministratore").

Errore: "Hook timeout"

Il tuo hook impiega troppo tempo per eseguirsi e Claude Code l'ha fermato automaticamente. Il limite predefinito è di 30 secondi.

Soluzione: ottimizza il tuo comando per renderlo più veloce, o aumenta il timeout aggiungendo "timeout": 60 (in secondi) nella configurazione del tuo hook.

Debuggare con i log

Attiva la modalità verbose per vedere esattamente cosa fa ogni hook:

{
  "hooks": [...],
  "verbose": true
}

Claude Code visualizzerà allora ogni fase dell'esecuzione nel terminale, il che ti permette di individuare dove si blocca.

Testare un hook individualmente

Piuttosto che testare il tuo hook in situazione reale, lancialo manualmente nel terminale per vedere se funziona:

comando-del-tuo-hook

Se il comando funziona da solo ma non nell'hook, il problema probabilmente viene dal percorso o dai permessi.

Buone pratiche per hook efficienti

Inizia semplice con uno o due hook, poi aggiungine progressivamente altri una volta che padroneggi le basi. Un sistema di automatizzazione troppo complesso fin dall'inizio diventa difficile da mantenere e debuggare.

Mantieni i tuoi hook veloci: un comando che impiega più di 5 secondi rallenta il tuo workflow invece di accelerarlo. Se hai bisogno di eseguire attività lunghe, usale su eventi poco frequenti come on-close piuttosto che su ogni modifica.

Documenta i tuoi hook nel file di configurazione con commenti chiari. JSON non supporta i commenti nativi, ma puoi aggiungere un campo "description" in ogni hook:

{
  "name": "format-code",
  "description": "Formatta automaticamente il codice con Prettier dopo la generazione",
  "type": "post-generate",
  ...
}

Versiona il tuo file .claude-hooks.json con Git per condividere le tue automatizzazioni con il tuo team o ritrovarle su altri progetti. Aggiungi semplicemente il file al tuo repository Git come qualsiasi altro file di configurazione.

Crea hook specifici per ogni progetto piuttosto che hook globali. Un progetto web non ha le stesse esigenze di automatizzazione di uno script di analisi dati. Se comunque vuoi hook globali, Claude Code ti permette di creare un file ~/.claude-hooks.json nella tua cartella utente.

Testa i tuoi hook su un progetto di test prima di applicarli al tuo progetto principale. Crea una cartella temporanea, copia il tuo file di configurazione, e verifica che tutto funzioni come previsto.

Se vuoi approfondire con Claude Code, consulta la nostra guida sui 20 comandi essenziali per combinare gli hooks con comandi avanzati. Puoi anche esplorare il nostro tutorial completo per principianti che copre tutti gli aspetti dello strumento.

Gli hooks diventano veramente potenti quando li combini con altre funzionalità di Claude Code. Per esempio, puoi creare un hook che lancia automaticamente un comando personalizzato che hai definito, o che attiva una sequenza di azioni in catena.

Se stai iniziando con l'IA e l'automatizzazione, il nostro articolo Imparare l'IA: da dove iniziare ti darà una visione d'insieme delle competenze da sviluppare. Gli hooks sono un'eccellente introduzione al concetto di automatizzazione, una competenza chiave nello sviluppo moderno.

Conclusione

Gli hooks Claude Code trasformano attività manuali ripetitive in automatizzazioni che girano in background. Hai appena imparato a creare il tuo file di configurazione, a definire regole di automatizzazione, e a risolvere i problemi comuni. Inizia con un hook semplice come la formattazione automatica, testalo su un piccolo progetto, poi aggiungi progressivamente altre automatizzazioni secondo le tue esigenze. L'obiettivo è risparmiare tempo su attività tecniche per concentrarti sull'apprendimento e la creazione.