Git hooks agentes IA · 2026-07-11

Git hooks com agentes de IA — Automatize validações antes do commit

Aprenda a configurar Git hooks com agentes de IA para automatizar validações de código. Guia prático de pre-commit e pre-push com Claude Code e Codex no Windows.

Usar Git hooks agentes IA é a forma mais direta de garantir que código de baixa qualidade nunca entre no seu repositório. Em vez de confiar na disciplina manual de rodar linters, testes e verificações antes de cada commit, você delega essa responsabilidade para agentes como Claude Code e Codex, que executam as validações automaticamente no momento certo do fluxo Git. Este tutorial mostra como configurar pre-commit e pre-push hooks que usam agentes de IA para lint, testes, formatação e revisão de código — tudo no Windows, sem depender de serviços externos.

Sumário

O problema: código quebrado chega ao repositório
O que são Git hooks (e por que usar agentes neles)
Pre-commit hook com Claude Code — lint e formatação inteligentes
Pre-push hook com Codex — revisão antes do envio
Exemplo completo: hook que usa dois agentes em série
Cuidados ao usar agentes em Git hooks
FAQ
Automatize seus hooks hoje

O problema: código quebrado chega ao repositório

Todo desenvolvedor já passou por isso: um commit que quebra a build, um arquivo mal formatado que polui o diff, um teste esquecido que só aparece no CI. A raiz do problema não é falta de cuidado — é a distância entre o momento em que o código é escrito e o momento em que ele é verificado.

Você pode até configurar ESLint, Prettier e Jest para rodar manualmente antes de cada commit. Mas na correria do dia a dia, é tentador pular essas etapas. "Só mais um commit rápido" vira "preciso reverter o último push" meia hora depois.

É aí que entram os Git hooks agentes IA. Em vez de scripts shell com verificações estáticas limitadas, você coloca agentes de IA dentro dos hooks. Eles analisam o código com contexto completo do projeto, sugerem correções inteligentes e bloqueiam o commit se algo estiver errado — tudo sem depender da sua memória ou disciplina.

O que são Git hooks (e por que usar agentes neles)

Git hooks são scripts que o Git executa automaticamente em pontos específicos do fluxo de trabalho. Eles ficam na pasta .git/hooks/ de cada repositório e podem disparar antes ou depois de operações como commit, push, merge e rebase.

Os hooks mais úteis para validação são:

pre-commit: executado antes do commit ser criado. Ideal para lint, formatação, verificação de segurança e testes rápidos.
pre-push: executado antes do envio ao remoto. Ideal para testes de integração, análise de diff completa e verificação de breaking changes.
commit-msg: executado depois do commit message ser digitado. Ideal para validar o formato da mensagem (Conventional Commits, por exemplo).
pre-receive / update: executado no lado do servidor (GitHub, GitLab). Ideal para políticas de qualidade do time inteiro.

Tradicionalmente, esses hooks são scripts shell que chamam ferramentas como eslint, prettier --check e npm test. O problema é que essas ferramentas são limitadas: elas seguem regras fixas e não entendem o *contexto* do que você está tentando fazer. Um pre-commit hook com agente de IA, por outro lado, consegue analisar a intenção da mudança, sugerir correções específicas para aquele trecho de código e até reescrever partes problemáticas automaticamente.

Usar Git hook Claude Code ou Git hook Codex transforma um mecanismo de verificação burro em um assistente de qualidade que entende o projeto.

Pre-commit hook com Claude Code — lint e formatação inteligentes

O pre-commit hook roda antes de git commit finalizar. É o momento perfeito para verificar formatação, sintaxe e boas práticas — com a diferença de que um agente de IA pode ir muito além de um linter tradicional.

Criando o hook

Navegue até a pasta de hooks do seu repositório e crie o arquivo pre-commit:

cd .git/hooks touch pre-commit chmod +x pre-commit # WSL ou Git Bash

No Windows puro (PowerShell), você precisa criar o arquivo e garantir que o Git Bash consiga executá-lo. Uma alternativa é usar a biblioteca husky, que gerencia hooks via npm e funciona bem no Windows:

npx husky init

Isso cria a pasta .husky/ na raiz do projeto, com suporte nativo ao Windows.

Conteúdo do hook com Claude Code

Abra o arquivo .husky/pre-commit e adicione:

#!/usr/bin/env bash echo "=== Pre-commit: analisando mudanças com Claude Code ===" # Lista arquivos staged STAGED=$(git diff --cached --name-only --diff-filter=d) if [ -z "$STAGED" ]; then echo "Nenhum arquivo staged. Pulando validação." exit 0 fi # Claude Code analisa o diff e valida o código claude --print " Analise o diff staged neste repositório e execute as seguintes verificações: 1. Erros de sintaxe nos arquivos modificados 2. Problemas de formatação (indentação, espaçamento, ponto-e-vírgula) 3. Importações não utilizadas ou circulares 4. Variáveis declaradas mas não usadas 5. Padrões que podem causar bugs em runtime Para cada problema encontrado: - Aponte o arquivo e a linha exata - Explique por que é um problema - Sugira a correção Se houver ERROS GRAVES (sintaxe quebrada, imports inválidos), retorne EXIT_FAILURE. Se houver apenas AVISOS (formatação, boas práticas), retorne EXIT_SUCCESS mas liste os avisos. Se estiver TUDO OK, retorne EXIT_SUCCESS com uma mensagem breve. " # Captura o exit code do Claude Code EXIT_CODE=$? if [ $EXIT_CODE -ne 0 ]; then echo "=== Pre-commit: problemas encontrados. Commit bloqueado. ===" echo "Corrija os erros apontados acima e tente novamente." exit 1 fi echo "=== Pre-commit: validação passou! ===" exit 0

A mágica está no prompt: em vez de regras fixas de lint, o pre-commit hook agente analisa o código com compreensão semântica. Ele detecta não apenas erros de sintaxe, mas padrões que um linter tradicional não pegaria — como uma variável usada de forma inconsistente ou uma importação circular que só existe em certos fluxos de execução.

Testando o hook

Faça uma alteração propositalmente errada em um arquivo e tente commitar:

echo "const x = ;" >> src/temp-test.js git add src/temp-test.js git commit -m "teste hook"

O Claude Code deve detectar o erro de sintaxe e bloquear o commit com a mensagem explicativa.

Pre-push hook com Codex — revisão antes do envio

O pre-push hook roda imediatamente antes de git push enviar os commits para o remoto. Diferente do pre-commit, que valida arquivo por arquivo, o pre-push tem visão do conjunto completo de mudanças que serão enviadas. É o momento ideal para uma revisão de código automatizada.

Instale o husky se ainda não tiver e crie o hook:

npx husky add .husky/pre-push

Conteúdo do hook com Codex

Edite .husky/pre-push:

#!/usr/bin/env bash echo "=== Pre-push: revisando mudanças com Codex ===" # Obtém a branch atual BRANCH=$(git rev-parse --abbrev-ref HEAD) echo "Branch: $BRANCH" # Compara a branch atual com a origem if git rev-parse --verify origin/$BRANCH > /dev/null 2>&1; then RANGE="origin/$BRANCH..HEAD" else RANGE="HEAD~1..HEAD" fi # Codex analisa o diff completo codex --print << PROMPT Review all changes in the range $RANGE of this repository. Execute the following checks: 1. Breaking changes — alterations that could break consumers of the code 2. Security vulnerabilities — exposed credentials, injection risks, missing validation 3. Test coverage — are new functions covered by tests? 4. Performance regressions — expensive operations in hot paths 5. Architectural consistency — do the changes follow the project's patterns? Format your response as a JSON array: [ { "severity": "error" | "warning" | "info", "file": "path/to/file", "line": 42, "message": "Description of the issue" } ] If there are ANY errors, exit with code 1. Otherwise exit with code 0. PROMPT EXIT_CODE=$? if [ $EXIT_CODE -ne 0 ]; then echo "=== Pre-push: problemas encontrados. Push bloqueado. ===" echo "Revise os apontamentos do Codex antes de enviar." exit 1 fi echo "=== Pre-push: revisão aprovada. Push autorizado. ===" exit 0

Usar Git hook Codex no pre-push é particularmente útil porque detecta problemas que só aparecem quando você olha o conjunto completo de mudanças — como uma refatoração que quebrou um contrato de API ou uma migração de banco que falta no commit.

Exemplo completo: hook que usa dois agentes em série

Em projetos mais estruturados, você pode combinar os dois hooks num fluxo contínuo: Claude Code no pre-commit para validação rápida, Codex no pre-push para revisão aprofundada. Mas também é possível criar um único hook que usa os dois agentes em sequência.

Abaixo está um script .husky/pre-push que roda Claude Code primeiro (validação leve) e Codex depois (revisão pesada), economizando tokens da API ao interromper no primeiro erro:

#!/usr/bin/env bash set -e echo "=== Fase 1: Claude Code — validação rápida ===" claude --print " Analise o diff entre a branch atual e origin/main. Verifique apenas: (1) erros de sintaxe, (2) imports quebrados, (3) variáveis undefined. Se tudo ok, retorne 'PASS'. Caso contrário, liste os problemas. " if [ $? -ne 0 ]; then echo "Fase 1 reprovada. Push bloqueado." exit 1 fi echo "=== Fase 2: Codex — revisão completa ===" codex --print " Review the full diff against origin/main. Check for: breaking changes, security issues, missing tests, performance problems. If any error-level issues found, exit with code 1. " if [ $? -ne 0 ]; then echo "Fase 2 reprovada. Push bloqueado." exit 1 fi echo "=== Push autorizado por ambos os agentes ===" exit 0

Esse script é a aplicação prática de automatizar Git hooks com múltiplos agentes: cada um faz o que faz de melhor, e o resultado é uma barreira de qualidade em duas camadas antes do código chegar ao repositório remoto.

Cuidados ao usar agentes em Git hooks

Usar agentes de IA em Git hooks é poderoso, mas exige atenção a alguns pontos:

Tempo de execução. Chamar uma API de IA dentro de um hook adiciona latência. Um pre-commit que leva 30 segundos pode quebrar o flow do time. Considere:

Usar modelos menores (Claude Haiku, GPT-4o mini) para verificações rápidas.
Limitar a análise apenas aos arquivos staged, não ao repositório inteiro.
Definir um timeout máximo no hook (ex.: timeout 60 claude ...).

Custo de API. Cada chamada ao Claude Code ou Codex consome tokens. Em um time de 10 devs fazendo 10 commits por dia, os custos somam rápido. Estratégias para mitigar:

Usar o agente apenas no pre-push (menos frequente), não no pre-commit.
Cachear resultados de arquivos não modificados entre execuções.
Alternar para verificações estáticas tradicionais nos hooks e deixar os agentes apenas para revisão.

Compatibilidade com Windows. No Windows, hooks precisam ser executáveis pelo Git Bash. Se você usa PowerShell puro, o husky é a abordagem mais confiável — ele gerencia a execução dos hooks via Node.js, que funciona em qualquer terminal Windows.

Falsos positivos e negativos. Agentes de IA não são infalíveis. Um hook pode bloquear um commit válido (falso positivo) ou deixar passar um problema real (falso negativo). A solução é sempre permitir bypass manual com uma flag: git commit --no-verify (pula pre-commit) ou git push --no-verify (pula pre-push).

Token de API no hook. Nunca hardcode chaves de API dentro do script do hook. Use variáveis de ambiente carregadas na sessão do terminal ou um gerenciador de segredos. Um hook comprometido dentro de um repositório compartilhado exporia suas chaves para todo o time.

FAQ

Preciso instalar algo além do agente para usar Git hooks?

Não. Git hooks são nativos do Git — você só precisa do Claude Code ou Codex instalado e acessível pelo terminal. O husky é opcional, mas recomendado no Windows para evitar problemas de permissão e path.

Um pre-commit hook agente funciona sem internet?

Não. Tanto Claude Code quanto Codex dependem de APIs na nuvem. Se você precisa de validação offline, mantenha hooks tradicionais (ESLint, Prettier, Jest) como fallback e use o agente como camada adicional.

Como evitar que o hook bloqueie commits em emergência?

Use git commit --no-verify para pular o pre-commit e git push --no-verify para pular o pre-push. São flags nativas do Git que funcionam independentemente do conteúdo do hook.

Dá para usar o mesmo hook em projetos diferentes?

Sim. Crie um script reutilizável em um diretório compartilhado (ex.: ~/.git-hooks/) e configure cada repositório para apontar para ele com git config core.hooksPath ~/.git-hooks/. Assim você mantém hooks centralizados sem duplicar código.

Agentes em hooks consomem muitos tokens da API?

Depende do tamanho do diff. Um commit com 5 arquivos pequenos consome centenas de tokens. Um commit com 50 arquivos grandes pode consumir milhares. Defina limites de escopo no prompt — por exemplo, "analise apenas os 10 maiores arquivos" — para controlar o consumo.

O hook pode corrigir o código automaticamente?

Sim. No pre-commit, o agente pode reescrever arquivos e usar git add para atualizar o staged. Mas isso é arriscado: uma correção automática pode introduzir mudanças inesperadas. Prefira o modo "sugerir e bloquear" em vez de "corrigir e commitar".

Automatize seus hooks hoje

Git hooks com agentes de IA são uma das maneiras mais eficazes de elevar a qualidade do código sem depender de disciplina manual. Com alguns minutos de configuração, você transforma Claude Code e Codex em guardiões automatizados do seu repositório — cada commit e push passa por validação inteligente antes de seguir adiante.

Comece instalando um agente no seu terminal e configurando o pre-commit hook de exemplo deste tutorial. Em meia hora, seu repositório já estará protegido contra commits quebrados. Quando sentir necessidade, adicione o pre-push com Codex para uma segunda camada de revisão.

E se você usa múltiplos agentes em paralelo, o Orquestra oferece um canvas infinito onde Claude Code e Codex trabalham lado a lado, com terminais isolados e contexto compartilhado entre projetos — tudo nativo no Windows, sem WSL.

Baixe o Orquestra para Windows 11 e comece seu teste gratuito de 7 dias.

*Todas as imagens sugeridas são meramente ilustrativas e podem variar conforme a ferramenta utilizada.*

Imagens sugeridas:

pre-commit-claude-block.png — Terminal mostrando pre-commit hook bloqueando commit com erro de sintaxe apontado pelo Claude Code
git-hooks-pipeline-agentes.png — Diagrama visual do pipeline pre-commit com Claude Code + pre-push com Codex
git-hooks-dual-agent.png — Tela de terminal mostrando hook de dois estágios com aprovação de ambos os agentes

Links internos:

Links externos:

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis