--- title: "Claude Code Hooks: automatizzare i tuoi quality gate" description: "Impara cosa sono i Claude Code Hooks, ogni evento del ciclo di vita e come configurarli in settings.json per far girare automaticamente lint, test e formattazione." type: "guide" locale: "it" category: "Claude Code" canonical: "https://agenticschool.dev/it/guide/claude-code-hooks" datePublished: "2026-06-13" dateModified: "2026-06-13" --- # Claude Code Hooks: automatizzare i tuoi quality gate - Category: Claude Code - Keywords: claude code hooks, claude code hooks tutorial, pretooluse posttooluse, automate claude code, claude code quality gates - Canonical URL: https://agenticschool.dev/it/guide/claude-code-hooks - Locale: it > Impara cosa sono i Claude Code Hooks, ogni evento del ciclo di vita e come configurarli in settings.json per far girare automaticamente lint, test e formattazione. I Claude Code Hooks sono comandi shell che Claude Code esegue automaticamente in punti precisi del suo ciclo di vita, cosi imponi i tuoi quality gate in modo deterministico piuttosto che sperare che l'agente se ne ricordi. Dove una regola CLAUDE.md e un suggerimento che il modello puo seguire o meno, un hook si attiva sempre: puo far girare il tuo formatter dopo ogni scrittura di file, eseguire i tuoi test prima che l'agente si fermi, o bloccare direttamente un comando pericoloso. Questa guida spiega gli eventi degli hook, come si configurano gli hook, e un setup pratico che puoi adottare oggi stesso. ## Cos'e davvero un hook Ogni hook ha tre parti: un evento (il momento del ciclo di vita in cui si attiva), un matcher opzionale (un filtro perche giri solo per certi tool) e un'azione (il comando shell che esegue). Quando un hook si attiva, Claude Code gli passa JSON via standard input che descrive l'evento (ID di sessione, directory di lavoro, il nome del tool e il suo input), e il tuo script decide cosa fare. Il codice di uscita del comando pilota il flusso: exit 0 significa continuare, e un exit diverso da zero (per convenzione 2) blocca l'azione e restituisce il tuo messaggio all'agente perche reagisca. - Evento: quando l'hook si attiva (per esempio dopo che un tool e girato). - Matcher: un filtro opzionale, per esempio solo sulle modifiche di file. - Azione: il comando shell che Claude Code esegue. ## Gli eventi del ciclo di vita che puoi agganciare Gli hook coprono tutto il ciclo di vita dei tool. Quelli che usi di piu sono PreToolUse e PostToolUse (attorno a ogni chiamata di tool), Stop (quando l'agente vuole terminare) e SessionStart (quando una sessione comincia). Per un controllo piu fine, ce ne sono altri. - PreToolUse: prima che un tool giri, per validare o bloccare l'azione. - PostToolUse: dopo che un tool e girato, per formattare, lintare o verificare il risultato. - UserPromptSubmit: quando invii un prompt, per iniettare contesto o mettere in sicurezza l'input. - Stop e SubagentStop: quando l'agente (o un subagent) vuole fermarsi, per lanciare i test come ultimo gate. - SessionStart e Notification: setup di sessione e quando l'agente ha bisogno della tua attenzione. ## Dove gli hook si configurano Gli hook vivono nel tuo settings.json Claude Code. Metti i gate non negoziabili a livello di squadra nel file di progetto sotto .claude/settings.json, cosi tutti condividono gli stessi guard rail, e tieni le preferenze personali nei tuoi user settings. Ogni voce associa un evento a un matcher e al comando da eseguire. ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bun run lint --fix" } ] } ] } } ``` Un hook PostToolUse che fa girare il tuo linter dopo ogni modifica o scrittura di file. ## Un setup pratico di quality gate Il setup piu potente e piccolo: formattare e lintare a ogni scrittura, e far girare la tua suite di test come gate Stop, cosi l'agente non puo dichiarare un compito finito con test rossi. Aggiungi un guard PreToolUse se vuoi bloccare i comandi shell distruttivi. Tieni gli script degli hook veloci e idempotenti, perche girano spesso, e in caso di blocco, scrivi un messaggio chiaro sull'errore standard perche l'agente sappia come correggerlo. ## Steps ### 1. Creare il tuo file di settings Crea .claude/settings.json alla radice del tuo progetto se non esiste. Qui vivono gli hook condivisi a livello di squadra. ### 2. Aggiungere un hook PostToolUse per formattare e lintare Sotto hooks.PostToolUse, aggiungi un matcher "Edit|Write" e un comando che esegue il tuo formatter e il tuo linter, cosi il codice viene ripulito dopo ogni cambiamento dell'agente. ### 3. Aggiungere un hook Stop che esegue i tuoi test Sotto hooks.Stop, aggiungi un comando che esegue la tua suite di test. Exit diverso da zero in caso di fallimento, cosi l'agente non puo terminare con test che falliscono e continua invece a correggerli. ### 4. Aggiungere un guard PreToolUse per i comandi rischiosi Sotto hooks.PreToolUse con un matcher Bash, aggiungi uno script che controlla il comando dal JSON stdin e blocca con exit 2 le operazioni distruttive come il force-push o la cancellazione ricorsiva. ### 5. Testare e fare commit Fai una piccola modifica e conferma che gli hook si attivano come previsto, poi fai commit del file di settings perche tutta la squadra erediti gli stessi guard rail. ## FAQ ### Cosa sono i Claude Code Hooks? Gli hook sono comandi shell che Claude Code esegue automaticamente in punti del suo ciclo di vita, come prima o dopo una chiamata di tool o quando l'agente vuole fermarsi. Ti lasciano imporre i quality gate in modo deterministico, come eseguire test o un formatter, piuttosto che contare sulla memoria del modello. ### Dove configuro i Claude Code Hooks? Nel tuo settings.json Claude Code. Metti gli hook condivisi a livello di squadra nel file di progetto sotto .claude/settings.json e tieni quelli personali nei tuoi user settings. Ogni hook associa un evento a un matcher opzionale e al comando da eseguire. ### Un hook puo bloccare un'azione? Si. Un hook PreToolUse che termina con un codice di uscita diverso da zero (per convenzione 2) blocca la chiamata di tool, e il messaggio che emetti viene restituito all'agente perche si adatti. E cosi che fermi i comandi distruttivi prima che girino. ### Qual e la differenza tra un hook e una regola CLAUDE.md? Una regola CLAUDE.md e una raccomandazione che il modello puo seguire o meno. Un hook e deterministico: esegue sempre il comando configurato sull'evento scelto, quindi e lo strumento giusto per i gate non negoziabili come test, formattazione e verifiche di sicurezza.