Claude Code git hooks per commit più sicuri e revisioni più veloci

Perché l'automazione al momento del commit è importante

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.

Cosa aggiunge Claude Code ai git hook

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:

• Segnalare possibili segreti (API key, token, chiavi private), anche quando sono leggermente offuscati o spezzati su più righe.
• Applicare la formattazione con contesto, ad esempio eseguendo i formatter solo sui file staged e avvisando quando un formatter causerebbe un enorme churn non correlato.
• Suggerire o richiedere test in base a cosa è cambiato (per esempio: “hai toccato la logica di pagamento, esegui questi unit test”) invece di “esegui tutto”.
• Generare un breve sommario per il reviewer dalla diff: cosa è cambiato, perché, aree a rischio e cosa verificare.

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.

Velocità e affidabilità prima di tutto

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.

Privacy e offline vs online

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.

Scegli gli hook giusti e mantienili veloci

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.

Blocca i segreti prima che vengano committati

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.

Applicare la formattazione senza rallentare le persone

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:

• Esegui la formattazione solo sui file staged.
• Usa auto-fix per modifiche sicure (spaziatura, virgolette, ordine import).
• Fallisci velocemente quando serve una decisione umana (regola che potrebbe cambiare comportamento).
• Mantieni l'output del formatter silenzioso a meno che non abbia cambiato qualcosa.
• Usa caching quando possibile, ma mai a costo della correttezza.

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:

• Forza LF come terminatore di linea nel repo.
• Rimuovi trailing whitespace sulle righe modificate.
• Assicurati che i file finiscano con una newline.
• Salta la formattazione per file generati e directory vendor.

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.

Richiedere i test per ciò che hai cambiato

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 device
• db/ o migrations/ -> esegui lint delle migration più un piccolo controllo di schema
• shared/ -> esegui i test del pacchetto shared, più eventuali consumer veloci

Con 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 è:

• Al commit: eseguire un set rapido e selettivo (lint + unit test per i moduli toccati)
• Al push: eseguire un set più ampio (integrazione, smoke end-to-end, test cross-module)
• In CI: eseguire la suite completa e imporre gate di coverage

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:

• Blocca su fallimenti chiari (formattazione, unit test normalmente stabili)
• Avvisa su test noti flakey con un breve messaggio
• Sposta suite lente su push/CI

Se un test è flakey, trattalo come un bug: traccialo, correggilo e rimuovi la modalità warn appena è stabile di nuovo.

Generare brevi riassunti per i reviewer al momento del commit

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.

Un template semplice per il sommario

Mantieni l'output conciso e coerente così i reviewer imparano a fidarsene:

• Cosa: una frase sul cambiamento principale (non una lista di file)
• Perché: il problema utente o il bug risolto
• Rischio: basso, medio o alto con una ragione
• Testing: cosa hai eseguito (o “non eseguito”)
• Note: migrazioni, flag, step di rollout o qualsiasi cosa critica per la review

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.

Non far trapelare segreti nel sommario

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.

Flusso di esempio: un commit, meno sorprese

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:

• What changed: Fix rounding in tax calculation for values ending in .005
• Config: staging now reads API key from env var
• Tests: billing unit tests passed
• Risk: affects billing totals, but limited to tax rounding path

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.

Errori comuni e come evitarli

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.

1) Hook troppo lenti

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 totali
• commit-msg: sotto 1 secondo
• Qualsiasi cosa più lunga: spostala in pre-push o CI

2) Output AI senza regole chiare

L'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.

3) Confusione staged vs unstaged

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.

4) Troppi falsi positivi

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.

Checklist rapida e prossimi passi

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:

• Mantieni pre-commit sotto pochi secondi per la maggior parte delle modifiche. Se rallenta, le persone lo bypasseranno.
• Scansiona, formatta e lint solo i file staged. Tutto il resto appartiene a pre-push o CI.
• Blocca segreti evidenti (API key, chiavi private, token). Per i casi “forse”, avvisa e lascia che lo sviluppatore confermi.
• Richiedi test mirati al commit per i moduli toccati, poi esegui test più ampi su push o CI.
• Aggiungi un breve riassunto di commit coerente così i reviewer sanno cosa è cambiato e su cosa concentrarsi.

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:

• Prototipa il flusso in un progetto sandbox prima, poi copialo nel repo reale quando ti sembra giusto.
• Parti in modalità “warn only” per una settimana, misura i falsi positivi e poi passa i controlli più affidabili a “block”.
• Aggiungi vie d'uscita per emergenze (es., permettere di saltare un hook con una ragione nel messaggio di commit) e registra quando succede.
• Sposta tutto ciò che è pesante (suite di test complete, scansione profonda dei segreti, audit di dipendenze) in pre-push o CI così i commit restano veloci.

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.