I Claude Code git hooks possono bloccare segreti, far rispettare la formattazione, eseguire i test giusti e scrivere brevi sommari di commit per revisioni più rapide.
La maggior parte dei problemi nelle review non viene dal codice “difficile”. Nasce da errori evitabili che sfuggono in un commit: un flag di debug lasciato attivo, un file non formattato che crea diff rumorosi, un test non aggiornato o un segreto copiato in una config. Ognuno è piccolo, ma insieme trasformano una review pulita in un lento botta e risposta.
L'automazione al momento del commit è il posto più semplice per fermarli. Quando i controlli vengono eseguiti subito prima della creazione del commit, catturano i problemi mentre la modifica è ancora fresca nella tua testa. Correggere un errore richiede secondi perché sei già nel contesto del lavoro. Confrontalo con il trovarlo due giorni dopo in una pull request, dopo che si sono accumulati altri commit e il reviewer deve chiedere cosa è successo.
I git hook sono uno strumento pratico per questo perché girano localmente, senza aspettare la CI. Ma non sono magici. Gli hook possono essere saltati, mal configurati o inconsistenti tra macchine se il team non li standardizza. Non possono nemmeno garantire qualità da soli. Pensali come corrimano, non come porte che sbarrano tutto.
Dove gli hook aiutano di più è nel prevenire la “tassa della review”, il feedback ripetitivo e a basso valore che continua a ricomparire. Esempi comuni: stringhe sensibili che sembrano token, rumore da formattazione e lint, controlli basilari tipo “hai eseguito i test giusti?” e piccoli riassunti contestuali che aiutano il reviewer a capire l'intento.
Qui entrano bene i Claude Code git hooks: possono fare il lavoro noioso di verifica e aggiungere un po' di contesto leggibile al momento esatto in cui committi.
Stabilire aspettative è importante. Mantieni gli hook locali veloci e prevedibili così le persone non li odiano. I controlli rapidi stanno sul tuo laptop; i controlli lenti più avanti. Una buona divisione è secondi al momento del commit e minuti in CI. Se un hook impiega regolarmente tanto da spingere qualcuno a “skip”, smette di proteggere il repo.
Un esempio semplice: modifichi un modulo e rifattori alcune funzioni. Senza automazione, un reviewer vede 400 righe spostate, nessun test menzionato e deve porre domande di base. Con i controlli al commit, il commit è formattato, viene eseguito un set di test rilevante e il messaggio di commit include un breve riassunto. La review inizia dove dovrebbe: sul design, non sulla pulizia.
Gli hook sono ottimi per controlli semplici, ma di solito si fermano a regole sì-o-no: “il file è formattato?” o “hai eseguito il linter?”. Claude Code può aggiungere uno strato leggero di giudizio leggendo la diff staged e alcuni file correlati, poi prendendo decisioni che rispecchiano meglio come gli esseri umani rivedono le modifiche.
Con i Claude Code git hooks, l'hook può guardare a ciò che hai effettivamente cambiato, non solo a ciò che esiste nel repo. Questo rende l'automazione più selettiva. Può concentrarsi sui moduli toccati, i file di configurazione modificati e le nuove variabili d'ambiente, invece di trattare ogni commit come una build completa.
Attività pratiche dove “leggere la diff e ragionare” paga:
I vincoli contano perché un hook lento viene saltato. Mantieni l'obiettivo piccolo: aggiungi corrimano che catturino errori comuni presto, non una seconda CI su ogni commit.
Una buona regola è: se non finisce in pochi secondi, probabilmente appartiene alla CI o a un pre-push. Molti team eseguono controlli locali veloci al commit e lasciano suite di test più pesanti per dopo.
Pianifica i casi di fallimento. Se una chiamata al modello va in timeout, decidi se bloccare il commit o ricorrere a un controllo più semplice. Un fallback mantiene il flusso prevedibile ed evita di addestrare le persone a disabilitare gli hook.
Alcune configurazioni chiamano un modello hosted; altre girano in ambienti più isolati. Decidi quale codice può lasciare la macchina dello sviluppatore (se ce n'è), e limita cosa invii. La diff staged più un piccolo insieme di file referenziati è spesso sufficiente.
Se lavori con repository sensibili, sii esplicito su dove avviene l'analisi e cosa viene loggato. Un esempio concreto: se un commit aggiunge un nuovo valore di config come STRIPE_SECRET=..., l'hook può fermare il commit, spiegare cosa sembra rischioso e suggerire di spostarlo in un secret manager o in un file env locale prima che raggiunga il repo remoto.
Gli hook sono utili solo se le persone li mantengono attivi e non imparano a temere i commit. Il trucco è scegliere l'hook giusto per il lavoro giusto e tenere qualsiasi cosa lenta fuori dal percorso critico.
Una mappa semplice di dove solitamente appartengono i controlli:
pre-commit: controlli veloci e locali che bloccano problemi evidenti (formattazione, scansione segreti, lint rapido)commit-msg: controlli che richiedono solo il messaggio (ID ticket, lunghezza, formato convenzionale)pre-push: lavoro più pesante che vale la pena intercettare prima che raggiunga il repo condiviso (test più lenti, type check, build)Quando aggiungi i Claude Code git hooks, trattali come un reviewer utile che arriva istantaneamente, non come un collo di bottiglia. Metti tutto ciò che richiede chiamate di rete, suite di test complete o analisi lunga in pre-push o CI, non in pre-commit.
Un modo pratico per decidere cosa eseguire è ordinare i controlli per velocità e impatto. Se intercetta problemi ad alto rischio (come chiavi esposte) e può girare in uno o due secondi, appartiene a pre-commit. Se impiega 30–90 secondi, spostalo in pre-push o eseguilo solo quando cambiano certi file.
I team devono anche avere una posizione chiara sull'enforcement. Per un repo personale, gli hook opt-in possono andare bene. Per un repo di team è comune far rispettare il minimo (segreti, formattazione, regole sul messaggio) e mantenere i controlli più pesanti come advisory localmente, mentre la CI resta il cancello finale.
L'output degli hook conta più di quanto si pensi. Un hook che fallisce dovrebbe dire cosa è successo e cosa fare dopo. Mantieni i messaggi brevi e specifici. Mostra il file e la riga esatti quando possibile, dai un comando di fix chiaro, spiega come bypassare solo per vere emergenze (e quando non farlo), ed evita log enormi a meno che l'utente non chieda “verbose”.
Esempio: se esporti un progetto da Koder.ai e inizi a committare localmente, un pre-commit veloce può intercettare subito un token API copiato, mentre il pre-push esegue la regola più lenta “solo i test per i moduli cambiati” prima che qualcun altro veda il branch.
Un segreto è qualsiasi cosa permetta a qualcuno di agire come te o accedere a sistemi privati. Pensa a token API, secret OAuth, chiavi cloud, password di database, URL privati con credenziali, chiavi di firma e anche credenziali di test “temporanee”. Un singolo commit accidentale può finire in un fork, in un log CI o in una diff incollata, e allora non è più temporaneo.
La soluzione più semplice è scansionare solo ciò che stai per committare. Un hook dovrebbe controllare le modifiche staged (l'indice), non l'intero repo. Questo lo mantiene veloce ed evita rumore da file vecchi che non hai toccato. Fa anche sentire il feedback giusto: “questo commit include un problema” invece di “il tuo repo una volta aveva un problema”.
Cose comuni da segnalare presto includono token ad alta entropia (stringhe lunghe e casuali), formati di chiave noti (chiavi AWS, token GitHub, JWT), pattern come password=... o api_key: ... nei config, URL privati con credenziali embeddate e file .env o config di produzione copiati.
I falsi positivi capitano, specialmente con dati di test, hash o documentazione d'esempio. Inserisci un allowlist in cui le persone possano muoversi senza disabilitare tutto. Mantieni l'allowlist stretta: percorsi di file esatti per fixture o marker espliciti come “dummy” o “example” che il detector riconosce.
Quando si trova un segreto, fallisci il commit con un messaggio che spiega i passi successivi. I Claude Code git hooks possono rendere questo più amichevole producendo una breve spiegazione basata sulla diff, ma la chiave sono azioni successive chiare e sicure:
ERROR: Possible secret detected in staged file: config/app.yaml (line 12)
Reason: looks like an API token
Next steps:
1) Remove it from the change or move it to env vars
2) Rotate the token (assume it is compromised)
3) Re-stage and retry commit
If this is a false positive, add a narrow allowlist rule in .secrets-allowlist
Un esempio concreto: qualcuno aggiorna una config backend e aggiunge una TEMP_API_KEY perché una feature funzioni in dev. L'hook ferma il commit, suggerisce di spostarla in una variabile d'ambiente e ricorda di ruotare la chiave se era reale. È una piccola interruzione che evita una grande pulizia dopo.
Le dispute di formattazione fanno perdere tempo ai reviewer, ma gli hook lenti sono il modo più rapido per farli disabilitare. Il punto giusto è regole semplici, uno strumento per linguaggio e toccare solo ciò che sta per essere committato.
Scegli un solo formatter per linguaggio e fallo diventare la fonte di verità. Due formatter che non concordano (o un formatter più un linter che riscrive) creeranno diff rumorosi e churn infinito. Mantienilo noioso: un formatter JS/TS, uno Go, uno Dart. Assicurati poi che tutti eseguano le stesse versioni così l'output dell'hook è stabile tra le macchine.
Il più grande guadagno di velocità è formattare solo i file staged. Formattare l'intero repository a ogni commit è la ragione principale per cui i team si lamentano di pre-commit. Un approccio staged-only mantiene anche il diff focalizzato su ciò che hai cambiato, che è esattamente ciò che i reviewer vogliono.
Un set pratico di scelte che mantiene i commit rapidi:
Auto-fix vs fallire è preferenza di team, ma un approccio misto funziona bene. L'auto-fix è ottimo per modifiche meccaniche perché evita il ciclo “commit, fail, re-run, commit di nuovo”. Fallire può essere meglio quando vuoi che le persone vedano il problema e scelgano una direzione. Se fai fallire, stampa un'istruzione che chiunque possa seguire in 10 secondi.
Standardizza le piccole cose che causano rumore cross-platform. Endings di linea e spazi finali sono i soliti colpevoli, specialmente quando si passa tra Windows, macOS e CI.
Una policy semplice che raramente causa problemi:
Dove i Claude Code git hooks possono aiutare è nel collante: rilevare quali file staged richiedono quale formatter, eseguirli nell'ordine corretto e spiegare i fallimenti in linguaggio semplice. Per esempio, se qualcuno stagea un file Go e uno TS, l'hook può formattarli ciascuno con lo strumento corretto, ri-stageare i risultati e poi stampare una breve nota tipo “2 file riformattati, nessun cambiamento di comportamento”. I reviewer vedono diff più puliti e gli sviluppatori non si sentono puniti per commit frequenti.
Una regola semplice rende i commit più sicuri senza renderli dolorosi: esegui solo i test che corrispondono a ciò che hai effettivamente staged. Quando l'hook guarda la diff staged (non il working tree), evita falsi allarmi da file a metà.
Inizia rilevando quali aree sono state toccate. La maggior parte dei repo ha già una struttura naturale: package, servizi, app o moduli. Un hook può leggere git diff --cached --name-only e mappare quei percorsi a un piccolo set di comandi di test.
Ecco alcune regole di mapping che restano comprensibili quando le rivedi dopo:
web/ o frontend/ -> esegui npm test (o il comando mirato più piccolo che hai)api/ o server/ -> esegui i unit test del backend (salta integrazione di default)mobile/ -> esegui test rapidi di widget/unit, non suite su devicedb/ o migrations/ -> esegui lint delle migration più un piccolo controllo di schemashared/ -> esegui i test del pacchetto shared, più eventuali consumer velociCon Claude Code git hooks puoi fare un passo avanti: far leggere a Claude i nomi dei file staged e proporre un set minimo di test, poi l'hook esegue quei comandi. Mantieni però la regola decisionale basata su regole, così il team può prevedere cosa succederà.
Dividi il lavoro tra commit e push. I commit devono restare veloci per evitare che le persone bypassino gli hook. Un pattern pratico è:
I test flaky e lenti necessitano di una policy esplicita, altrimenti l'hook diventa rumore. Accordatevi sul team su cosa blocca un commit vs cosa solo avvisa. Un approccio praticabile:
Se un test è flakey, trattalo come un bug: traccialo, correggilo e rimuovi la modalità warn appena è stabile di nuovo.
Una buona diff non è sempre facile da rivedere. Un breve riassunto al commit può trasformare una lettura di 10 minuti in un check di 2 minuti, specialmente quando le modifiche toccano più file o includono refactor.
L'idea è semplice: quando esegui git commit, il tuo hook chiede a Claude Code di leggere la diff staged e produrre una nota di 3–6 righe che risponde alle domande che i reviewer si fanno sempre: cosa è cambiato, perché, quanto è rischioso e come è stato testato.
Mantieni l'output conciso e coerente così i reviewer imparano a fidarsene:
Puoi mettere questo direttamente nel messaggio di commit (per esempio come footer), o salvarlo in un file che il team copia nella descrizione della pull request. Il messaggio di commit funziona bene quando vuoi che il contesto viaggi con la modifica. Un file separato funziona meglio se il team preferisce soggetti di commit puliti e convenzionali.
Uno strumento di sommario dovrebbe essere più severo di un reviewer. Prima di inviare qualsiasi contenuto della diff al modello, filtra le linee che corrispondono a pattern come API key, chiavi private, token, valori .env e credenziali. Filtra anche header e cookie comuni se il tuo repo include traffico HTTP catturato. Quando l'hook rileva pattern sensibili, può redigere le linee o ricorrere a un sommario generico come “modifiche relative a credenziali oscurate”.
Esempio: aggiorni un endpoint di fatturazione e tocchi tre file. La diff staged è rumorosa a causa di rename, ma il sommario dice: “Aggiunge gestione della idempotenza per la creazione dei charge per evitare fatturazioni duplicate. Motivo: i retry causavano addebiti duplicati. Rischio: medio (percorso di pagamento). Test: unit test per il servizio di fatturazione, replay manuale delle richieste.” Questo è esattamente ciò che serve al reviewer, senza leggere ogni riga prima.
Correggi un piccolo bug e modifichi una config nello stesso commit. Il bug è una modifica di una riga in billing/tax.go. La modifica di config aggiorna config/staging.yaml per puntare a un nuovo endpoint.
Esegui git commit -am "Fix tax rounding". I tuoi Claude Code git hooks partono e fanno una serie rapida di controlli, in ordine prevedibile.
Prima la scansione dei segreti guarda a cosa è cambiato, non all'intero repo. Segnala che la config di staging include qualcosa che sembra una API key.
ERROR: Possible secret detected in config/staging.yaml:12
Pattern: api_key=sk_live_...
Fix: remove the key and use an env var reference (e.g., API_KEY)
Override: set ALLOW_SECRETS=1 (not recommended)
Sostituisci il valore con un riferimento a variabile d'ambiente, poi committi di nuovo.
Poi la formattazione gira solo dove serve. Se il tuo file Go non è formattato, fallisce con un breve suggerimento come “run gofmt on billing/tax.go”. Esegui il formatter e l'hook passa in secondi.
Poi il gate dei test esegue un set mirato. Perché hai toccato billing/, esegue solo i unit test di billing (non la suite completa). Se un test fallisce, l'hook mostra il comando esatto per riprodurre localmente. Correggi il caso di rounding e riesegui gli stessi test.
Infine, l'hook genera un sommario per il reviewer dalla diff. È breve e specifico, tipo:
Quello che il reviewer vede è un commit già pulito: nessun segreto esposto, formattazione coerente e test coerenti con la modifica. Riceve anche un sommario pronto, così può concentrarsi sulla logica invece di cercare l'intento.
Il modo più rapido per far fallire gli hook è renderli dolorosi. Se un hook impiega abbastanza a interrompere il flusso di qualcuno, le persone lo bypasseranno con --no-verify o lo cancelleranno. Tieni qualsiasi cosa pesante fuori da pre-commit ed eseguila in CI o on demand.
Una regola pratica: pre-commit dovrebbe sembrare un controllo ortografico, non una suite di test. Se vuoi controlli più intelligenti dai Claude Code git hooks, usali per decidere cosa eseguire, non per eseguire tutto.
Rendi gli hook veloci per default e severi solo quando serve. Per esempio, esegui formattazione + scansione segreti rapida a ogni commit, ma esegui test solo per i moduli interessati.
Un budget di velocità semplice che funziona:
pre-commit: 1–5 secondi totalicommit-msg: sotto 1 secondopre-push o CIL'AI è ottima per suggerimenti, non per policy. Se chiedi a un'AI di “revisionare la diff” senza regole, ottieni risultati diversi ogni volta. Definisci cosa deve fare l'hook (e cosa non deve mai fare). Per esempio: può generare un sommario per il reviewer, ma non può riscrivere il codice a meno che un formatter non abbia già prodotto cambiamenti deterministici.
Molti hook per errore scansionano il working tree e poi fanno fallire il commit per modifiche che non avevi staged. Questo sembra ingiusto.
Evitalo usando sempre il contenuto staged come input. Un buon test: modifica un file, stage solo metà e verifica che l'hook segnali solo ciò che è staged.
Se ogni commit genera un avviso, gli avvisi diventano rumore. Sintonizza i pattern, aggiungi allowlist per stringhe note sicure e degrada i rilevamenti “forse” a warning con una correzione chiara.
Esempio concreto: se lo scanner dei segreti segnala chiavi di test in fixtures/, aggiungi una regola per ignorare quella cartella, ma continua a bloccare chiavi reali nei file di config dell'app.
Se vuoi che i Claude Code git hooks aiutino senza infastidire il team, l'obiettivo è semplice: intercetta i problemi reali presto, stai silenzioso quando va tutto bene e mantieni il loop di commit rapido.
Una checklist pratica che funziona per la maggior parte dei repo:
pre-commit sotto pochi secondi per la maggior parte delle modifiche. Se rallenta, le persone lo bypasseranno.pre-push o CI.Un piccolo dettaglio che ripaga: fai in modo che il riassunto per il reviewer abbia sempre lo stesso aspetto. Un template semplice è sufficiente e addestra i reviewer a scansionarlo rapidamente.
Review summary:
- What changed: <1-2 bullets>
- Risky areas: <files/modules>
- Tests run: <command or “not run + why”>
Prossimi passi che facilitano l'adozione:
Se ti piace costruire tooling in modo chat-first, Koder.ai (koder.ai) può essere utile per generare i piccoli script helper intorno ai tuoi hook e iterare in sicurezza con snapshot e rollback prima di esportare il codice sorgente nel tuo repo.
Inizia con i problemi ricorrenti che fanno perdere tempo ai reviewer:
Tieni tutto ciò che è lento (suite di test completa, analisi approfondita) su pre-push o in CI.
Un buon default è:
pre-commit per controlli veloci che guardano le modifiche staged (segreti, formattazione, lint veloce, test unitari selettivi)commit-msg per regole sul messaggio di commit (lunghezza, formato, ID ticket)pre-push per controlli più lenti ma ancora locali (test più ampi, build)Se un controllo impiega regolarmente più di pochi secondi, spostalo più avanti.
Tratta gli hook al momento del commit come guardrail, non come unica enforcement.
Politica pratica: gli hook aiutano gli sviluppatori; la CI protegge il ramo principale.
Scansiona la diff staged (l'indice), non l'intero repository.
Se serve una scansione completa del repo, eseguila su schedule o in CI.
Blocca quando la corrispondenza è ad alta confidenza (formati di chiavi reali, blocchi di chiavi private, valori password= evidenti nei config). Avvisa quando è ambiguo.
Aggiungi anche una allowlist molto ristretta per i casi sicuri noti, come:
DUMMY_KEY)Se le persone vedono allarmi continui, disattiveranno l'hook.
Formatta solo i file staged e usa un solo formatter per linguaggio.
Default pratici:
Questo mantiene i diff puliti senza trasformare ogni commit in una lunga riscrittura.
Mappa i percorsi modificati a un piccolo insieme di comandi di test veloci.
Esempio di approccio:
git diff --cached --name-onlypre-push o CIQuesto mantiene i commit veloci ma cattura presto i rotture più comuni.
Mantienilo breve e coerente (3–6 righe). Un template semplice:
Puoi aggiungerlo al messaggio di commit o salvarlo come output di testo da copiare nella descrizione della PR.
Prima di inviare la diff a un modello, redigi/filtra i contenuti sensibili e sii conservativo.
.env, chiavi private, cookie o header di authDefault: “condividi meno”, specialmente su repo privati.
Rendi gli hook prevedibili e veloci:
pre-commit)Se l'hook sembra instabile o lento, gli sviluppatori useranno --no-verify.