Hook e script: automatizzare il tuo workflow

Panoramica

Gli hook eseguono script automaticamente in momenti definiti, perche la cosa giusta accada, che qualcuno se ne ricordi o no. Claude Code ha i suoi lifecycle hook che scattano attorno alle azioni dell'agente, e Git ha degli hook che scattano attorno ai commit e ai push. L'uso classico piu prezioso e un quality gate che lancia il tuo linter, il tuo typechecker e i tuoi test prima che il codice possa lasciare la tua macchina, cosicche una regressione non puo fisicamente raggiungere il tuo repo o la produzione. Questa lezione cabla entrambi con una configurazione reale ed eseguibile.

Cosa imparerai

Imparerai cos'e un hook, i lifecycle event in cui Claude Code ti lascia agganciarti, come configurare un hook in settings.json, in cosa cio differisce da un git pre-push hook e come assemblare un quality gate che protegge automaticamente il tuo progetto. Riparti con uno snippet settings.json funzionante e un git hook funzionante, che puoi adattare.

Prerequisiti

Un progetto sotto version control dal Corso 1 e almeno un controllo eseguibile da riga di comando, come uno script di lint o di test. Il CLAUDE.md della lezione uno aiuta anche, perche il tuo file di regole dovrebbe gia nominare il comando di quality gate che i tuoi hook imporranno. Il dettaglio di cosa deve andare nel gate e il Corso 5.

Il problema

Sai che dovresti lanciare i test prima di pubblicare. La maggior parte delle volte, lo fai. Ma e venerdi, la modifica e piccola, sei sicuro che vada tutto bene, e lo salti. E il push che rompe la produzione. Affidarsi alla disciplina umana per controlli di routine fallisce prima o poi, per tutti, perche l'attenzione e finita e il controllo noioso e la prima cosa da saltare quando sei stanco o di corsa. La soluzione non e piu disciplina. E togliere l'umano dal ciclo, perche il controllo giri automaticamente ogni volta, senza che intervenga alcuna decisione.

Cos'e un hook

Un hook e un comando che gira automaticamente quando un event preciso scatta. Decidi tu l'event e il comando, e se il comando termina in errore, l'azione puo essere bloccata. Claude Code fornisce lifecycle hook attorno al lavoro dell'agente: prima che uno strumento giri (PreToolUse), dopo che uno strumento ha girato (PostToolUse), quando l'agente ha finito di rispondere (Stop) e altri. Puoi usare PostToolUse per formattare automaticamente un file nel momento in cui l'agente lo modifica, o PreToolUse per bloccare un comando pericoloso. Questi hook sono deterministici - e l'harness che esegue il tuo script, non il modello che decide di farlo.

• PreToolUse: gira prima di una chiamata di strumento. Usalo per validare o bloccare un'azione prima che accada.
• PostToolUse: gira dopo una chiamata di strumento. Usalo per formattare o lintare automaticamente un file subito dopo una modifica.
• Stop: gira quando l'agente ha finito di rispondere. Usalo per lanciare un controllo finale o notificarti.
• Gli hook sono un comportamento deterministico dell'harness, quindi scattano in modo affidabile - contrariamente a chiedere gentilmente al modello di ricordarsi.

Cablare un hook in settings.json

Gli hook di Claude Code si configurano in settings.json, nel tuo progetto sotto .claude/settings.json o nella tua configurazione utente. Ogni hook corrisponde a un event e a un pattern di strumento ed esegue un comando shell. Ecco un vero hook PostToolUse che formatta e linta ogni file TypeScript appena l'agente lo modifica o lo scrive, perche la codebase non resti mai in uno stato disordinato tra i turni.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bun run prettier --write \"$CLAUDE_FILE_PATHS\" && bun run eslint --fix \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

Il matcher prende di mira gli strumenti Edit e Write, e il comando gira contro i file che l'agente ha appena toccato. Ormai, la formattazione non e mai qualcosa a cui tu o l'agente dovete pensare, perche l'harness se ne occupa dopo ogni modifica. Consulta la documentazione ufficiale sugli hook per le variabili d'ambiente esatte e la sintassi dei matcher, perche vengono affinate col tempo.

Il quality gate pre-push

L'automazione di gran lunga piu preziosa e un gate che lancia la tua suite completa di controlli prima che il codice possa lasciare la tua macchina. Il posto piu robusto per questo e un git pre-push hook, perche protegge il repo qualunque sia l'agente o l'umano che pubblica. Un git hook e semplicemente uno script eseguibile nella cartella .git/hooks, o meglio, gestito da uno strumento come Husky per essere committato e condiviso. Se un controllo fallisce, lo script termina con un codice non nullo e il push e rifiutato. Il codice rotto non puo raggiungere il tuo repo, punto.

#!/usr/bin/env bash
# .husky/pre-push - blocca il push se un controllo fallisce

set -e  # fermarsi al primo comando che fallisce

echo "Running quality gate before push..."
bun run lint
bun run typecheck
bun run test

echo "All checks passed. Pushing."

Con set -e, il primo controllo fallito interrompe lo script e il push non ha mai luogo. Questo solo gate impedisce il modo piu frequente in cui i team pubblicano regressioni: qualcuno salta i test su una "piccola" modifica. Ti costa un minuto a ogni push e ti risparmia il pomeriggio che un deployment rotto sarebbe costato.

Agent hook contro git hook

Questi due sistemi si completano, e sapere quale usi conta. Gli hook di Claude Code scattano attorno alle azioni dell'agente e sono ottimi per tenere ogni modifica pulita - formattare alla scrittura, bloccare un comando vietato, notificarti quando un lungo compito termina. I git hook scattano attorno agli event di version control e sono il posto giusto per il quality gate duro, perche custodiscono il repo, non importa chi o cosa inneschi il push. Lo schema che usano la maggior parte dei builder seri: agent hook per il riordino lungo la strada, git hook per il gate finale che niente supera. Due valgono meglio di uno.

Errori frequenti

I comuni: mettere il tuo unico quality gate in un agent hook, cosicche un push manuale dal terminale gli passa dritto accanto; scrivere un hook cosi lento che ogni push diventa una fatica e cominci ad aggirarlo; dimenticare set -e, cosicche un controllo fallito viene ignorato e il push continua comunque; e non committare i tuoi git hook (usa Husky), cosicche proteggono solo la tua macchina e non i tuoi compagni di squadra. Un gate funziona solo se e veloce, condiviso e davvero bloccante.

ROI business

L'automazione batte la disciplina ogni volta, e il calcolo e brutalmente a suo favore. Un gate pre-push che dura un minuto impedisce il deployment rotto che costa un pomeriggio di pompieri piu la perdita di fiducia di un bug visibile ai clienti. Codificare il controllo come un hook significa che gira per tutti, ogni volta, con zero attenzione continua. Per un fondatore, cio trasforma "spero che tutti pensino a testare" in "il codice rotto non puo pubblicarsi" - una garanzia invece di un desiderio. Una buona automazione fa della cosa giusta l'impostazione predefinita, e l'impostazione predefinita e cio che accade davvero il venerdi alle 18.

Checklist

Sei pronto ad andare avanti quando ognuno di questi punti e vero. Il gate che costruisci qui e la spina dorsale del lavoro qualita del Corso 5.

• Sai nominare tre lifecycle event di Claude Code e a cosa serve ciascuno.
• Hai un hook PostToolUse che formatta o linta dopo le modifiche.
• Hai un git pre-push hook che lancia lint, typecheck e test e blocca in caso di fallimento.
• I tuoi git hook sono committati e condivisi, non solo sulla tua macchina.

Risorse

Tieni nei preferiti la documentazione ufficiale degli hook di Claude Code per i nomi di event, matcher e variabili d'ambiente aggiornati. Husky e lo strumento standard per git hook committati e condivisi - la sua documentazione ti guida nel setup in qualche comando. La lezione di test del Corso 5 tratta esattamente di cosa metti nel gate, perche colga veri bug senza essere lento.

La tua missione

Aggiungi un git pre-push hook in un vero progetto, che lancia i tuoi comandi lint, typecheck e test e blocca il push se uno fallisce. Rompi deliberatamente un test, tenta di pubblicare e guarda il rifiuto. Poi aggiungi un hook PostToolUse di Claude Code che formatta i file dopo le modifiche. Ora hai un'automazione che impone i tuoi standard, invece della tua memoria.

Prossima lezione

Il tuo agente ormai segue regole, pilota workflow impacchettati e impone gate automaticamente. La prossima lezione lo connette al mondo oltre i tuoi file: MCP, il Model Context Protocol, che da al tuo agente accesso a database, strumenti di design, servizi e fonti di dati tramite un connettore standard.