Neste artigo
- O que são hooks no Claude Code (em 30 segundos)
- Como eu decido: vai para o CLAUDE.md ou vira hook?
- Hook 1: bloquear edição em arquivos sensíveis
- Hook 2: barrar comandos que eu nunca quero ver o agente rodar
- Hook 3: formatar e checar lint depois de cada edição
- Hook 4: não deixar o agente dizer “pronto” com teste quebrado
- Bônus: devolver o contexto depois da compactação
- As armadilhas que me fizeram perder tempo
- Minha opinião: hooks são o “CI local” do agente
- Perguntas frequentes
- Hooks substituem o CLAUDE.md?
- Preciso saber Bash para usar hooks?
- Hook deixa o Claude Code mais lento?
Todo mundo que usa Claude Code por algumas semanas passa pelo mesmo momento: você escreve no CLAUDE.md “nunca edite o .env“, “sempre rode o formatter”, “não termine sem rodar os testes”… e um dia o agente simplesmente não faz. Não por maldade. Ele leu, entendeu e, no meio de uma tarefa longa, com o contexto cheio, priorizou outra coisa.
Demorei para aceitar o óbvio, que a própria documentação do Claude Code diz com todas as letras: o CLAUDE.md é tratado como contexto, não como configuração obrigatória. Se uma regra precisa valer sempre, ela não pode depender da boa vontade do modelo. Ela tem que virar código. E no Claude Code isso tem nome: hooks.
Minha tese é simples: instrução no CLAUDE.md é pedido; hook é regra. Neste artigo eu mostro como eu separo uma coisa da outra e os hooks que uso de verdade, com os scripts, e as armadilhas que me fizeram perder tempo.
O que são hooks no Claude Code (em 30 segundos)
Hooks são comandos (ou endpoints HTTP, prompts e até subagentes) que o Claude Code executa automaticamente em pontos fixos do ciclo de vida da sessão. Os que mais importam no dia a dia são:
- PreToolUse: roda antes de uma ferramenta ser executada (editar arquivo, rodar comando no terminal). Pode bloquear a ação.
- PostToolUse: roda depois que a ferramenta deu certo. Não desfaz nada, mas pode devolver um aviso para o Claude corrigir.
- Stop: roda quando o Claude termina de responder. Pode impedir que ele “dê por encerrado”.
- SessionStart: roda quando a sessão começa, retoma ou volta de uma compactação. O que o script imprime vira contexto.
O hook recebe um JSON no stdin com os dados do evento (por exemplo, tool_input.file_path numa edição ou tool_input.command num comando Bash) e responde por código de saída, stderr ou um JSON no stdout. Você configura em .claude/settings.json (vale para o projeto e pode ir para o repositório), em ~/.claude/settings.json (todos os seus projetos) ou em .claude/settings.local.json (só na sua máquina). A referência oficial de hooks lista todos os eventos; o guia prático tem exemplos prontos.
Como eu decido: vai para o CLAUDE.md ou vira hook?
Eu uso uma pergunta só: “se o agente ignorar isso uma vez, qual é o estrago?”
- Estrago pequeno, é questão de estilo ou preferência: fica no
CLAUDE.md. “Prefira composição a herança”, “nomes de teste em português”, “use o service X para chamadas externas”. Se ele errar, eu corrijo na revisão. - Estrago real ou regra que tem que valer 100% das vezes: vira hook. Mexer em segredo, em lockfile, em migration já aplicada, rodar
git push --force, entregar código sem formatar, dizer “pronto” com teste quebrado.
Um efeito colateral bom: o CLAUDE.md fica mais curto. Tirei dele um monte de “NUNCA” em caixa alta que só ocupava contexto. A documentação de memória do Claude Code vai na mesma linha: quanto mais específicas e concisas as instruções, mais consistentemente ele segue, e o que precisa rodar num ponto fixo (antes de commit, depois de cada edição) deve ser hook.
Hook 1: bloquear edição em arquivos sensíveis
É o primeiro que eu instalo em qualquer projeto. Um PreToolUse com matcher Edit|Write que olha o caminho do arquivo e sai com código 2 se for algo protegido. Salvo em .claude/hooks/protege-arquivos.sh:
#!/bin/bash
# .claude/hooks/protege-arquivos.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTEGIDOS=(".env" "composer.lock" "package-lock.json" ".git/" "database/migrations/")
for p in "${PROTEGIDOS[@]}"; do
if [[ "$FILE_PATH" == *"$p"* ]]; then
echo "Bloqueado: $FILE_PATH é protegido ($p). Crie uma migration nova ou me peça para editar manualmente." >&2
exit 2
fi
done
exit 0
E registro no .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protege-arquivos.sh" }
]
}
]
}
}
O detalhe que faz diferença é a mensagem no stderr. Com exit 2, o Claude recebe esse texto como erro da ferramenta e ajusta o plano. Por isso eu escrevo a mensagem como instrução (“crie uma migration nova”), não só como “proibido”. No meu caso, que trabalho muito com Laravel, travar database/migrations/ evitou o clássico “vou só ajustar essa coluna na migration que já rodou em produção”.
Um aviso honesto: isso bloqueia as ferramentas de edição, não o terminal. O agente ainda pode mudar o arquivo com um comando shell. Para fechar mais, a documentação recomenda somar regras de permissions.deny e, se precisar de garantia de verdade, sandbox. Hook é uma camada, não a fortaleza inteira.
Hook 2: barrar comandos que eu nunca quero ver o agente rodar
Mesma ideia, agora com matcher Bash, lendo tool_input.command:
#!/bin/bash
# .claude/hooks/comandos-proibidos.sh
CMD=$(jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -Eq 'git push .*(--force|-f)( |$)|rm -rf /|DROP (TABLE|DATABASE)|--env=production'; then
echo "Bloqueado: comando destrutivo ou de produção. Explique o que quer fazer e eu executo." >&2
exit 2
fi
exit 0
Aqui eu sou bem pragmático: regex em string de comando é fácil de contornar e não é controle de segurança sério. O objetivo não é parar um atacante; é parar o agente bem-intencionado que, às 23h, decidiu que um force push “resolve o conflito”. Para isso funciona muito bem. Um ponto que me deu confiança: segundo a documentação, um PreToolUse que nega a ação vale em todos os modos de permissão, inclusive quando alguém roda com --dangerously-skip-permissions.
Hook 3: formatar e checar lint depois de cada edição
Esse é o que mais melhorou a qualidade dos diffs que eu reviso. Um PostToolUse em Edit|Write que escolhe a ferramenta pela extensão:
#!/bin/bash
# .claude/hooks/formata.sh
F=$(jq -r '.tool_input.file_path // empty')
[ -z "$F" ] && exit 0
case "$F" in
*.php) vendor/bin/pint "$F" >/dev/null ;;
*.py) ruff format "$F" >/dev/null
ruff check "$F" 1>&2 || exit 2 ;;
*.ts|*.tsx|*.vue) npx prettier --write --ignore-unknown "$F" >/dev/null ;;
esac
exit 0
Repare na linha do ruff check: se o lint falha, eu mando a saída para o stderr e saio com 2. Num PostToolUse isso não desfaz a edição (a ferramenta já rodou), mas mostra o erro para o Claude, que corrige na hora. Antes, eu descobria o problema no CI, 10 minutos depois. Agora o agente descobre no mesmo passo.
Uma escolha consciente: eu não rodo a suíte de testes aqui. Teste depois de cada edição deixa a sessão lenta e gera ruído, porque no meio de uma refatoração o código fica quebrado de propósito por alguns passos.
Hook 4: não deixar o agente dizer “pronto” com teste quebrado
Os testes entram no Stop, que roda quando o Claude termina de responder. Se os testes falham, saio com 2 e ele continua trabalhando:
#!/bin/bash
# .claude/hooks/testes-antes-de-parar.sh
INPUT=$(cat)
# evita loop: se já estou numa continuação causada por este hook, deixa parar
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
# só roda se houve mudança em código
git diff --quiet -- app/ src/ tests/ && exit 0
if ! OUT=$(php artisan test --stop-on-failure 2>&1); then
echo "Os testes falharam. Corrija antes de encerrar:" >&2
echo "$OUT" | tail -n 30 >&2
exit 2
fi
exit 0
Duas coisas que aprendi apanhando. Primeiro: o Stop dispara sempre que o Claude termina uma resposta, não só quando a tarefa acabou. Se você faz uma pergunta rápida, ele roda também. Por isso o git diff --quiet: sem mudança em código, não tem por que rodar teste. Segundo: sem checar stop_hook_active, um teste que o agente não consegue consertar vira um loop. A documentação informa que o Claude Code sobrepõe o hook depois de oito bloqueios seguidos sem chamada de ferramenta no meio, mas é melhor não depender disso. Eu prefiro deixar ele parar e me explicar o que está travado.
Bônus: devolver o contexto depois da compactação
Em sessões longas, o contexto é compactado e detalhes se perdem. Um SessionStart com matcher compact resolve: o que o comando imprime no stdout volta para o contexto do Claude.
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{ "type": "command", "command": "echo \"Branch: $(git branch --show-current)\"; git log --oneline -5; cat .claude/tarefa-atual.md 2>/dev/null" }
]
}
]
}
}
Eu mantenho um tarefa-atual.md curto com o objetivo da tarefa e as decisões já tomadas. Depois da compactação, o agente “lembra” em que branch está e o que já foi decidido, sem eu ter que repetir.
As armadilhas que me fizeram perder tempo
- Exit 1 não bloqueia nada. Esse é o maior. Só o código 2 bloqueia. Qualquer outro código diferente de zero é tratado como erro não bloqueante: a ação segue. Já vi hook de proteção “funcionando” por semanas sem bloquear nada porque terminava com
exit 1. - Script sem permissão de execução. Esqueceu o
chmod +x, o hook não roda. - JSON inválido no settings. Vírgula sobrando ou comentário e os hooks somem. O comando
/hooksdentro do Claude Code mostra o que foi carregado e de onde; é a primeira coisa que eu olho. - Matcher é sensível a maiúsculas.
edit|writenão casa comEdit|Write. - Dependências do script. Os exemplos usam
jq. Na máquina de um colega semjq, o hook quebra. Para testar fora do Claude, eu faço:echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protege-arquivos.sh; echo $?. - Hook roda com as suas permissões. Hook de projeto é código executando na sua máquina. Antes de abrir um repositório de terceiros com Claude Code, eu leio o
.claude/settings.jsondele.
Minha opinião: hooks são o “CI local” do agente
Quando comecei a usar agentes de código, eu tentava resolver tudo no prompt e no arquivo de regras. Funcionava 90% das vezes, e os 10% restantes eram justamente os que doíam. O que mudou o jogo foi tratar o agente como trato um dev novo no time: eu não confio que ele vai lembrar de rodar o lint, eu coloco o lint no pipeline. Hooks são esse pipeline, rodando dentro da sessão.
Se você vai começar, não instale dez de uma vez. Comece pelo hook 1 (arquivos protegidos) e pelo hook 3 (formatter). São os de menor atrito e maior retorno. Depois de uma semana, você vai saber onde o agente mais escorrega no seu projeto, e o próximo hook se escreve sozinho. Escrevi sobre o resto do meu ambiente em meu setup Cursor + Claude Code em 2026, e o que eu olho na revisão do que sai do agente está em como eu reviso PR gerado por IA.
Perguntas frequentes
Hooks substituem o CLAUDE.md?
Não. O CLAUDE.md continua sendo o lugar de contexto: arquitetura, convenções, como o projeto funciona. Hooks são para o que precisa ser garantido. Os dois se complementam.
Preciso saber Bash para usar hooks?
Ajuda, mas o hook pode ser qualquer executável que leia JSON do stdin: Python, Node, PHP. O que importa é o contrato: ler o JSON, decidir e sair com 0 (segue) ou 2 (bloqueia).
Hook deixa o Claude Code mais lento?
Depende do que você roda. Formatter num arquivo é quase instantâneo. Suíte de testes inteira a cada edição deixa tudo lento, por isso eu coloco testes só no Stop e só quando há mudança em código.
Prefere a versão rápida? Veja a Web Story com os hooks em 11 telas.
Quer ir além? No Labs de IA eu mostro na prática como uso Claude Code, agentes e automações no trabalho, do jeito que faço no dia a dia.






