Ganchos Claude Code: Um guia prático para a automação do fluxo de trabalho

Ao trabalhar com Claude Code, você vai perceber um problema comum: Escreve um código legal, mas esquece passos importantes, tipo formatar, fazer testes ou seguir os protocolos de segurança. Você acaba repetindo os mesmos lembretes várias vezes. 

Os Claude Code Hooks permitem automatizar esses lembretes executando comandos shell automaticamente em pontos específicos do seu fluxo de trabalho.

Este tutorial mostra como configurar ganchos para formatação de código, execução de testes, notificações e proteção de arquivos. Você vai criar um sistema de automação que aplica seus padrões de desenvolvimento de forma consistente, sem precisar mexer manualmente.

Pra saber mais sobre o grande modelo de linguagem (LLM) que alimenta o Claude Code, dá uma olhada nesse artigo sobre o Claude Sonnet 4.5.

O que são ganchos de código Claude?

Os Claude Code Hooks são comandos shell que rolam automaticamente quando certas coisas acontecem durante sua sessão de programação de IA. Pense neles como gatilhos automáticos que executam seus scripts personalizados em momentos precisos—antes de Claude gravar um arquivo, depois de executar um comando ou quando ele te envia uma notificação.

O sistema funciona monitorando as ações do Claude Code e comparando-as com as regras que você define em um arquivo de configuração. Quando rola uma correspondência, o comando que você especificou é executado com acesso ao contexto sobre o que acabou de acontecer. Isso te dá controle sobre o comportamento do Claude e permite automatizar tarefas repetitivas que, de outra forma, precisariam de intervenção manual.

Aqui está um gancho básico que executa um formatador de código sempre que Claude escreve um arquivo Python:

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

Esse gancho tem três partes: 

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

• O comparador: Write (só quando estiver escrevendo arquivos)

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

O gancho recebe informações detalhadas sobre o que Claude acabou de fazer por meio de dados JSON enviados para a entrada do script, para que você possa criar uma automação mais sofisticada que responda a alterações específicas em arquivos.

Se você está interessado em automação além dos fluxos de trabalho de codificação, a Claude Cowork oferece automação semelhante assistida por IA para tarefas relacionadas a arquivos e documentos.

A seguir, vamos ver como criar esses ganchos do zero e registrá-los no Claude Code para adicioná-los aos seus fluxos de trabalho.

Pré-requisitos

Antes de mergulhar no Claude Code Hooks, você vai precisar configurar algumas coisas:

• Claude Code instalado e funcionando: Você deve se sentir à vontade para usar o Claude Code para tarefas básicas de codificação.

• Familiaridade com a linha de comando: Os ganchos executam comandos do shell, então você precisa saber como escrever comandos básicos do terminal para o seu sistema operacional.

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

• Diretório do projeto: Um projeto de codificação onde você pode testar hooks com segurança, sem afetar trabalhos importantes.

Você não precisa ser um especialista em scripts shell, mas entender como executar comandos como ls, cd e operações básicas de arquivo vai te ajudar a acompanhar os exemplos. Se você é novo em scripts bash ou no terminal, recomendo fazer nosso Introdução ao Shell .

Começando com Claude Code Hooks

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

Entendendo os eventos de gancho

O Claude Code oferece dez eventos diferentes onde você pode executar seus comandos. Cada evento é acionado em um momento específico, permitindo que você controle diferentes partes do seu fluxo de trabalho:

PreToolUse PostToolUse são os eventos mais comuns. O PreToolUse rola antes do Claude fazer alguma coisa, tipo gravar um arquivo ou rodar um comando, o que é ótimo pra validar ou bloquear operações perigosas. O PostToolUse rola depois que o Claude termina uma ação, o que é legal pra tarefas de limpeza, tipo formatar código ou rodar testes.

UserPromptSubmit é acionado quando você envia uma solicitação para o Claude, antes que ele processe sua solicitação. Você pode usar isso pra adicionar contexto à sua conversa ou pra validar se as solicitações atendem a certos requisitos.

Notification é executado quando o Claude te manda alertas, tipo pedir permissão pra rodar um comando ou quando precisa da sua ajuda. O PermissionRequest é acionado quando o Claude Code mostra uma caixa de diálogo de permissão, permitindo que você aprove ou recuse automaticamente a solicitação em nome do usuário.

Stop e um gatilho de SubagentStop quando o Claude terminar de responder, o que é útil para verificações finais ou geração de relatórios. A diferença entre os dois é que Stop é acionado quando Claude termina sua resposta geral, enquanto SubagentStop é acionado quando um auxiliar gerado pela ferramenta (um “subagente”) termina seu trabalho.

Os eventos restantes, PreCompact e SessionStart, lidam com situações especiais, como limpeza de conversas e inicialização de sessões.

Os eventos restantes, PreCompact, SessionStart e SessionEnd, lidam com situações específicas do ciclo de vida. PreCompact é executado logo antes de Claude encurtar o histórico de conversas. O “SessionStart” é acionado no início de uma nova sessão para definir os padrões, e o “ SessionEnd ” é acionado quando a sessão é encerrada, permitindo a limpeza ou o relatório final de recursos.

Entendendo os comparadores

Os matchers são os filtros que decidem quais ações do Claude Code ativam 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 os simples, como Write (disparado quando Claude grava um arquivo) ou Edit (disparado ao editar conteúdo), e combinações como Edit|Write para cobrir várias ações. 

Você também pode usar padrões de prefixo como Notebook.* para encontrar todas as ferramentas que começam com “Notebook”. Se você quiser que o gancho seja acionado em todas as ações, use a expressão regular universal .*, uma string vazia ("") ou deixe matcher em branco.

Como os comparadores diferenciam maiúsculas de minúsculas e só funcionam com nomes de ações, é melhor mantê-los o mais específicos possível. Quando você precisar de um controle mais preciso (por exemplo, limitar o gancho a determinados tipos de arquivo), você pode ler a carga JSON que o Claude passa para o gancho e aplicar sua própria expressão regular ou condições lá.

Criando seu primeiro hook no Claude Code

O Claude Code oferece duas maneiras de configurar hooks: através do comando interativo /hooks ou editando diretamente os arquivos de configuração. Vamos começar com a abordagem interativa, já que é mais fácil para quem está começando.

Usando o comando ` /hooks `:

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

2. Escolha o evento que vai ativar o processo (escolha “ PostToolUse ” neste exemplo)

3. Selecione “Adicionar novo gancho” no menu.

4. Defina seu padrão de correspondência (digite Write para direcionar a gravação do arquivo)

5. Digite seu comando:

• Mac: say "Task complete"

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

• Linux: spd-say "Task complete"

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

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

Se você preferir editar os arquivos de configuração diretamente, os hooks ficam em ~/.claude/settings.json para configurações globais ou .claude/settings.json dentro do diretório do seu projeto. 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, sempre que o Claude gravar um arquivo, você vai ouvir uma notificação de áudio.

Testando seu gancho

Antes de continuar, dá uma olhada se o seu gancho tá mesmo funcionando:

1. Peça ao Claude para escrever qualquer arquivo Python (por exemplo, “Crie um arquivo hello.py que imprima hello world”).

2. Você deve ouvir a notificação de áudio quando o Claude terminar a operação de gravação.

3. Se você não ouvir nada, dá uma olhada na transcrição do Claude Code apertando Ctrl-O pra ver se tem alguma mensagem de erro.

4. Problemas comuns incluem o comando hook não ser encontrado, permissões de arquivo erradas ou erros de sintaxe no seu arquivo de configuração.

Fazer esse teste básico funcionar te poupa tempo de depuração mais tarde, quando você estiver criando ganchos mais complexos. Se você acabou de editar o arquivo de configurações manualmente, alterou um comparador ou evento, ou instalou novas ferramentas que deseja usar em um comando hook, pode ser útil reabrir /hooks ou reiniciar o Claude para recarregar a configuração.

Esse padrão básico — evento, comparador, comando — é a base de toda a automação de ganchos. Você pode expandir isso adicionando vários comandos para serem executados ao mesmo tempo quando o mesmo evento for acionado. Por exemplo, você pode querer tocar um som e criar um backup quando o Claude gravar um arquivo. 

Você também pode criar comparadores separados para diferentes ferramentas dentro do mesmo evento, de modo que a gravação de arquivos acione ações diferentes da edição de código. Todos os ganchos que combinam com o mesmo padrão de ferramenta funcionam juntos. Se você configurar vários comparadores para o mesmo evento, cada gancho será executado quando seu comparador for acionado.

Trabalhando com entradas de gancho

Quando o Claude Code aciona um gancho, ele manda informações sobre o que acabou de acontecer pela entrada padrão (stdin), um fluxo de dados que vai direto pro seu comando quando ele é executado. Esses dados são o que tornam os hooks poderosos, em vez de apenas scripts aleatórios executados em momentos arbitrários. 

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

Anatomia das entradas de gancho

Cada 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: mostra a conversa atual

• transcript_path: mostra o histórico de conversas

• cwd: mostra o diretório de trabalho

• hook_event_name: informa qual evento foi disparado

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

Variações de entrada baseadas em eventos

Eventos de ferramentas como PreToolUse e PostToolUse têm mais detalhes sobre a ação, e é aí que os hooks são super úteis pra automação. Em PreToolUse, o tool_input é especificado, e o tool_response adicionalmente 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 gancho, file_path mostra o caminho do arquivo que está sendo escrito ou editado, enquanto content contém o texto exato que a ferramenta está prestes a escrever. Depois de rodar, a resposta da ferramenta mostra o nome final do arquivo ( filePath, repara no camelCase) pra confirmar qual arquivo foi realmente mexido, junto com um sinalizador success indicando se a operação foi concluída corretamente. 

Essas informações detalhadas significam que seus hooks podem reagir de forma diferente dependendo do que realmente aconteceu. Você pode formatar só arquivos Python, fazer backup só de diretórios importantes ou mandar notificações só quando certos tipos de arquivo forem modificados.

Eventos como UserPromptSubmit são mais simples, pois não envolvem ferramentas:

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

Observe que os hooks UserPromptSubmit não usam matchers na sua configuração. Eles são acionados em todos os prompts, não nas operações da ferramenta. Isso faz com que sejam perfeitos para registrar conversas, adicionar contexto ao projeto automaticamente ou validar prompts antes que o Claude os processe.

Lendo a entrada do gancho na prática

Vamos criar um gancho que registre cada solicitação do usuário. Isso resolve o problema de perder o controle do que você pediu para o Claude fazer, principalmente durante longas sessões de programação. Primeiro, a configuração do gancho:

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

Depois, 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 que o Claude Code manda e registra o prompt com o contexto da sessão. Isso cria um histórico pesquisável das suas interações, que se torna super útil quando você precisa lembrar como resolveu um problema semanas depois.

Trabalhando com saídas de gancho

Depois que seu comando hook for executado, ele precisa informar ao Claude Code o que aconteceu e se deve continuar normalmente. Esse mecanismo de controle é o que transforma os ganchos de simples ferramentas de registro em uma poderosa automação de fluxo de trabalho que pode guiar o comportamento do Claude. Isso rola 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

Saída padrão (stdout) significa saída normal. Por exemplo, se você imprimir algo, ele vai para stdout. Pra maioria dos ganchos, é isso que aparece na transcrição do Claude Code quando você aperta Ctrl-O, dando pra você um registro do que sua automação fez sem bagunçar a conversa principal.

Erro padrão (stderr) é quando aparece uma mensagem de erro. Você pode escrever para stderr usando 

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

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

A principal diferença é que um stderr pode ser enviado direto pro Claude pra ser processado automaticamente, deixando ele responder aos problemas que seus hooks detectam.

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

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

• Código de saída 2: Erro de bloqueio (envia um e-mail para stderr para Claude)

• Código de saída 3: Execução diferida (mostra que o comando foi concluído sem erros, mas seus efeitos são adiados até que condições adicionais sejam atendidas) 

• Outros códigos: Erro sem bloqueio (mostra stderr para o usuário, mas continua funcionando)

Esse sistema te dá um controle bem preciso sobre quando o Claude deve parar, continuar ou receber feedback sobre o que sua automação descobriu. Vamos dar uma olhada em exemplos dos dois códigos de saída mais importantes.

Código de saída 0: Funcionamento normal

A maioria dos ganchos usa o código de saída 0 pra indicar que tudo correu bem. Aqui está um gancho completo que registra as operações de arquivo e avisa 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')\""
          }
        ]
      }
    ]
  }
}

Esse gancho executa dois comandos: registra em um arquivo e, em seguida, imprime uma mensagem na transcrição. Tem várias maneiras de fazer isso, mas essa abordagem funciona em várias plataformas e evita depender de detalhes da linha de comando.

Como não tem um código de saída explícito, o padrão é 0. A mensagem impressa aparece na transcrição do Claude Code, mostrando que o registro funcionou. Esse padrão é perfeito pra criar trilhas de auditoria ou acompanhar as mudanças que o Claude faz no seu projeto com o tempo.

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

O código de saída 2 manda sua mensagem de erro direto pro Claude, deixando ele responder automaticamente. É aqui que os ganchos se tornam um mecanismo de segurança, em vez de apenas automação. Aqui está um gancho que bloqueia operações de arquivo perigosas:

{
  "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 gancho detecta um caminho perigoso, ele sai com o código 2. O Claude Code manda a mensagem stderr pro Claude, que pode te explicar por que a operação foi bloqueada e sugerir alternativas. Isso evita danos acidentais aos arquivos do sistema, mantendo Claude informado sobre suas políticas de segurança.

Criando um gancho de notificação inteligente para o Claude Code

Vamos criar nosso gancho de notificação melhorado, que combina o processamento de entrada com o tratamento inteligente de saída. Isso resolve o problema de ruído do nosso gancho original, que avisava sempre que um arquivo era alterado:

{
  "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)

Esse gancho lê a entrada para entender qual arquivo foi modificado, decide a importância da notificação com base no tipo de arquivo, usa stdout para registrar alterações importantes na transcrição, aciona diferentes alertas de áudio com base no tipo de arquivo e sempre sai com o código 0, já que essas são ações informativas, não bloqueadoras.

A combinação de análise de entrada e controle de saída cria um gancho que se comporta de forma inteligente com base no contexto, ao mesmo tempo em que fornece o nível certo de feedback para você e para o Claude Code. Em vez de receber notificações irritantes para cada arquivo temporário, você só fica sabendo das mudanças que realmente importam para o seu projeto.

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

Padrões avançados para ganchos de código Claude

Além das notificações e registros básicos, os hooks podem resolver problemas reais do fluxo de trabalho de desenvolvimento que as equipes enfrentam diariamente. Aqui estão algumas ideias que você pode adaptar para seus próprios projetos.

O legal é que você não precisa criar esses ganchos manualmente. Você pode simplesmente dar ao Claude Code uma das ideias sugeridas abaixo, junto com a referência Hooks na documentação dele, e ele vai gerar o código e o JSON relevantes para a configuração.

Cada um desses padrões pode ser personalizado para suas ferramentas e fluxo de trabalho específicos. Comece com aqueles que resolvem suas maiores frustrações diárias e, depois, vá expandindo sua automação conforme você se sentir mais à vontade com o desenvolvimento de ganchos.

Ganchos avançados para segurança e conformidade

Scanner de chaves API

• Problema: Colocando segredos no controle de versão sem querer

• Gatilhos: Antes de gravar qualquer arquivo

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

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

Manda só trechos mascarados (por exemplo, mantém 4 caracteres prefixo/sufixo) ou hashes para a API da Anthropic pra analisar strings suspeitas e ver se são segredos de verdade ou só nomes de variáveis. Saia com o código 2 e dê um feedback pro Claude sobre os segredos que foram detectados e alternativas mais seguras.

Executor de cabeçalho de licença

• Problem: Projetos de código aberto sem os cabeçalhos de licença necessários nos novos arquivos

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

• Solução: Confirmando que os novos arquivos .py, .js e .java têm o texto da licença certo.

Analise a entrada do gancho para pegar o conteúdo do arquivo e veja se as primeiras 10 linhas têm o texto da licença usando a correspondência de strings. Para uma validação mais detalhada, manda o cabeçalho do arquivo para o Claude pela API da Anthropic pra conferir se tem os avisos de direitos autorais e as informações de licença certinhas. Bloqueie a criação do arquivo com o código de saída 2 se os cabeçalhos estiverem faltando e forneça ao Claude o modelo de licença correto para adicionar.

Proteção de arquivos de produção

• Problema: Modificar sem querer arquivos importantes de configuração do sistema

• Gatilhos: Antes de editar arquivos em diretórios confidenciais

• Solução: Bloqueando alterações em /etc/, nginx.conf, database.yml e outras configurações importantes.

Pega o caminho do arquivo do JSON de entrada do hook e vê se ele combina com padrões como /etc/, production.yml ou outros nomes de arquivos importantes. Use a API do Claude para analisar o caminho do arquivo e ver se é um arquivo de configuração que pode afetar os sistemas de produção. Saia com o código 2 e dê orientações específicas sobre práticas de desenvolvimento mais seguras quando caminhos perigosos forem detectados.

Otimizador de imagens

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

• Gatilhos: Depois de adicionar novos arquivos de imagem

• Solução: Comprimindo arquivos PNG/JPEG sem perder a qualidade visual

Analise a entrada do gancho para pegar o caminho do arquivo e veja se é um arquivo de imagem usando a correspondência de extensão. Use ferramentas de compactação como imageoptim ou chame a API TinyPNG para compactar a imagem sem perder a qualidade. Registre os resultados da compactação em stdout para que você possa ver a redução no tamanho do arquivo na transcrição do Claude.

Ganchos avançados para automação do controle de versão

Validador de ramificação Git

• Problema: Membros da equipe acidentalmente enviando alterações para branches protegidos

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

• Solução: Verificando o branch Git atual e bloqueando operações em main/master/production

Use um comando bash simples git branch --show-current para pegar o nome do branch atual e comparar com uma lista de branches protegidos. Se estiver em um branch protegido, saia com o código 2 e mande uma mensagem de erro pro Claude explicando as políticas de proteção do branch. Para regras complexas de nomenclatura de ramificações, use a API do Claude para analisar os nomes das ramificações e ver se eles se encaixam nos padrões de proteção.

Auto-confirmação inteligente

• Problema: Esquecer de fazer o commit das alterações ou escrever mensagens de commit ruins

• Gatilhos: Depois de qualquer alteração no arquivo

• Solução: Preparando e confirmando alterações automaticamente com mensagens descritivas geradas por IA

Leia os caminhos dos arquivos modificados da entrada do hook, execute o comando ` git diff ` para pegar as alterações e mande o diff para a API do Claude com um aviso pedindo uma mensagem de commit curtinha. Use a mensagem gerada com os comandos ` git add ` e ` git commit ` para confirmar automaticamente as alterações. Inclua nomes de arquivos e tipos de alteração no prompt da API para garantir que as mensagens de commit sigam os padrões convencionais de commit.

Gerador de documentação

• Problema: A documentação da API está ficando fora de sincronia com as alterações no código

• Gatilhos: Depois de mexer nos arquivos de interface (controladores, modelos, APIs)

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

Dá uma olhada no caminho do arquivo modificado pra ver se é um endpoint de API, modelo ou arquivo de interface usando a correspondência de padrões. Manda o conteúdo do arquivo para a API do Claude, pedindo pra extrair as alterações da API e gerar atualizações da documentação. Execute a ferramenta de geração de documentação apropriada (jsdoc, sphinx-build, etc.) e envie a documentação atualizada automaticamente.

Ganchos avançados para colaboração e integração do fluxo de trabalho

Integração com o Slack

• Problema: A equipe não está a par de mudanças importantes nas bases de código compartilhadas.

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

• Solução: Publicar mensagens formatadas nos canais da equipe com nomes de arquivos e resumos das alterações

Extraia informações do arquivo da entrada do gancho e filtre tipos de arquivos importantes, como código-fonte ou arquivos de configuração. Use a API do Claude para criar um resumo fácil de entender sobre o que mudou com base nos nomes e tipos de arquivos. Manda a mensagem formatada pro Slack usando URLs de webhook com menções aos membros da equipe pra mudanças importantes.

Distribuidor de webhooks

• Problema: Gatilhos manuais do pipeline de CI/CD causando atrasos na implantação

• Gatilhos: Quando acontecem coisas específicas (mudanças de configuração, arquivos de implantação modificados)

• Solução: Chamando APIs externas para acionar compilações, implantações ou outros processos automatizados

Dá uma olhada no caminho do arquivo modificado em relação a padrões como Dockerfile, package.json ou configurações de implantação para ver se o CI/CD deve ser acionado. Use a biblioteca de solicitações do Python para chamar URLs de webhook com cabeçalhos de autenticação e dados de carga útil sobre as alterações. Inclua caminhos de arquivos e altere metadados na carga útil do webhook para que sistemas externos possam tomar decisões inteligentes sobre o que construir ou implantar.

Atualizador da página de status

• Problem: Os clientes não sabem das atividades de manutenção ou implantação

• Gatilhos: Quando os arquivos de implantação ou infraestrutura são modificados

• Solução: Atualiza as páginas de status do serviço com avisos de manutenção.

Analise a entrada do gancho para alterações no arquivo de infraestrutura, como manifestos do Kubernetes ou configurações do Terraform, usando padrões de caminho de arquivo. Crie mensagens de manutenção usando a API do Claude com base no tipo de mudanças detectadas na infraestrutura. Publique atualizações de status em serviços como StatusPage.io ou PagerDuty usando suas APIs REST com os tipos de incidentes apropriados e a duração estimada.

Notificador de status da equipe

• Problema: Conflitos quando vários desenvolvedores trabalham nas mesmas funcionalidades sem saber

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

• Solução: Avise os canais da equipe que você está começando a trabalhar em um projeto ou componente específico.

Dá uma olhada no diretório do projeto a partir da entrada do hook e usa a API do Claude pra analisar os arquivos recentes ou o histórico do git pra entender que tipo de trabalho tá sendo feito. Manda uma mensagem formatada pros canais de comunicação da equipe com seu nome, nome do projeto e área de foco. Inclua a duração estimada do trabalho e convide os membros da equipe para se coordenarem se estiverem trabalhando em recursos relacionados.

Conclusão

Os Claude Code Hooks transformam assistentes de codificação de IA imprevisíveis em fluxos de trabalho automatizados que funcionam exatamente quando você precisa deles. Neste tutorial, você aprendeu a configurar hooks usando o comando interativo /hooks e a configuração manual, entendeu os dados de entrada JSON que alimentam a automação inteligente e controlou o comportamento do Claude por meio de códigos de saída e saídas estruturadas. 

Os padrões práticos que abordamos incluem validadores de segurança que bloqueiam operações perigosas e notificações inteligentes que reduzem o ruído. Esses exemplos mostram como os hooks resolvem problemas reais de desenvolvimento, ao mesmo tempo que te dão controle total sobre o seu assistente de IA. Agora que você entende o básico, pode criar uma automação que atenda às necessidades específicas do fluxo de trabalho da sua equipe. 

Pra saber mais sobre como usar ferramentas de IA, dá uma olhada no curso de DataCamp Entendendo a Engenharia de Prompts, que fala sobre estratégias de prompt que funcionam direto com o desenvolvimento de hooks. Para habilidades mais amplas em codificação de IA, experimente nosso curso intermediário do chatGPT para desenvolver as habilidades que tornam os assistentes de IA parceiros mais confiáveis no seu fluxo de trabalho de desenvolvimento.