Claude Code Hooks: um guia prático de automação de fluxo de trabalho

Ao trabalhar com Claude Code, é comum notar um problema: ele escreve um bom código, mas esquece etapas importantes como formatar, rodar testes ou seguir protocolos de segurança. Você acaba repetindo os mesmos lembretes toda hora. Os Claude Code Hooks permitem automatizar esses lembretes executando comandos de shell automaticamente em pontos específicos do seu fluxo de trabalho.

Neste tutorial, eu mostro como configurar hooks para formatação de código, execução de testes, notificações e proteção de arquivos. Você vai construir um sistema de automação que aplica seus padrões de desenvolvimento sem intervenção manual.

Para saber mais sobre Claude Code, confira nosso guia de boas práticas do Claude Code e o tutorial de Claude Skills. Se você quer aprender a configurar instruções no nível do projeto, veja nosso guia sobre como escrever um CLAUDE.md.

Resumo

• Claude Code Hooks são comandos de shell que rodam automaticamente em pontos específicos do ciclo de vida do Claude Code (antes/depois de chamadas de ferramentas, no início da sessão, quando o Claude para)

• Configure-os em .claude/settings.json (projeto) ou ~/.claude/settings.json (global) usando JSON com eventos, matchers e comandos

• Use hooks PreToolUse para bloquear operações perigosas antes que aconteçam (código de saída 2 = bloquear)

• Use hooks PostToolUse para tarefas de limpeza como formatação, linting ou execução de testes depois que o Claude escreve código

• Hooks recebem contexto em JSON via stdin e comunicam resultados por códigos de saída, stdout e stderr

O que são Claude Code Hooks?

Claude Code Hooks são comandos de shell que rodam automaticamente quando eventos específicos acontecem durante sua sessão de codificação com IA. Pense neles como gatilhos automáticos que executam seus scripts personalizados em momentos precisos—antes do Claude escrever um arquivo, depois de rodar um comando ou quando ele envia uma notificação.

O sistema funciona monitorando as ações do Claude Code e comparando com regras definidas por você em um arquivo de configuração. Quando há correspondência, o comando especificado roda com acesso ao contexto do que acabou de acontecer. Isso dá controle sobre o comportamento do Claude e permite automatizar tarefas repetitivas que, de outra forma, exigiriam intervenção manual.

Aqui vai um hook básico que roda um formatador de código toda vez que o Claude escreve um arquivo Python:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black ."
          }
        ]
      }
    ]
  }
}

Este hook tem três partes: 

• O evento: PostToolUse (depois que o Claude finaliza uma ação)

• O matcher: Write (apenas quando escreve arquivos)

• O comando: python -m black . (formata arquivos Python no diretório atual)

O hook recebe informações detalhadas sobre o que o Claude acabou de fazer por meio de dados JSON enviados para a entrada do script, então você pode criar automações mais sofisticadas que reagem a mudanças específicas de arquivos.

Se quiser ir além com automação no Claude Code, nosso tutorial de Claude Code Routines mostra como agendar hooks e agentes para rodar de forma recorrente na nuvem.

Vamos ver como criar hooks do zero e registrá-los no Claude Code.

Pré-requisitos

Você vai precisar de algumas coisas antes de começar:

• Claude Code instalado e rodando: Você deve estar à vontade usando o Claude Code para tarefas básicas de codificação

• Familiaridade com linha de comando: Hooks rodam comandos de shell, então você precisa saber escrever comandos básicos de terminal do seu sistema operacional

• Acesso a um editor de texto: Você vai editar arquivos de configuração JSON para configurar seus hooks

• Diretório de projeto: Um projeto de código onde você possa testar hooks com segurança sem afetar trabalhos importantes

Você não precisa ser expert em shell script, mas entender como rodar comandos como ls, cd e operações básicas com arquivos vai ajudar a acompanhar os exemplos. Se você é iniciante em bash ou no terminal, recomendo nosso curso Introduction to Shell.

Começando com Claude Code Hooks

Agora que você entendeu o que são hooks, vamos configurar sua primeira automação. O processo envolve escolher o evento certo, configurar uma regra simples e testá-la com um comando básico.

Entendendo os eventos de hook

O Claude Code expõe mais de 25 eventos de hook. A tabela abaixo cobre os 10 que você vai usar com mais frequência. Para a lista completa, veja a referência oficial de hooks.

PreToolUse e PostToolUse são os eventos mais comuns. PreToolUse roda antes do Claude executar uma ação como escrever um arquivo ou rodar um comando, o que é perfeito para validação ou para bloquear operações perigosas. PostToolUse roda depois que o Claude conclui uma ação, ideal para tarefas de limpeza como formatar código ou rodar testes.

UserPromptSubmit dispara quando você envia um prompt para o Claude, antes de ele processar seu pedido. Você pode usar isso para adicionar contexto à conversa ou validar que os prompts atendem a certos requisitos.

Notification roda quando o Claude envia alertas, como pedir permissão para rodar um comando ou quando precisa do seu input. PermissionRequest dispara quando o Claude Code exibe um diálogo de permissão, permitindo aprovar ou negar automaticamente em nome do usuário.

Stop e SubagentStop disparam quando o Claude termina de responder, o que é útil para verificações finais ou geração de relatórios. A diferença é que Stop dispara quando o Claude finaliza a resposta geral, enquanto SubagentStop faz isso quando um ajudante gerado por ferramenta (um “subagent”) termina seu trabalho.

Os eventos restantes, PreCompact, SessionStart e SessionEnd, lidam com situações específicas do ciclo de vida. PreCompact roda pouco antes do Claude encurtar o histórico da conversa. ‘SessionStart’ dispara no começo de uma nova sessão para definir padrões, e SessionEnd dispara quando a sessão fecha, permitindo limpeza ou relato final.

Entendendo os matchers

Matchers são os filtros que decidem quais ações do Claude Code disparam um hook. Tecnicamente, são strings interpretadas como expressões regulares, então você pode usar correspondências exatas ou padrões mais flexíveis. 

Os matchers mais relevantes são simples, como Write (dispara quando o Claude escreve um arquivo) ou Edit (dispara ao editar conteúdo), e combinações como Edit|Write para cobrir múltiplas ações. 

Você também pode usar prefixos como Notebook.* para corresponder a todas as ferramentas que começam com “Notebook.”. Se quiser que o hook dispare em toda ação, use a regex universal .*, uma string vazia ("") ou deixe matcher em branco.

Como os matchers diferenciam maiúsculas de minúsculas e atuam apenas nos nomes das ações, é melhor mantê-los o mais específicos possível. Quando precisar de controle mais fino (por exemplo, limitar o hook a certos tipos de arquivos), você pode ler o payload JSON que o Claude passa para o hook e aplicar sua própria regex ou condições ali.

Criando seu primeiro hook no Claude Code

O Claude Code oferece duas maneiras de configurar hooks: pelo comando interativo /hooks ou editando diretamente os arquivos de configuração. Vamos começar pelo modo interativo, que é mais amigável para iniciantes.

Usando o comando /hooks:

1. Abra o Claude Code e digite /hooks na interface do chat

2. Escolha o evento de gatilho (selecione PostToolUse neste exemplo)

3. Selecione "Add new hook" no menu

4. Defina o padrão do matcher (digite Write para mirar escrita de arquivos)

5. Insira seu comando:

• Mac: say "Task complete"

• Windows: powershell -c [console]::beep()

• Linux: spd-say "Task complete"

6. Salve a configuração e volte ao Claude Code pressionando Esc três vezes

O comando /hooks vai atualizar automaticamente seu arquivo de configurações e recarregar a configuração. Você também pode usar /hooks a qualquer momento para ver seus hooks existentes ou fazer alterações.

Se preferir editar os arquivos de configuração diretamente, os hooks ficam em ~/.claude/settings.json para configurações globais, .claude/settings.json dentro do diretório do projeto (faça commit no repositório para hooks compartilhados com o time) ou .claude/settings.local.json para hooks pessoais que são ignorados pelo git por padrão. No nosso exemplo acima, ficaria assim:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Task complete'"
          }
        ]
      }
    ]
  }
}

Depois de editar o arquivo manualmente, reinicie o Claude Code ou use o comando /hooks para recarregar sua configuração. Agora, toda vez que o Claude escrever um arquivo, você ouvirá uma notificação sonora.

Testando seu hook

Antes de avançar, verifique se o seu hook realmente funciona:

1. Peça ao Claude para escrever qualquer arquivo Python (ex.: "Crie um arquivo hello.py que imprime hello world")

2. Você deve ouvir a notificação sonora quando o Claude concluir a operação de escrita

3. Se não ouvir nada, verifique a transcrição do Claude Code pressionando Ctrl-O para ver possíveis mensagens de erro

4. Problemas comuns incluem não encontrar o comando do hook, permissões de arquivo incorretas ou erros de sintaxe no arquivo de configuração

Fazer esse teste básico funcionar economiza tempo de depuração quando você construir hooks mais complexos. Se você acabou de editar o arquivo de configurações manualmente, mudou o matcher ou evento, ou instalou novas ferramentas que quer usar em um comando de hook, pode ajudar reabrir o /hooks ou reiniciar o Claude para recarregar a configuração.

Esse padrão básico (evento, matcher, comando) é a base de toda automação com hooks. Você pode expandir adicionando vários comandos para rodarem simultaneamente quando o mesmo evento for disparado. Por exemplo, você pode querer tocar um som e criar um backup quando o Claude escreve um arquivo. 

Também dá para criar matchers separados para diferentes ferramentas dentro do mesmo evento, então escrita de arquivos dispara ações diferentes de edição de código. Todos os hooks que correspondem ao mesmo padrão de ferramenta rodam em paralelo. Se você configurar múltiplos matchers para o mesmo evento, cada hook roda quando seu matcher é acionado.

Trabalhando com entradas dos hooks

Quando o Claude Code dispara um hook, ele envia informações sobre o que acabou de acontecer pela entrada padrão (stdin), um fluxo de dados que vai direto para o seu comando quando ele roda. É isso que torna os hooks poderosos, em vez de scripts aleatórios rodando em horários arbitrários. 

O Claude Code empacota essas informações em JSON e as envia para qualquer comando que você configurou, seja um comando simples de terminal ou um script personalizado.

Anatomia das entradas de hook

Todo hook recebe um objeto JSON com campos básicos sobre a sessão atual:

{
  "session_id": "abc123",
  "transcript_path": "/Users/you/.claude/projects/my-project/conversation.jsonl", 
  "cwd": "/Users/you/my-project",
  "hook_event_name": "PostToolUse"
}

Vamos traduzir cada componente:

• session_id: identifica sua conversa atual

• transcript_path: aponta para o histórico da conversa

• cwd: mostra o diretório de trabalho

• hook_event_name: diz qual evento foi disparado

Ter esse contexto permite que seus hooks tomem decisões inteligentes: você pode rastrear qual conversa acionou uma ação, acessar todo o histórico do chat se necessário ou rodar comandos no diretório correto.

Variações de entrada por evento

Eventos de ferramenta como PreToolUse e PostToolUse incluem detalhes extras sobre a ação, e é aí que os hooks ficam realmente úteis para automação. Em PreToolUse, o tool_input é especificado, e o tool_response é adicionado em PostToolUse:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.py",
    "content": "print('Hello world')"
  },
  "tool_response": {
    "filePath": "/path/to/file.py", 
    "success": true
  }
}

Na entrada do hook, file_path mostra o caminho do arquivo sendo escrito ou editado, enquanto content contém o texto exato que a ferramenta está prestes a escrever. Após a execução, a resposta da ferramenta repete o filePath final (note o camelCase) para confirmar qual arquivo foi realmente alterado, junto com a flag success indicando se a operação concluiu corretamente. 

Essas informações detalhadas permitem que seus hooks reajam de forma diferente conforme o que aconteceu. Você pode formatar apenas arquivos Python, fazer backup só de diretórios importantes ou enviar notificações apenas quando certos tipos de arquivo forem modificados.

Eventos como UserPromptSubmit são mais simples, já que não envolvem ferramentas:

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit", 
  "prompt": "Write a function to calculate factorial"
}

Note que hooks UserPromptSubmit não usam matchers na configuração. Eles disparam em todos os prompts, não em operações de ferramenta. Isso é perfeito para registrar conversas, adicionar contexto do projeto automaticamente ou validar prompts antes de o Claude processá-los.

Lendo a entrada do hook na prática

Vamos criar um hook que registra todo prompt do usuário. Isso resolve o problema de perder o controle do que você pediu para o Claude fazer, especialmente em sessões longas. Primeiro, a configuração do hook:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/log_prompts.py"
          }
        ]
      }
    ]
  }
}

Em seguida, crie o script Python em ~/.claude/log_prompts.py com o seguinte conteúdo:

#!/usr/bin/env python3
import json
import sys
from datetime import datetime

# Read JSON data from stdin
input_data = json.load(sys.stdin)

# Extract information
session_id = input_data.get("session_id", "unknown")
prompt = input_data.get("prompt", "")
timestamp = datetime.now().isoformat()

# Log the prompt
log_entry = f"{timestamp} | Session: {session_id[:8]} | {prompt}\n"
with open("prompt_history.txt", "a") as f:
    f.write(log_entry)

O script lê os dados JSON enviados pelo Claude Code e registra o prompt com o contexto da sessão. Isso cria um histórico pesquisável das suas interações, o que se torna valioso quando você precisar lembrar como resolveu um problema semanas depois.

Trabalhando com as saídas dos hooks

Depois que seu comando de hook roda, ele precisa dizer ao Claude Code o que aconteceu e se deve continuar normalmente. Esse mecanismo de controle transforma hooks de simples ferramentas de log em automações poderosas de fluxo de trabalho que orientam o comportamento do Claude. Isso acontece por três canais: saída padrão (stdout), erro padrão (stderr) e códigos de saída.

Canais de saída e códigos de saída

A saída padrão (stdout) representa a saída normal. Por exemplo, se você imprimir algo, vai para o stdout. Para a maioria dos hooks, é isso que aparece na transcrição do Claude Code quando você pressiona Ctrl-O, dando um registro do que sua automação fez sem poluir a conversa principal.

O erro padrão (stderr) se refere a mensagens de erro. Você pode escrever no stderr usando 

• Python: print("message", file=sys.stderr) ou

• Linha de comando: echo "message" >&2

A diferença é que o stderr pode ser enviado diretamente ao Claude para processamento automático, permitindo que ele responda aos problemas que seus hooks detectarem.

Os códigos de saída dizem ao Claude Code o que fazer a seguir:

• Código de saída 0: Sucesso (mostra o stdout para o usuário)

• Código de saída 2: Erro bloqueante (envia o stderr para o Claude)

• Outros códigos: Erro não bloqueante (mostra o stderr para o usuário, mas continua)

Esse sistema dá controle refinado sobre quando o Claude deve parar, continuar ou receber feedback sobre o que sua automação descobriu. Vamos ver exemplos dos dois códigos mais importantes.

Código de saída 0: operação normal

A maioria dos hooks usa código 0 para indicar que tudo deu certo. Aqui vai um hook completo que registra operações de arquivo e notifica o usuário:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import datetime; open('activity.log','a').write('File written: ' + datetime.datetime.now().isoformat() + '\\n'); print('Logged file operation')\""
          }
        ]
      }
    ]
  }
}

Este hook roda duas ações: registra em um arquivo e depois imprime uma mensagem na transcrição. Há muitas formas de fazer isso, mas essa abordagem é multiplataforma e evita depender de especificidades da linha de comando.

Como não há código de saída explícito, o padrão é 0. A mensagem impressa aparece na transcrição do Claude Code, dando um retorno de que o log funcionou. Esse padrão é perfeito para construir trilhas de auditoria ou acompanhar as mudanças que o Claude faz no seu projeto ao longo do tempo.

Código de saída 2: bloqueio com feedback

O código 2 envia sua mensagem de erro diretamente ao Claude, permitindo que ele responda automaticamente. É aqui que os hooks viram um mecanismo de segurança, e não apenas automação. Veja um hook que bloqueia operações perigosas em arquivos:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/security_check.py"
          }
        ]
      }
    ]
  }
}

Você vai precisar criar o script de verificação de segurança em ~/.claude/security_check.py:

#!/usr/bin/env python3
import json
import sys

# Read hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Check for dangerous patterns
dangerous_paths = ["/etc/", "/usr/", "production.conf"]
is_dangerous = any(pattern in file_path for pattern in dangerous_paths)

if is_dangerous:
    # Block the operation and tell Claude why
    print(f"Blocked modification of {file_path} - this appears to be a system or production file", file=sys.stderr)
    sys.exit(2)  # Sends stderr message to Claude
else:
    # Allow the operation
    print(f"Approved modification of {file_path}")
    sys.exit(0)  # Shows stdout in transcript

Quando esse hook detecta um caminho perigoso, ele sai com código 2. O Claude Code envia a mensagem do stderr ao Claude, que então consegue explicar por que a operação foi bloqueada e sugerir alternativas. Isso evita danos acidentais a arquivos do sistema enquanto mantém o Claude informado sobre suas políticas de segurança.

Construindo um hook de notificação inteligente para o Claude Code

Vamos construir uma versão melhorada do hook de notificação que combina processamento de entrada com tratamento inteligente de saída. Isso resolve o ruído do nosso hook original, que alertava a cada alteração de arquivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/smart_notify.py"
          }
        ]
      }
    ]
  }
}

Crie o script de notificação em ~/.claude/smart_notify.py:

#!/usr/bin/env python3
import json
import sys
import os
import subprocess

# Read the hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Categorize file importance
important_extensions = [".py", ".js", ".ts", ".java", ".cpp"]
config_files = ["Dockerfile", "requirements.txt", "package.json"]

is_code = any(file_path.endswith(ext) for ext in important_extensions)
is_config = any(filename in file_path for filename in config_files)

if is_code:
    # Important: notify and log
    print(f"Code file modified: {os.path.basename(file_path)}")
    subprocess.run(["say", "Code updated"], check=False)  # Mac
    sys.exit(0)  # Show message in transcript
elif is_config:
    # Very important: louder notification
    print(f"Configuration file changed: {os.path.basename(file_path)}")
    subprocess.run(["say", "Configuration updated - review changes"], check=False)
    sys.exit(0)
else:
    # Not important: silent success
    sys.exit(0)

Este hook lê a entrada para entender qual arquivo foi modificado, decide o nível de importância da notificação com base no tipo de arquivo, usa stdout para registrar mudanças importantes na transcrição, dispara alertas sonoros diferentes por tipo de arquivo e sempre sai com código 0, já que são ações informativas, não bloqueantes.

A combinação de análise de entrada com controle de saída cria um hook que se comporta de forma inteligente conforme o contexto, oferecendo o nível certo de feedback para você e para o Claude Code. Em vez de receber alertas chatos para cada arquivo temporário, você só ouve sobre mudanças que realmente importam para o seu projeto.

Observe que este exemplo usa o comando say, disponível no macOS. No Linux, você pode usar notify-send, e no Windows, um comando do PowerShell, para obter notificações semelhantes.

Armadilhas comuns com Claude Code Hooks

Algumas coisas que costumam pegar a maioria das pessoas na primeira semana com hooks:

Echo no perfil do shell quebra hooks. Hooks rodam em shells não interativos que carregam seu ~/.zshrc ou ~/.bashrc. Se seu perfil tem echo incondicionais, eles colocam texto antes do stdout do hook e quebram a análise de JSON. Envolva em uma checagem de shell interativo:

if [[ $- == *i* ]]; then
  echo "Welcome back"
fi

Hooks de Stop podem entrar em loop infinito. Um hook Stop que sai com código 2 força o Claude a continuar trabalhando. Se seu script não checar stop_hook_active no JSON de entrada e encerrar corretamente quando for true, você vai girar até dar timeout. Sempre inclua um guard de saída antecipada.

Matchers diferenciam maiúsculas de minúsculas. bash não corresponde a Bash. Use exatamente o nome da ferramenta como aparece no Claude Code.

A saída é limitada a 10.000 caracteres. Se seu hook gerar mais, será truncado antes de ser injetado no contexto do Claude. Mantenha o stdout conciso e mostre só o necessário para o modelo agir.

Confusão entre hooks de time e pessoais. Hooks em .claude/settings.json são compartilhados com o time (faça commit no repositório). Para hooks pessoais que você não quer compartilhar, use .claude/settings.local.json, ignorado pelo git por padrão.

Hooks vs. skills: quando usar cada um

Hooks e Claude Skills têm propósitos diferentes e funcionam melhor juntos. Uma skill é um arquivo markdown que ensina o Claude a fazer algo (procedimentos, convenções, modelos). Um hook é um comando de shell que aplica uma regra de forma determinística, independentemente do que o Claude decidir.

A distinção importa: uma skill é uma sugestão que o modelo pode ignorar sob pressão; um hook dispara toda vez. Escreva uma skill para documentar o procedimento de migração do seu time. Escreva um hook PostToolUse para rodar o linter de migração em todo arquivo .sql que o Claude escrever. A skill torna o Claude competente; o hook torna o Claude responsável.

Padrões avançados para Claude Code Hooks

Além de notificações e logs básicos, hooks podem resolver problemas reais de fluxo de trabalho de desenvolvimento que os times enfrentam no dia a dia. Aqui estão algumas ideias para você adaptar aos seus projetos.

A boa notícia é que você não precisa construir esses hooks manualmente. Basta dar ao Claude Code uma das ideias de prompt abaixo, junto com a referência de Hooks na documentação, e ele vai gerar o código e o JSON de configuração relevantes.

Cada um desses padrões pode ser personalizado para suas ferramentas e fluxo de trabalho. Comece pelos que resolvem suas maiores dores diárias e depois expanda sua automação conforme ganhar confiança desenvolvendo hooks.

Hooks avançados para segurança e conformidade

Hooks são ótimos para aplicar regras de segurança e padrões de compliance. Aqui vão quatro casos de uso.

Scanner de chaves de API

• Problema: Fazer commit de segredos acidentalmente no controle de versão

• Gatilhos: Antes de escrever qualquer arquivo

• Solução: Analisar o conteúdo do arquivo em busca de chaves de API, tokens e senhas usando regex

“Crie um script em Python que leia o JSON de entrada do hook, extraia o conteúdo do arquivo e use regex para detectar formatos comuns de segredos como api_key=, token: ou password=.  Para qualquer correspondência suspeita, faça verificação local e nunca envie segredos crus externamente. 

Envie apenas trechos mascarados (ex.: mantenha 4 caracteres de prefixo/sufixo) ou hashes para a API da Anthropic para analisar strings suspeitas e decidir se são segredos reais ou nomes de variáveis. Saia com código 2 e forneça feedback ao Claude sobre segredos detectados e alternativas mais seguras.”

Aplicador de cabeçalho de licença

• Problema: Projetos open source sem cabeçalhos de licença obrigatórios em novos arquivos

• Gatilhos: Antes de escrever arquivos de código-fonte

• Solução: Validar que novos arquivos .py, .js, .java contenham o texto de licença adequado

“Faça o parse da entrada do hook para obter o conteúdo do arquivo e verifique se as 10 primeiras linhas contêm o texto da licença usando comparação de strings. Para validação mais sofisticada, envie o cabeçalho do arquivo para o Claude via API da Anthropic para checar se contém avisos de direitos autorais e informações de licença adequadas. Bloqueie a criação de arquivos com código 2 se os cabeçalhos estiverem ausentes e forneça ao Claude o modelo de licença correto para adicionar.”

Guardião de arquivos de produção

• Problema: Modificar acidentalmente arquivos críticos de configuração do sistema

• Gatilhos: Antes de editar arquivos em diretórios sensíveis

• Solução: Bloquear mudanças em /etc/, nginx.conf, database.yml e outras configs críticas

“Extraia o caminho do arquivo do JSON de entrada do hook e verifique se ele corresponde a padrões como /etc/, production.yml ou outros nomes críticos. Use a API do Claude para analisar o caminho e determinar se é um arquivo de configuração que pode afetar sistemas de produção. Saia com código 2 e forneça orientação específica sobre práticas de desenvolvimento mais seguras quando caminhos perigosos forem detectados.”

Otimizador de imagens

• Problema: Arquivos de imagem grandes deixando apps e repositórios lentos

• Gatilhos: Depois de adicionar novos arquivos de imagem

• Solução: Comprimir arquivos PNG/JPEG mantendo a qualidade visual

“Faça o parse da entrada do hook para obter o caminho do arquivo e verifique se é uma imagem pelo sufixo. Rode ferramentas de compressão como imageoptim ou chame a API do TinyPNG para comprimir preservando a qualidade. Registre os resultados da compressão no stdout para ver a economia de tamanho na transcrição do Claude.”

Hooks avançados para automação com controle de versão

Workflows de Git e documentação são áreas em que hooks também ajudam bastante. Vamos ver algumas ideias.

Validador de branch Git

• Problema: Membros do time fazem push sem querer em branches protegidas

• Gatilhos: Antes de qualquer operação de escrita ou edição de arquivo

• Solução: Checar a branch atual do Git e bloquear operações em main/master/production

“Use um comando simples de bash git branch --show-current para obter o nome da branch atual e compare com uma lista de branches protegidas. Se estiver em uma branch protegida, saia com código 2 e envie ao Claude uma mensagem de erro explicando as políticas de proteção. Para regras de nomenclatura mais complexas, use a API do Claude para analisar nomes de branch e determinar se correspondem a padrões de proteção.”

Auto-commit inteligente

• Problema: Esquecer de fazer commit ou escrever mensagens ruins

• Gatilhos: Depois de qualquer modificação de arquivo

• Solução: Estagiar e fazer commit automaticamente com mensagens descritivas geradas por IA

“Leia os caminhos de arquivos modificados da entrada do hook, rode git diff para obter as mudanças e envie o diff para a API do Claude com um prompt pedindo uma mensagem de commit concisa. Use a mensagem gerada com git add e git commit para fazer commit automaticamente. Inclua nomes de arquivos e tipos de mudança no prompt da API para garantir mensagens no padrão conventional commits.”

Gerador de documentação

• Problema: Documentação de API fica fora de sincronia com mudanças no código

• Gatilhos: Depois de modificar arquivos de interface (controllers, models, APIs)

• Solução: Rodar automaticamente ferramentas de documentação como JSDoc, Sphinx ou geradores OpenAPI

“Cheque o caminho do arquivo modificado para determinar se é um endpoint de API, model ou arquivo de interface usando padrões. Envie o conteúdo do arquivo para a API do Claude pedindo para extrair mudanças de API e gerar atualizações de documentação. Rode a ferramenta de documentação adequada (jsdoc, sphinx-build etc.) e faça commit automaticamente da documentação atualizada.

Hooks avançados para colaboração e integração de fluxo

Por fim, hooks podem ajudar a manter todo o time atualizado.

Integração com Slack

• Problema: O time não fica ciente de mudanças importantes em bases de código compartilhadas

• Gatilhos: Quando notificações são enviadas para operações significativas

• Solução: Publicar mensagens formatadas em canais do time com nomes de arquivos e resumos de mudança

“Extraia informações de arquivos da entrada do hook e filtre por tipos importantes como código-fonte ou arquivos de configuração. Use a API do Claude para gerar um resumo claro do que mudou com base em nomes e tipos de arquivo. Envie a mensagem formatada ao Slack usando webhooks com menções a membros do time para mudanças críticas.”

Dispatcher de webhook

• Problema: Disparos manuais de pipeline CI/CD causando atrasos em deploy

• Gatilhos: Quando eventos específicos ocorrem (mudanças de config, arquivos de deploy modificados)

• Solução: Chamar APIs externas para disparar builds, deploys ou outros processos automatizados

“Confira o caminho modificado contra padrões como Dockerfile, package.json ou configs de deploy para decidir se o CI/CD deve disparar. Use a biblioteca requests no Python para chamar webhooks com headers de autenticação e payload com dados das mudanças. Inclua caminhos de arquivo e metadados no payload para que sistemas externos decidam o que construir ou implantar.”

Atualizador de status page

• Problema: Clientes sem saber de manutenções ou atividades de deploy

• Gatilhos: Quando arquivos de deploy ou infraestrutura são modificados

• Solução: Atualizar páginas de status de serviço com avisos de manutenção

“Faça parse da entrada do hook para mudanças em arquivos de infraestrutura como manifests do Kubernetes ou configs do Terraform usando padrões de caminho. Gere mensagens de manutenção usando a API do Claude com base no tipo de mudança detectada. Publique atualizações em serviços como StatusPage.io ou PagerDuty via REST APIs com tipos de incidente apropriados e duração estimada.”

Notificador de status do time

• Problema: Conflitos quando vários devs trabalham na mesma feature sem saber

• Gatilhos: Ao iniciar uma nova sessão no Claude Code

• Solução: Alertar canais do time de que você começou a trabalhar em um projeto ou componente específico

“Leia o diretório do projeto na entrada do hook e use a API do Claude para analisar arquivos recentes ou o histórico do git para entender o tipo de trabalho em andamento. Envie uma mensagem formatada aos canais de comunicação do time com seu nome, nome do projeto e área de foco. Inclua duração estimada e convide membros a coordenar se estiverem trabalhando em features relacionadas.”

Considerações finais

Claude Code Hooks transformam assistentes de codificação por IA, às vezes imprevisíveis, em fluxos de trabalho automatizados que rodam exatamente quando você precisa. Neste tutorial, você aprendeu a configurar hooks usando o comando interativo /hooks e configuração manual, a entender os dados de entrada em JSON que alimentam a automação inteligente e a controlar o comportamento do Claude por códigos de saída e outputs estruturados. 

Os padrões práticos que cobrimos incluem validadores de segurança que bloqueiam operações perigosas e notificações inteligentes que reduzem ruído. Esses exemplos mostram como hooks resolvem problemas reais de desenvolvimento enquanto dão controle total sobre seu assistente de IA. Agora que você domina os fundamentos, pode construir automações que combinem com as necessidades do seu fluxo de trabalho.

Para aprender mais sobre o uso de ferramentas de IA, confira na DataCamp o curso Understanding Prompt Engineering, que aborda estratégias de prompting diretamente relacionadas ao desenvolvimento de hooks. Para habilidades mais amplas de codificação com IA, experimente nosso curso Intermediate ChatGPT para desenvolver as competências que tornam assistentes de IA parceiros mais confiáveis no seu fluxo de desenvolvimento.