English 中文 العربية 日本語 Português

Claude Code: Sistema de Hooks

Última atualização: 2026-08-31

Hooks permitem inserir lógica customizada nos pontos-chave do Claude Code — auto-backup antes de modificações, auto-teste antes de commits, auto-rollback em erros.

💡 Dica: Hooks são "interceptadores" no ciclo de vida do Claude Code — você executa scripts customizados quando eventos específicos ocorrem, implementando fluxos de trabalho automatizados.

📋 Pré-requisitos: Capítulo 17 - Estilos de Saída

1. O Que Você Vai Aprender

2. Ciclo de Vida dos Hooks

(1) Tipos de Eventos

Evento Momento do Gatilho Uso Comum
before:prompt Antes de processar input do usuário Pré-processamento de input
before:tool:write Antes de escrever arquivo Auto-backup
after:tool:write Após escrever arquivo Auto-format
before:tool:bash Antes de executar comando Verificação de segurança
after:tool:bash Após executar comando Pós-processamento de resultado
after:response Após gerar resposta Enviar notificação

(2) Contexto do Hook

Cada hook recebe um objeto de contexto com nome do evento, timestamp, caminho do arquivo, comando, conteúdo e ID da sessão.

▶ Exemplo 1: Fluxo de Gatilho de Hooks

TEXT 📖 Somente leitura 
> Modify src/auth/jwt.ts

Hooks acionados:
1. [before:tool:write] → Auto-backup jwt.ts
2. [File written]
3. [after:tool:write] → Run ESLint --fix
4. [before:tool:bash] → Check command safety
5. [Execute: npm test]
6. [after:tool:bash] → Parse test results
7. [after:response] → Send Slack notification

3. Configuração de Hooks

(1) Configuração Global de Hooks

JSON 
// ~/.claude/hooks.json
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "auto-backup",
        "command": "cp ${filePath} ${filePath}.bak",
        "enabled": true
      }
    ],
    "after:tool:write": [
      {
        "name": "auto-format",
        "command": "npx prettier --write ${filePath}",
        "enabled": true
      }
    ]
  }
}

(2) Hooks em Nível de Projeto

JSON 
// .claude/hooks.json
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "protect-config",
        "condition": "filePath.endsWith('.env')",
        "command": "echo 'Config file modification blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

4. Cenários Práticos

▶ Exemplo 2: Hook de Auto-Backup

JSON 
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "git-backup",
        "command": "git stash push -m 'auto-backup-before-claude' -- ${filePath} 2>/dev/null || true",
        "enabled": true
      }
    ]
  }
}

▶ Exemplo 3: Hook de Auditoria de Segurança

JSON 
{
  "hooks": {
    "before:tool:bash": [
      {
        "name": "block-dangerous-commands",
        "condition": "command.includes('rm -rf') || command.includes('DROP TABLE')",
        "command": "echo '⚠️ Dangerous command blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

▶ Exemplo 4: Hook de Auto-Teste

JSON 
{
  "hooks": {
    "after:tool:write": [
      {
        "name": "auto-test",
        "condition": "filePath.includes('src/') && filePath.endsWith('.ts')",
        "command": "npm test 2>&1 | tail -5",
        "enabled": true
      }
    ]
  }
}

5. Debug de Hooks

BASH 
# Habilitar debug de hooks
export CLAUDE_HOOK_DEBUG=1

# Ver logs de execução de hooks
cat ~/.claude/hooks.log

# Desabilitar todos os hooks temporariamente
claude --no-hooks

Problemas Comuns

Problema Causa Solução
Hook não aciona enabled: false Verificar config
Erros no hook Problemas de caminho do comando Usar caminhos absolutos
Hook lento Tempo de execução do script Async ou simplificar lógica
Gatilho em loop Hook aciona outro hook Adicionar condições para evitar

6. Exemplo Completo: Solução Completa de Hooks

JSON 
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "auto-backup",
        "command": "cp ${filePath} /tmp/claude-backup/$(basename ${filePath}).$(date +%s)",
        "enabled": true
      },
      {
        "name": "protect-env",
        "condition": "filePath.endsWith('.env')",
        "command": "echo '❌ Env file modification blocked' && exit 1",
        "enabled": true
      }
    ],
    "after:tool:write": [
      {
        "name": "format",
        "command": "npx prettier --write ${filePath} 2>/dev/null; npx eslint --fix ${filePath} 2>/dev/null; true",
        "enabled": true,
        "files": ["src/**/*.ts"]
      }
    ],
    "before:tool:bash": [
      {
        "name": "block-dangerous",
        "condition": "command.match(/rm -rf|DROP|npm publish/)",
        "command": "echo '⛔ Dangerous command blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

❓ Perguntas Frequentes

P: Hooks deixam o Claude Code lento? R: Sim. Cada hook executa um comando; hooks lentos impactam notavelmente a experiência. Mantenha scripts de hook abaixo de 1 segundo.

P: Falha de hook bloqueia operações? R: Hooks before que falham (exit 1) bloqueiam operações; falhas em hooks after não afetam operações já completadas.

P: Hooks podem modificar a saída do Claude Code? R: Não. Hooks apenas realizam efeitos colaterais (backup, format, notificar), não mudam conteúdo retornado.

P: Hook vs Plugin? R: Hooks são respostas leves a eventos (executar comandos); plugins são extensões completas de funcionalidade (registram ferramentas, modificam comportamento). Necessidades simples: hooks; complexas: plugins.

📖 Resumo

📝 Exercícios

  1. Básico (⭐): Configure um hook after:tool:write que auto-executa Prettier na modificação de arquivos.
  2. Intermediário (⭐⭐): Configure hooks de segurança para bloquear rm -rf e npm publish.
  3. Avançado (⭐⭐⭐): Desenhe solução completa de hooks cobrindo backup, formatação, verificação de segurança e notificação.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%