Claude Code Hooks — Automatize Seu Fluxo de Trabalho

Você já se pegou repetindo as mesmas tarefas toda vez que o Claude Code executa uma ação? Rodar o linter depois de cada edição, formatar arquivos antes de um commit, validar dependências após instalar pacotes. Essas micro-tarefas consomem tempo e, pior, são fáceis de esquecer. Os hooks do Claude Code existem exatamente para eliminar esse atrito — são gatilhos que disparam comandos automaticamente antes ou depois de ações específicas, transformando seu fluxo de trabalho em algo previsível e consistente.

Se você já domina os comandos essenciais e tem o ambiente configurado, os hooks representam o próximo nível de produtividade. Eles conectam etapas do seu processo de desenvolvimento sem que você precise intervir manualmente em cada uma.

O que são hooks no Claude Code e como funcionam

Hooks são comandos shell que o Claude Code executa automaticamente em momentos específicos do seu ciclo de operação. Pense neles como “interceptadores” — eles ficam observando determinados eventos e, quando esses eventos acontecem, disparam scripts ou comandos que você definiu previamente.

O conceito não é novo na programação. Se você já usou Git hooks (como pre-commit ou post-merge), a lógica é idêntica. A diferença é que os claude code hooks operam dentro do contexto da ferramenta de IA, reagindo a ações como:

• Edição de arquivos pelo Claude
• Execução de comandos no terminal
• Início ou fim de uma sessão de conversa
• Criação de novos arquivos no projeto

Cada hook recebe informações sobre o evento que o disparou — como o nome do arquivo editado ou o comando que foi executado — e pode usar essas informações para decidir o que fazer.

A mecânica por trás dos hooks

Quando o Claude Code processa uma instrução sua, ele segue um pipeline interno. Os hooks se encaixam nesse pipeline em pontos de entrada e saída:

1. Você envia um prompt ao Claude Code
2. O Claude interpreta e decide a ação (editar arquivo, rodar comando etc.)
3. Pre-hook é executado antes da ação
4. A ação principal acontece
5. Post-hook é executado depois da ação

Se um pre-hook retornar um erro (código de saída diferente de zero), a ação principal pode ser bloqueada. Isso permite criar validações que impedem operações indesejadas antes que elas aconteçam.

Tipos de hooks disponíveis e quando usar cada um

O sistema de hooks do Claude Code organiza os gatilhos por tipo de evento. Conhecer cada um permite montar automações precisas sem disparar ações desnecessárias.

Quando usar pre-hooks

Pre-hooks são ideais para prevenção e preparação. Exemplos concretos:

• Verificar se um arquivo está protegido contra edição antes que o Claude o modifique
• Garantir que o ambiente tem as dependências necessárias antes de rodar um comando
• Criar um snapshot do estado atual para possibilitar rollback

Quando usar post-hooks

Post-hooks funcionam melhor para validação e complemento. São os mais usados na prática:

• Rodar eslint --fix automaticamente após cada edição de arquivo JavaScript
• Executar prettier para manter a formatação consistente
• Disparar testes relacionados ao arquivo que foi modificado
• Atualizar documentação ou changelogs

Como configurar hooks no arquivo de projeto

A configuração de hooks acontece no arquivo .claude/settings.json do seu projeto. Se a pasta .claude não existir, crie-a na raiz do repositório.

A estrutura básica do arquivo com hooks é:

{
  "hooks": {
    "PostEditFile": [
      {
        "command": "npx eslint --fix {{filepath}}",
        "pattern": "*.js"
      }
    ],
    "PreCommand": [
      {
        "command": "echo 'Executando: {{input}}'"
      }
    ]
  }
}

Anatomia de uma definição de hook

Cada hook aceita os seguintes campos:

• command: O comando shell a ser executado. Suporta variáveis de template como {{filepath}}, {{input}} e {{output}}.
• pattern (opcional): Um glob pattern que filtra em quais arquivos o hook se aplica. Se omitido, o hook roda para qualquer arquivo.
• timeout (opcional): Tempo máximo de execução em milissegundos. Evita que hooks travados bloqueiem o fluxo.
• stop_on_error (opcional): Se true, interrompe a ação principal caso o hook falhe.

Variáveis de template disponíveis

Exemplos práticos de hooks para automação

Teoria sem prática não muda fluxo de trabalho. Aqui estão configurações reais que você pode adaptar ao seu projeto.

Exemplo 1: Linting e formatação automática após edição

{
  "hooks": {
    "PostEditFile": [
      {
        "command": "npx eslint --fix {{filepath}}",
        "pattern": "*.{js,ts,jsx,tsx}",
        "timeout": 10000
      },
      {
        "command": "npx prettier --write {{filepath}}",
        "pattern": "*.{js,ts,jsx,tsx,css,json,md}",
        "timeout": 5000
      }
    ]
  }
}

Com essa configuração, toda vez que o Claude Code editar um arquivo JavaScript ou TypeScript, o ESLint corrige problemas automaticamente e o Prettier padroniza a formatação. Você nunca mais precisa lembrar de rodar esses comandos.

Exemplo 2: Testes automáticos por arquivo modificado

{
  "hooks": {
    "PostEditFile": [
      {
        "command": "npx jest --findRelatedTests {{filepath}} --passWithNoTests",
        "pattern": "src/**/*.{js,ts}",
        "timeout": 30000
      }
    ]
  }
}

Esse hook roda apenas os testes relacionados ao arquivo que foi editado, não a suíte inteira. O flag --passWithNoTests evita erros quando o arquivo não tem testes associados.

Exemplo 3: Validação de segurança antes de comandos

{
  "hooks": {
    "PreCommand": [
      {
        "command": ".claude/scripts/validate-command.sh '{{input}}'",
        "stop_on_error": true
      }
    ]
  }
}

O script validate-command.sh pode verificar se o comando que está prestes a ser executado contém operações perigosas — como rm -rf /, acesso a diretórios fora do projeto ou instalação de pacotes não autorizados.

Exemplo 4: Commit automático ao final da sessão

{
  "hooks": {
    "PostSession": [
      {
        "command": "git add -A && git commit -m 'claude: auto-commit session changes' --no-verify || true"
      }
    ]
  }
}

O || true no final garante que o hook não falhe caso não haja alterações para commitar. Útil para manter um histórico granular de tudo que o Claude modificou.

Combinando hooks com skills para fluxos completos

Hooks isolados já são poderosos, mas o verdadeiro potencial aparece quando você os combina com o sistema de skills (instruções persistentes) do Claude Code. Enquanto hooks automatizam ações técnicas, skills orientam o comportamento da IA.

Um fluxo completo pode funcionar assim:

1. Skill instrui o Claude a sempre criar testes ao adicionar novas funções
2. PostEditFile hook roda os testes automaticamente após cada edição
3. PostEditFile hook aplica formatação com Prettier
4. PostSession hook faz commit das alterações

Para configurar uma skill, crie um arquivo .claude/skills/testing.md:

# Regra de Testes

Sempre que criar ou modificar uma função em src/, crie ou atualize
o arquivo de teste correspondente em tests/ seguindo o padrão:
- Arquivo: tests/[nome-do-arquivo].test.ts
- Cobertura mínima: casos de sucesso e erro

Com a skill definindo o que o Claude deve fazer e os hooks garantindo o que acontece depois, você cria um pipeline de desenvolvimento que mantém qualidade sem intervenção manual.

Ordem de execução quando múltiplos hooks existem

Quando você define vários hooks para o mesmo evento, eles são executados na ordem em que aparecem no array. Se um hook com stop_on_error: true falhar, os hooks seguintes do mesmo evento não são executados.

PostEditFile[0] → PostEditFile[1] → PostEditFile[2]
     ✓                  ✗ (stop_on_error)    ⊘ (não executa)

Planeje a ordem estrategicamente: coloque validações críticas primeiro e ações complementares depois.

Boas práticas para hooks em projetos reais

Depois de configurar seus primeiros hooks, algumas práticas vão evitar dores de cabeça conforme o projeto cresce:

Versione a pasta .claude no repositório. Hooks e skills fazem parte da infraestrutura do projeto. Quando um novo membro da equipe clona o repositório, ele herda todas as automações.

Mantenha hooks rápidos. A regra prática é que nenhum hook individual deveria levar mais de 10 segundos. Se uma validação é demorada, considere rodá-la apenas no PostSession em vez de a cada edição de arquivo.

Use logs para depuração. Adicione um hook de logging simples durante o desenvolvimento:

{
  "command": "echo '[HOOK] PostEditFile: {{filepath}}' >> .claude/hook.log"
}

Teste hooks isoladamente antes de integrá-los. Execute o comando do hook manualmente no terminal com um arquivo real para confirmar que funciona antes de adicioná-lo à configuração.

Documente hooks não óbvios. Se um hook faz algo além do trivial, adicione um comentário no script explicando o motivo. Seu eu do futuro agradece.

Quando hooks não são a melhor escolha

Nem toda automação precisa ser um hook. Existem situações onde outras abordagens funcionam melhor:

• Tarefas que dependem de contexto da conversa: Hooks não têm acesso ao histórico de mensagens. Use skills para isso.
• Processos que precisam de aprovação humana: Hooks rodam automaticamente. Se a ação exige revisão, é melhor usar comandos manuais.
• Operações destrutivas: Deletar arquivos, resetar banco de dados ou fazer deploy. Essas ações devem ser explícitas, não automáticas.

A automação com claude code hooks funciona melhor para tarefas repetitivas, previsíveis e de baixo risco — exatamente o tipo de trabalho que consome tempo sem agregar valor criativo.

Artigos relacionados

• Claude Code – Guia Completo para Criar Projetos com IA
• Como Instalar e Configurar o Claude Code do Zero
• Comandos Essenciais do Claude Code para Produtividade
• Hooks no Claude Code para Linting e Formatação
• Hooks do Claude Code para Validação e Segurança

Bruno Bracaioli

Empreendedor e Desenvolvedor

Bruno Bracaioli é especialista em arquitetura de software, ciência de dados e cybersecurity. Além disso, investe em criptomoedas e em investimentos tradicionais como CDBs, Ações, Tesouro e outros. É influenciador digital no instagram (@brunobracaioli) e no Youtube (/brunobracaioli). Contato por: bruno@bracaiolitech.com ou pelo bruno@b2tech.com