Você vem dizendo ao Claude Code para rodar seus testes após cada mudança. Você colocou no CLAUDE.md. Você repetiu nos prompts. E às vezes ele faz. E às vezes não.
Esse é exatamente o problema que os hooks resolvem.
Os hooks convertem suas recomendações em cumprimento garantido. Não “Claude, por favor rode o linter” — mas uma regra que dispara automaticamente, sempre, não importa o que Claude decida. Essa é uma categoria diferente de controle.
O que são Hooks, exatamente?
Os hooks são comandos de shell (ou prompts, ou agentes) definidos por você que são executados automaticamente em pontos específicos do ciclo de vida do Claude Code. A Anthropic os introduziu em meados de 2025 e desde então são um dos recursos mais poderosos e menos usados da ferramenta.
A diferença chave com CLAUDE.md:
- CLAUDE.md / prompts: guias que Claude deveria seguir. Não determinísticos.
- Hooks: comandos que vão ser executados, sempre, sem exceções.
Se você já viu Claude pular uma etapa que você pediu explicitamente, os hooks são a solução.
Os Eventos do Lifecycle
Claude Code expõe múltiplos pontos onde os hooks podem disparar. Os mais importantes:
| Evento | Quando é executado |
|---|---|
PreToolUse |
Antes de Claude executar qualquer ferramenta — pode bloquear a ação |
PostToolUse |
Depois que uma ferramenta é concluída com sucesso |
Stop |
Quando Claude termina sua resposta |
Notification |
Quando Claude precisa de sua atenção (inativo, pedido de permissão, etc.) |
SessionStart |
No início de uma nova sessão |
UserPromptSubmit |
Quando você envia um prompt, antes de Claude processá-lo |
TaskCompleted |
Quando uma tarefa é marcada como concluída (novo em 2026) |
O crítico é PreToolUse. É o único hook que pode bloquear uma ação. Se seu hook retorna um sinal de rejeição, Claude não pode continuar. Tudo mais é reativo. PreToolUse é preventivo.
Três Tipos de Handlers
Claude Code suporta três tipos de handlers, cada um adequado para necessidades distintas:
1. Command hooks — Executam um comando de shell, recebem pass/fail de volta
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"handler": {
"type": "command",
"command": "npx prettier --write $FILEPATH"
}
}]
}
}
2. Prompt hooks — Usam um modelo Claude para avaliar condições semanticamente (para decisões que precisam de critério, não apenas pattern matching)
3. Agent hooks — Invocam um agente Claude completo com acesso a ferramentas para análise profunda
Comece com command hooks. São os mais previsíveis e mais fáceis de debugar. Suba para prompt ou agent hooks quando você precisar de raciocínio semântico.
Primeiros passos: o menu /hooks
A forma mais rápida de configurar seu primeiro hook é através do menu interativo — sem editar JSON:
# Dentro de Claude Code
/hooks
Você vai ver todos os eventos disponíveis. Selecione um, configure um matcher (use * para tudo, ou reduza para uma ferramenta específica), e insira um comando de shell. O menu pergunta onde salvar — escolha User settings para aplicar a todos seus projetos, ou Project settings para o repositório atual.
4 Hooks Práticos para Adicionar Hoje
1. Auto-format em cada edição de arquivo
Cada vez que Claude edita ou escreve um arquivo, seu formatter roda automaticamente:
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write|MultiEdit",
"handler": {
"type": "command",
"command": ".claude/hooks/auto-format.sh"
}
}]
}
}
# .claude/hooks/auto-format.sh
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
EXT="${FILE##*.}"
case "$EXT" in
js|ts|tsx|json) npx prettier --write "$FILE" ;;
py) black --quiet "$FILE" ;;
go) gofmt -w "$FILE" ;;
esac
exit 0
2. Firewall de segurança — bloqueia comandos perigosos
Use PreToolUse para interceptar e negar comandos de shell que correspondam a padrões perigosos:
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"handler": {
"type": "command",
"command": ".claude/hooks/security-guard.sh"
}
}]
}
}
# .claude/hooks/security-guard.sh
COMMAND=$(cat | jq -r '.tool_input.command // empty')
DANGEROUS=('rm\s+-rf\s+/' 'curl.*\|\s*bash' 'mkfs\.' 'chmod\s+-R\s+777\s+/')
for pattern in "${DANGEROUS[@]}"; do
if echo "$COMMAND" | grep -qE "$pattern"; then
jq -n --arg r "Bloqueado: padrão perigoso detectado" \
'{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
exit 0
fi
done
exit 0
3. Notificação de desktop quando Claude precisa de input
Nunca mais fique olhando para o terminal esperando:
# macOS
osascript -e 'display notification "Claude Code precisa de sua atenção" with title "Claude Code"'
Configure como hook Notification no menu /hooks com matcher *.
4. Requeira que os testes passem antes de qualquer PR
Bloqueie Claude de criar um pull request até que os testes estejam em verde:
# .claude/hooks/require-tests-for-pr.sh
if npm test -- --reporter=dot; then
exit 0
else
echo "Os testes estão falhando. Corrija-os antes de criar um PR." >&2
exit 2
fi
Configure como hook PreToolUse com matcher mcp__github__create_pull_request.
Equipes e Enterprise: Hooks como Camada de Guardrails
Aqui é onde os hooks se tornam genuinamente importantes em escala.
Quando você salva os hooks em .claude/settings.json na raiz do projeto e faz commit no repositório, cada desenvolvedor do time herda as mesmas regras automaticamente. Sem onboarding, sem documentação para lembrar, sem “esqueci de rodar o linter.”
Para equipes enterprise, isso significa:
- Conformidade de segurança: Bloqueie modificações em diretórios protegidos. Impeça que credenciais sejam escritas em arquivos. Negue padrões de shell associados a erros comuns.
- Audit logging: Cada comando Bash que Claude roda fica logado com timestamps — crítico para compliance e revisão pós-incidente.
- Quality gates: Nenhum PR é criado se os testes não passam. Nenhum commit passa se o lint falha.
- HTTP hooks: Em vez de rodar scripts locais, você pode apontar os hooks para um endpoint do time que aplica políticas da organização — um único lugar para atualizar regras que se propagam para todas as sessões de todos os desenvolvedores.
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"handler": {
"type": "http",
"url": "https://seu-servidor-time/hooks/security-check",
"timeout": 30,
"headers": { "Authorization": "Bearer $TEAM_TOKEN" }
}
}]
}
}
A diferença entre um time que usa Claude Code com hooks e um sem eles: um tem padrões determinísticos, o outro tem intenções.
Onde os Hooks Vivem
| Arquivo | Escopo |
|---|---|
~/.claude/settings.json |
Todos seus projetos, apenas em sua máquina |
.claude/settings.json |
Este projeto — faça commit para compartilhar com o time |
.claude/settings.local.json |
Este projeto, apenas em sua máquina (não faça commit) |
Aprenda Mais: O Curso Oficial Gratuito da Anthropic
Se você quer ir além dos hooks e entender a arquitetura completa do Claude Code — gerenciamento de contexto, tool chaining, integração MCP, conceitos do SDK — a Anthropic tem um curso oficial gratuito chamado Claude Code in Action, disponível em sua plataforma Skilljar em anthropic.skilljar.com/claude-code-in-action.É gratuito, leva poucas horas, cobre os hooks explicitamente, e ao final concede um certificado oficial da Anthropic que você pode adicionar ao seu perfil do LinkedIn. Para desenvolvedores que querem demonstrar conhecimento profissional de Claude Code, é a única credencial oficial disponível no momento.
Também está disponível no Coursera se você preferir esse ecossistema.
O Modelo Mental para Levar
Os hooks respondem uma única pergunta: o que deveria acontecer sempre, não importa o que Claude decida?
Seu formatter deveria rodar sempre. Suas verificações de segurança deveriam bloquear sempre. Os testes deveriam passar sempre antes de um PR sair.
Essas coisas vão em hooks. Tudo o mais vai em CLAUDE.md.
Essa combinação — cumprimento determinístico para o não-negociável, guias para tudo o mais — é como você constrói um workflow de Claude Code em que realmente pode confiar em escala.
Você já está usando hooks em seus projetos? Qual é o hook que teve mais impacto no seu fluxo? Nos conte nos comentários.