Dominando os Hooks do Claude Code: Auto-Formatação, Auto-Testes e Mais

O Que São Hooks?

Os hooks do Claude Code permitem executar automaticamente comandos personalizados antes ou depois de ações específicas. Você pode configurar auto-formatação após salvar arquivos, executar testes automaticamente após alterações no código e muito mais.

Os hooks são definidos em .claude/settings.json e executam comandos shell quando o Claude Code realiza determinadas operações.

Tipos de Hooks

O Claude Code suporta hooks nos seguintes pontos de evento:

Evento do Hook	Quando é Disparado
PreToolUse	Antes de uma ferramenta ser executada
PostToolUse	Depois de uma ferramenta ser executada
Notification	Quando uma notificação é enviada
Stop	Quando o Claude Code termina de responder

Configuração Básica

Os hooks são definidos no campo hooks de .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Estrutura da Configuração

• matcher: Um padrão regex que corresponde ao nome da ferramenta que dispara o hook
• command: O comando shell a ser executado

Caso de Uso 1: Auto-Formatação

Executar o Prettier automaticamente após qualquer edição de arquivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Com essa configuração, toda vez que o Claude Code cria ou edita um arquivo, o Prettier o formata automaticamente. O estilo de código da sua equipe se mantém consistente sem nenhum esforço manual.

Caso de Uso 2: Auto-Linting

Veja como integrar a correção automática do ESLint:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

O sufixo || true evita que erros de lint causem falha no hook, permitindo que o Claude Code continue o processamento.

Caso de Uso 3: Testes Automáticos ao Alterar

Executar automaticamente os testes relacionados após edições de arquivos e retornar os resultados:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx vitest related \"$CLAUDE_FILE_PATH\" --run 2>&1 | tail -20"
      }
    ]
  }
}

A opção related do Vitest executa apenas os testes relevantes para o arquivo alterado, proporcionando feedback muito mais rápido do que uma suíte de testes completa.

Caso de Uso 4: Verificação Automática de Tipos

Executar a verificação de tipos do TypeScript após alterações nos arquivos:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }
    ]
  }
}

Caso de Uso 5: Bloquear Comandos Perigosos

Um hook PreToolUse que impede a execução de comandos arriscados:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|drop table|git push.*force'; then echo 'BLOQUEADO: Comando perigoso detectado' >&2; exit 1; fi"
      }
    ]
  }
}

Quando o hook termina com código 1, o Claude Code pula completamente a execução da ferramenta.

Caso de Uso 6: Notificações de Conclusão

Enviar uma notificação quando o Claude Code finaliza uma tarefa:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "notify-send 'Claude Code' 'Tarefa concluída' 2>/dev/null; echo 'Pronto'"
      }
    ]
  }
}

No macOS, você pode usar:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification \"Tarefa concluída\" with title \"Claude Code\"'"
      }
    ]
  }
}

Combinando Múltiplos Hooks

Em projetos reais, combinar vários hooks é a abordagem mais eficaz:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /'; then exit 1; fi"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '✓ Tarefa concluída'"
      }
    ]
  }
}

Dicas para Escrever Hooks

1. Mantenha o Tempo de Execução Curto

Os hooks executam de forma síncrona, então operações pesadas vão desacelerar as respostas do Claude Code. Use opções como related para limitar o escopo dos testes, e head ou tail para reduzir a saída.

2. Trate Erros com Elegância

Um hook que termina com erro pode interromper o fluxo de trabalho do Claude Code. Use || true e 2>/dev/null para manter tudo seguro.

3. Use Variáveis de Ambiente

Aproveite as variáveis de ambiente disponíveis nos hooks. $CLAUDE_FILE_PATH fornece o caminho do arquivo sendo operado.

Conclusão

Os hooks permitem personalizar profundamente o fluxo de trabalho do Claude Code. A combinação de auto-formatação e auto-testes é especialmente poderosa para manter a qualidade do código. Comece com a auto-formatação do Prettier e evolua a partir daí.