Os ganchos Git do Claude Code podem impedir vazamento de segredos, aplicar formatação, executar os testes certos e escrever resumos curtos de commit para revisões mais rápidas.
A maior parte da dor em revisões não vem do código “difícil”. Vem de erros evitáveis que escapam em um commit: uma flag de debug deixada ativa, um arquivo sem formatação que gera diffs ruidosos, um teste não atualizado ou um segredo copiado numa configuração. Cada um é pequeno, mas juntos transformam uma revisão limpa em um vai-e-volta demorado.
A automação no momento do commit é o lugar mais fácil para barrar isso. Quando as checagens rodam pouco antes do commit ser criado, elas capturam problemas enquanto a mudança ainda está fresca na sua cabeça. Corrigir um erro leva segundos porque você já está no contexto do trabalho. Compare com descobrir isso dois dias depois em um pull request, depois de mais commits acumulados, quando o revisor precisa perguntar o que aconteceu.
Ganchos Git são uma ferramenta prática porque rodam localmente, sem esperar o CI. Mas não são mágicos. Hooks podem ser pulados, mal configurados ou inconsistentes entre máquinas se a equipe não os padronizar. Eles também não garantem qualidade sozinhos. Pense neles como guarda-corpos, não como portões.
Onde hooks ajudam mais é em prevenir o “imposto de revisão”, o feedback repetitivo e de baixo valor que continua reaparecendo. Exemplos comuns incluem strings sensíveis que parecem tokens, ruído de formatação e lint, checagens básicas do tipo “você rodou os testes certos?” e pequenos resumos de contexto que ajudam o revisor a entender a intenção.
É aqui que os ganchos Git do Claude Code se encaixam bem: eles podem fazer o trabalho tedioso de verificação e adicionar um pouco de contexto legível no exato momento do commit.
Definir expectativas importa. Mantenha hooks locais rápidos e previsíveis para que as pessoas não os odeiem. Verificações rápidas pertencem ao seu laptop; verificações lentas pertencem mais adiante. Uma boa separação é segundos ao cometer e minutos no CI. Se um hook costuma demorar o suficiente para alguém usar “skip”, ele deixa de proteger seu repositório.
Um exemplo simples: você altera um módulo e refatora algumas funções. Sem automação, um revisor vê 400 linhas movidas, nenhum teste mencionado e precisa fazer perguntas básicas. Com checagens no momento do commit, o commit está formatado, um conjunto relevante de testes foi executado e a mensagem inclui um resumo curto. A revisão começa onde deve: no design, não na limpeza.
Ganchos Git são ótimos para checagens simples, mas normalmente param em regras de sim/não: “o arquivo está formatado?” ou “você rodou o linter?”. O Claude Code pode adicionar uma camada leve de julgamento lendo seu diff staged e alguns arquivos relacionados, então tomando decisões que combinam melhor com como humanos revisam mudanças.
Com os ganchos Git do Claude Code, o hook pode olhar o que você realmente mudou, não apenas o que existe no repositório. Isso torna a automação mais seletiva. Ele pode focar em módulos tocados, arquivos de configuração editados e novas variáveis de ambiente, em vez de tratar todo commit como uma build completa.
Tarefas práticas onde “ler o diff e pensar” compensa:
As restrições importam porque um hook lento vira um hook pulado. Mantenha o objetivo pequeno: adicionar guardrails que peguem erros comuns cedo, não um segundo sistema CI em cada commit.
Uma boa regra é: se não termina em poucos segundos, provavelmente pertence ao CI ou a um pre-push. Muitas equipes rodam checagens locais rápidas no commit e deixam suítes mais pesadas para depois.
Planeje modos de falha. Se uma chamada ao modelo exceder o tempo, decida bloquear o commit ou falhar para uma checagem mais simples. Um fallback mantém o fluxo previsível e evita treinar pessoas a desabilitar hooks.
Algumas configurações chamam um modelo hospedado; outras rodam em ambiente mais isolado. Decida quais partes do código podem sair da máquina do desenvolvedor (se houver), e limite o que você envia. O diff staged mais um pequeno conjunto de arquivos referenciados costuma ser suficiente.
Se você trabalha com repositórios sensíveis, seja explícito sobre onde a análise roda e o que é logado. Exemplo concreto: se um commit adiciona um novo valor de configuração como STRIPE_SECRET=..., o hook pode bloquear o commit, explicar o que parece arriscado e sugerir mover para um gerenciador de segredos ou um arquivo env local antes que chegue ao repositório remoto.
Ganchos Git só são úteis se as pessoas os manterem ativados e não passarem a temer commits. O truque é escolher o hook certo para cada tarefa e manter qualquer coisa lenta fora do caminho crítico.
Um mapa simples de onde as checagens geralmente pertencem:
pre-commit: checagens locais rápidas que bloqueiam problemas óbvios (formatação, varredura de segredos, lint rápido)commit-msg: checagens que precisam apenas da mensagem (ID de ticket, comprimento, formato convencional)pre-push: trabalho mais pesado que ainda vale a pena antes de ir ao repositório compartilhado (testes mais lentos, checagens de tipos, build)Ao adicionar os ganchos Git do Claude Code, trate-os como um revisor útil que aparece instantaneamente, não um gargalo. Coloque qualquer coisa que precise de chamadas de rede, suíte completa de testes ou análise longa em pre-push ou CI, não em pre-commit.
Uma maneira prática de decidir o que roda onde é ordenar as checagens por velocidade e impacto. Se pega questões de alto risco (como chaves vazadas) e roda em um ou dois segundos, pertence ao pre-commit. Se leva 30 a 90 segundos, mova para pre-push ou rode apenas quando certos arquivos mudarem.
Equipes também precisam de uma posição clara sobre enforcement. Para um repositório solo, hooks opt-in podem bastar. Para um repositório de equipe, é comum aplicar o básico (segredos, formatação, regras de mensagem) e manter checagens mais pesadas como consultivas localmente, enquanto o CI continua sendo o portão final.
A saída do hook importa mais do que se pensa. Um hook que falha deve dizer o que aconteceu e o que fazer a seguir. Mantenha mensagens curtas e específicas. Mostre o arquivo e a linha exata quando possível, dê um comando claro de correção, explique como pular apenas para emergências reais (e quando não fazê-lo), e evite logs gigantes a menos que o usuário peça “verbose”.
Exemplo: se você exporta um projeto do Koder.ai e começa a commitar localmente, um pre-commit rápido pode detectar um token de API copiado imediatamente, enquanto o pre-push roda a regra mais lenta de “rodar apenas testes para módulos mudados” antes de qualquer outra pessoa ver a branch.
Um segredo é qualquer coisa que permite a alguém agir como você ou acessar sistemas privados. Pense em tokens de API, segredos de clientes OAuth, chaves de nuvem, senhas de banco de dados, URLs privadas com credenciais, chaves de assinatura e até credenciais de teste “temporárias”. Um commit acidental pode acabar num fork, em um log de CI ou num diff colado — aí já não é mais temporário.
A vitória mais fácil é escanear apenas o que você está prestes a commitar. Um hook deve checar mudanças staged (o index), não o repositório inteiro. Isso o torna rápido e evita ruído de arquivos antigos que você não tocou. Também faz o feedback parecer justo: “este commit inclui um problema” em vez de “seu repositório já teve um problema”.
Coisas comuns a marcar cedo incluem tokens de alta entropia (strings longas e aleatórias), formatos de chaves conhecidos (chaves AWS, tokens GitHub, JWTs), padrões como password=... ou api_key: ... em config, URLs privadas com credenciais embutidas e arquivos .env ou configs de produção copiados.
Falsos positivos acontecem, especialmente com dados de teste, hashes ou docs de exemplo. Inclua uma allowlist para que as pessoas possam seguir em frente sem desabilitar toda a verificação. Mantenha a allowlist estreita: paths exatos para fixtures ou marcadores explícitos como “dummy” ou “example” que o detector reconheça.
Quando um segredo é encontrado, falhe o commit com uma mensagem que diga o próximo passo. Os ganchos Git do Claude Code podem tornar isso mais amigável produzindo uma explicação curta baseada no diff, mas o essencial é ações seguras e claras:
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
Exemplo concreto: alguém atualiza uma config backend e adiciona um TEMP_API_KEY para que uma feature funcione em dev. O hook impede o commit, sugere mover para uma variável de ambiente e lembra de rotacionar a chave se ela for real. É uma pequena interrupção que evita uma grande limpeza depois.
Discussões sobre formatação fazem os revisores perderem tempo, mas hooks lentos são um caminho rápido para desabilitá-los. O ponto ideal é regras simples, uma ferramenta por linguagem e tocar apenas o que vai ser commitado.
Escolha um formatador por linguagem e torne-o a fonte da verdade. Dois formatadores que discordam (ou um formatador mais um linter que reescreve código) geram diffs ruidosos e churn infinito. Mantenha sem surpresas: um formatador para JS/TS, um para Go, um para Dart. Depois garanta que todos usem as mesmas versões para que a saída do hook seja estável entre máquinas.
O maior ganho de velocidade é formatar apenas arquivos staged. Formatar o repositório inteiro em cada commit é a principal razão de reclamação. A abordagem staged-only também mantém o diff focado no que você mudou, que é justamente o que os revisores querem.
Conjunto prático de escolhas que mantém commits rápidos:
Auto-fix vs falhar é preferência da equipe, mas uma abordagem mista funciona bem. Auto-fix é ótima para edições mecânicas porque evita o loop “commit, falha, re-executar, commitar de novo”. Falhar pode ser melhor quando você quer que a pessoa veja o problema e escolha a direção. Se falhar, imprima um comando que qualquer um possa seguir em 10 segundos.
Padronize as pequenas coisas que causam ruído entre plataformas. Final de linha e espaços finais são os ofensores habituais, especialmente quando pessoas alternam entre Windows, macOS e CI.
Política simples que raramente causa problemas:
Onde os ganchos Git do Claude Code ajudam é na cola: detectar quais staged files precisam de qual formatador, rodá-los na ordem correta e explicar falhas em linguagem simples. Por exemplo, se alguém stageia um arquivo Go e um TS, o hook pode formatar cada um com a ferramenta correta, re-stagear os resultados e depois mostrar uma nota curta como “2 arquivos reformatados, sem mudanças de comportamento”. Revisores veem diffs mais limpos e desenvolvedores não se sentem punidos por commitar com frequência.
Uma regra simples torna commits mais seguros sem torná-los dolorosos: rode apenas os testes que correspondem ao que você staged. Quando o hook olha o diff staged (não sua working tree), evita alarmes falsos por arquivos meio-prontos.
Comece detectando quais áreas foram tocadas. A maioria dos repositórios já tem uma estrutura natural: packages, services, apps ou módulos. Um hook pode ler git diff --cached --name-only e mapear esses caminhos para um pequeno conjunto de comandos de teste.
Algumas regras de mapeamento que permanecem compreensíveis ao voltar depois:
web/ ou frontend/ -> rodar npm test (ou o menor comando direcionado que você tiver)api/ ou server/ -> rodar testes unitários do backend (pular integração por padrão)mobile/ -> rodar testes rápidos de unidade/widget, não suites de dispositivo inteirasdb/ ou migrations/ -> rodar lint de migrations mais uma checagem pequena de esquemashared/ -> rodar testes do pacote compartilhado, mais consumidores rápidosCom os ganchos Git do Claude Code, você pode ir um passo além: pedir ao Claude que olhe os nomes de arquivo staged e proponha um conjunto mínimo de testes, e então o hook roda esses comandos. Mantenha, porém, a regra final baseada em regras previsíveis, para que a equipe saiba o que esperar.
Separe a carga entre commit e push. Commits devem continuar rápidos para que as pessoas não burlem hooks. Padrão prático:
Testes flaky e lentos precisam de uma política explícita, ou seu hook vira ruído. Concorde em equipe sobre o que bloqueia um commit vs o que apenas avisa. Abordagem viável: bloquear em falhas claras (formatação, testes unitários normalmente estáveis), avisar sobre testes conhecidos por serem flaky com uma mensagem curta e mover suítes lentas para push/CI. Se um teste é flaky, trate como bug: registre, corrija e remova o modo de aviso assim que estiver estável.
Um bom diff nem sempre é fácil de revisar. Um resumo curto no momento do commit pode transformar uma leitura de 10 minutos em uma checagem de 2 minutos, especialmente quando mudanças tocam vários arquivos ou incluem refatores.
A ideia é simples: ao rodar git commit, seu hook pede ao Claude Code que leia o diff staged e gere uma nota de 3 a 6 linhas que responda às perguntas que revisores sempre têm: o que mudou, por que mudou, quão arriscado é e como foi testado.
Mantenha a saída enxuta e consistente para que os revisores aprendam a confiar nela:
Você pode colocar isso diretamente na mensagem de commit (por exemplo, como um footer curto) ou salvar em um arquivo que a equipe copie na descrição do pull request. Mensagem de commit funciona bem quando você quer que o contexto viaje com a mudança. Arquivo separado funciona melhor se a equipe prefere subjects limpos e convencionais.
Uma ferramenta de resumo deve ser mais rígida que um revisor. Antes de enviar qualquer conteúdo do diff ao modelo, filtre linhas que batam em padrões como chaves de API, chaves privadas, tokens, valores de .env e credenciais. Também filtre headers e cookies comuns se o repositório contiver tráfego HTTP capturado. Quando o hook detecta padrões sensíveis, ele pode redigir as linhas ou cair para um resumo genérico como “alterações relacionadas a credenciais redigidas”.
Exemplo: você atualiza um endpoint de cobrança e toca três arquivos. O diff staged está barulhento por renames, mas o resumo diz: “Adiciona manejo de chave de idempotência para criação de cobrança para evitar cobranças duplicadas. Motivo: retries causavam duplicatas. Risco: médio (caminho de pagamento). Testes: unit tests do serviço de cobrança, replay manual de requisições.” Isso é exatamente o que um revisor precisa, sem ler cada linha primeiro.
Você corrige um bug pequeno e ajusta uma config no mesmo commit. O bug é uma mudança de uma linha em billing/tax.go. A config atualiza config/staging.yaml para apontar para um novo endpoint.
Você roda git commit -am "Fix tax rounding". Seus ganchos Git do Claude Code entram e fazem um conjunto rápido de checagens, numa ordem previsível.
Primeiro, a varredura de segredos olha o que mudou, não o repositório inteiro. Ela marca que a config de staging inclui algo que parece uma chave de API.
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)
Você substitui o valor por uma referência a variável de ambiente e commita de novo.
Em seguida, a formatação roda apenas onde importa. Se seu arquivo Go não estiver formatado, ele falha com uma dica curta como “run gofmt on billing/tax.go”. Você executa o formatador e o hook passa em segundos.
Depois, o gate de testes roda um conjunto direcionado. Como você tocou billing/, ele roda apenas os testes unitários de billing (não a suíte completa). Se um teste falhar, o hook mostra o comando exato para reproduzir localmente. Você corrige o caso de arredondamento e re-roda os mesmos testes.
Por fim, o hook gera um resumo para o revisor a partir do diff. É curto e específico, por exemplo:
O que o revisor vê é um commit já limpo: sem segredos vazados, formatação consistente e testes que batem com a mudança. Há também um resumo pronto, para que ele possa focar na lógica em vez de procurar a intenção.
A forma mais rápida de fazer hooks falharem é torná-los dolorosos. Se um hook demora o suficiente para quebrar o fluxo de alguém, as pessoas vão pular com --no-verify ou deletá-lo. Mantenha coisas pesadas fora do pre-commit e rode-as no CI ou sob demanda.
Regra prática: pre-commit deve parecer uma checagem de digitação, não uma suíte de testes. Se você quer checagens mais inteligentes do Claude Code, use-as para decidir o que rodar, não para rodar tudo.
Torne hooks rápidos por padrão e estritos apenas quando necessário. Por exemplo, rode formatação rápida + varredura de segredos em cada commit, mas testes apenas para módulos afetados.
Orçamento simples de velocidade que funciona bem:
pre-commit: 1 a 5 segundos no totalcommit-msg: menos de 1 segundopre-push ou CIIA é ótima para sugestões, não para política. Se você pede a IA para “revisar o diff” sem regras, recebe resultados diferentes a cada vez. Defina o que o hook deve fazer (e o que nunca deve fazer). Ex.: pode gerar um resumo para o revisor, mas não pode reescrever código a menos que um formatador já tenha produzido mudanças determinísticas.
Muitos hooks acidentalmente escaneiam sua working tree e depois falham o commit por mudanças que você não staged. Isso parece injusto.
Evite sempre usando o conteúdo staged como input. Um bom teste: edite um arquivo, stageie só metade e verifique se o hook reporta apenas o que está staged.
Se todo commit dispara um aviso, avisos viram ruído. Ajuste padrões, adicione allowlists para strings seguras conhecidas e rebaixe achados “talvez” para aviso com solução clara.
Exemplo concreto: se seu scanner de segredos marca chaves de teste em fixtures/, adicione uma regra para ignorar essa pasta, mas continue bloqueando chaves reais em arquivos de configuração do app.
Se você quer que os ganchos Git do Claude Code ajudem sem irritar sua equipe, o objetivo é simples: pegar problemas reais cedo, permanecer silencioso quando tudo está normal e manter o loop de commit rápido.
Checklist prático que funciona para a maioria dos repositórios:
Um detalhe pequeno que compensa: faça o resumo do revisor ter sempre o mesmo formato. Um template simples é suficiente e treina revisores a escanear rapidamente.
Review summary:
- What changed: <1-2 bullets>
- Risky areas: <files/modules>
- Tests run: <command or “not run + why”>
Próximos passos que facilitam a adoção:
Se você gosta de construir tooling de forma orientada a chat, Koder.ai (koder.ai) pode ser útil para gerar pequenos scripts auxiliares em torno dos seus hooks e iterar com snapshots e rollback antes de exportar o código-fonte para o repositório.
Comece com os repetidos que mais desperdiçam tempo do revisor:
Deixe qualquer coisa lenta (suíte completa de testes, análise estática profunda) para pre-push ou CI.
Um bom padrão é:
pre-commit para verificações rápidas que olham as mudanças staged (segredos, formatação, lint rápido, testes unitários seletivos)commit-msg para regras de mensagem de commit (comprimento, formato, ID de ticket)pre-push para verificações mais lentas, mas ainda locais (testes mais amplos, builds)Se uma verificação normalmente leva mais do que alguns segundos, mova-a para mais tarde.
Trate hooks em tempo de commit como guardrails, não como a única defesa.
Política prática: hooks ajudam desenvolvedores; o CI protege a branch principal.
Varra apenas o diff staged (o index), não o repositório todo.
Se você precisar de uma varredura no repositório inteiro, rode-a por agendamento ou no CI.
Bloqueie quando o match for de alta confiança (formatos reais de chaves, blocos de chaves privadas, password= óbvios em configs). Avise quando for ambíguo.
Também adicione uma allowlist estreita para casos conhecidos e seguros, por exemplo:
DUMMY_KEY)Se as pessoas virem alarmes constantes, elas desabilitarão o hook.
Formate apenas os arquivos staged e use um único formatador por linguagem.
Padrões práticos:
Isso mantém os diffs limpos sem transformar cada commit numa reescrita longa.
Mapeie paths tocados para um pequeno conjunto de comandos de teste rápidos.
Abordagem de exemplo:
git diff --cached --name-onlypre-push ou CIAssim os commits seguem rápidos enquanto os problemas mais comuns são detectados cedo.
Mantenha curto e consistente (3–6 linhas). Um template simples:
Você pode anexar isso à mensagem de commit ou salvar como texto para a descrição do PR.
Redija antes de enviar qualquer conteúdo para um modelo e seja conservador.
.env, chaves privadas, cookies ou headers de autenticaçãoCompartilhe o mínimo, especialmente em repositórios privados.
Torne os hooks previsíveis e rápidos:
pre-commit)Se o hook parecer instável ou lento, desenvolvedores usarão --no-verify.