Ganchos Git do Claude Code para commits mais seguros e revisões mais rápidas

Por que a automação no momento do commit importa

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.

O que o Claude Code acrescenta aos ganchos Git

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:

• Marcar segredos prováveis (chaves de API, tokens, chaves privadas), mesmo quando estão um pouco ofuscados ou divididos em linhas.
• Aplicar formatação com contexto, por exemplo rodando formatadores apenas nos arquivos staged e avisando quando um formatador causaria grande churn não relacionado.
• Sugerir ou exigir testes com base no que mudou (por exemplo, “você alterou lógica de pagamento, rode estes testes unitários”) em vez de “rode tudo”.
• Gerar um curto resumo para o revisor a partir do diff: o que mudou, por que, áreas de risco e o que verificar.

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.

Velocidade e confiabilidade em primeiro lugar

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.

Privacidade e offline vs online

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.

Escolha os hooks certos e mantenha-os rápidos

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.

Bloqueie segredos antes que sejam cometidos

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.

Aplicar formatação sem desacelerar o time

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:

• Rode formatação apenas nos arquivos staged.
• Use auto-fix para mudanças seguras (espaçamento, aspas, ordem de imports).
• Falhe rápido quando for necessária uma decisão humana (como uma regra que pode mudar comportamento).
• Mantenha a saída do formatador silenciosa a menos que ele tenha alterado algo.
• Faça cache quando possível, mas nunca à custa da correção.

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:

• Forçar endings LF no repositório.
• Remover espaços em branco no fim de linhas modificadas.
• Garantir que arquivos terminem com uma nova linha.
• Ignorar formatação para arquivos gerados e diretórios vendor.

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.

Exigir testes para o que você mudou

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 inteiras
• db/ ou migrations/ -> rodar lint de migrations mais uma checagem pequena de esquema
• shared/ -> rodar testes do pacote compartilhado, mais consumidores rápidos

Com 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:

• No commit: rode um conjunto rápido e seletivo (lint + testes unitários dos módulos tocados)
• No push: rode um conjunto mais amplo (integração, smoke e2e, testes cross-module)
• No CI: rode a suíte completa e aplique gates de cobertura

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.

Gerar resumos curtos para revisores no momento do commit

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.

Template simples de resumo

Mantenha a saída enxuta e consistente para que os revisores aprendam a confiar nela:

• O que: uma frase sobre a mudança principal (não uma lista de arquivos)
• Por que: o problema do usuário ou bug corrigido
• Risco: baixo, médio ou alto com uma razão
• Testes: o que você rodou (ou “não rodado”)
• Observações: migrations, flags, passos de rollout ou qualquer coisa crítica para revisão

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.

Não vaze segredos no resumo

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.

Exemplo de fluxo: um commit, menos surpresas

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 mudou: Corrige arredondamento em cálculo de imposto para valores terminando em .005
• Config: staging agora lê a chave de API de variável de ambiente
• Testes: testes unitários de billing passaram
• Risco: afeta totais de cobrança, mas limitado ao caminho de cálculo de imposto

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.

Erros comuns e como evitá-los

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.

1) Hooks muito lentos

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 total
• commit-msg: menos de 1 segundo
• Qualquer coisa mais longa: mova para pre-push ou CI

2) Saída de IA sem regras claras

IA é ó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.

3) Confusão staged vs unstaged

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.

4) Muitos falsos positivos

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.

Checklist rápido e próximos passos

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:

• Mantenha pre-commit abaixo de alguns segundos na maioria das mudanças. Se ficar lento, as pessoas vão pular.
• Escaneie, formate e faça lint apenas dos arquivos staged. O resto pertence a pre-push ou CI.
• Bloqueie segredos óbvios (chaves de API, chaves privadas, tokens). Para casos “talvez”, avise e deixe o desenvolvedor confirmar.
• Exija testes direcionados no commit para módulos tocados, depois execute testes mais amplos no push ou CI.
• Adicione um resumo curto e consistente no commit para que revisores saibam o que mudou e onde focar.

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:

• Prototipe o fluxo num projeto sandbox primeiro, depois copie para o repositório real quando parecer certo.
• Comece em modo “apenas avisar” por uma semana, meça falsos positivos e então mude as checagens mais confiáveis para “bloquear”.
• Adicione rotas de escape para emergências (por exemplo, permitir pular um hook com razão clara na mensagem de commit) e registre quando isso acontecer.
• Mova tudo que for pesado (suítes completas, varreduras profundas de segredos, auditorias de dependência) para pre-push ou CI para manter commits rápidos.

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.