Skip to main content
Todos os guias
Conteúdo do guia

Conteúdo do guia

Tempo de leitura: 12 min
#automation#hooks#claude#code#guide#beginners
Iniciante12 min

Hooks no Claude Code para iniciantes: automatizando ações repetitivas

Guia prático completo sobre a configuração de Hooks no Claude Code: linting automático, formatação, verificações de segurança antes do commit, notificações e automação headless.

Publicado:
PARA AGENTE DE IAChatGPTClaude

1. O que são Hooks no Claude Code e por que eles são necessários

Ao trabalhar com um assistente de IA no terminal, os desenvolvedores frequentemente se veem repetindo as mesmas rotinas: "agora execute o ESLint", "formate o código com Prettier", "verifique os tipos antes do commit". Mesmo que essas regras sejam definidas nas instruções do sistema CLAUDE.md, o modelo de linguagem pode ocasionalmente esquecer de executá-las ou ignorá-las para economizar tokens.

Hooks no Claude Code resolvem esse problema radicalmente: são gatilhos determinísticos que chamam automaticamente comandos do sistema ou scripts em momentos precisos do ciclo de vida da operação do assistente.

A lógica dos hooks é simples:

Se o Claude executou o evento X → o sistema operacional garante a execução da ação Y.

mermaid
flowchart LR subgraph Текстова_інструкція["CLAUDE.md (Ймовірнісна)"] A["Промпт: 'Завжди запускай лінтер'"] --> B{"Модель пам'ятає?"} B -->|Іноді| C["Запуск перевірки"] B -->|Пропустила| D["Помилки накопичуються"] end subgraph Нативний_Hook["Hooks у settings.json (Детермінована)"] E["Подія: Редагування файлу"] --> F["Автоматичний тригер ОС"] F --> G["Гарантоване виконання npx eslint"] end

Comparação das abordagens de automação

CaracterísticaPrompts manuaisInstruções no CLAUDE.mdHooks nativos
Confiabilidade de execuçãoBaixa (depende da memória humana)Média (comportamento probabilístico do LLM)100% (interceptação determinística de eventos)
Consumo de tokensAlto (tokens gastos a cada solicitação)Médio (a regra é carregada em cada contexto)Zero (executado localmente no shell)
Velocidade de respostaLenta (entrada manual de comandos)Requer uma rodada adicional de geraçãoInstantânea (chamada nativa de processo)
Capacidade de bloqueioInexistenteInexistenteSim (exit code não-zero interrompe a ação)
Nota

Os Hooks do Claude Code são configurados em formato JSON no arquivo .claude/settings.json no nível do repositório individual ou globalmente em ~/.claude/settings.json.

2. Ciclo de vida de eventos: PreToolUse, PostToolUse, Notification, Stop

O Claude Code oferece quatro pontos fundamentais de interceptação (eventos) aos quais você pode vincular comandos automatizados.

mermaid
sequenceDiagram autonumber actor Dev as Розробник participant Agent as Claude Code participant Hook as Система Hooks participant Tool as Інструмент (Bash/Edit/Write) Dev->>Agent: Запит на модифікацію коду Agent->>Hook: Спроба виклику інструмента Note over Hook: PreToolUse Hook Hook-->>Agent: Перевірка пройдена (Exit Code 0) Agent->>Tool: Виконання операції Tool-->>Agent: Результат успішний Agent->>Hook: Подія завершення операції Note over Hook: PostToolUse Hook Hook-->>Agent: Результат лінтингу / форматування Agent->>Hook: Завершення відповіді моделі Note over Hook: Stop Hook (Сповіщення) Agent-->>Dev: Фінальна відповідь

Principais pontos de disparo

  1. PreToolUse (Antes do uso da ferramenta): dispara antes que o agente execute uma ação. Se o comando do hook retornar um erro (exit code diferente de 0), a execução da ação é bloqueada. Este é o lugar ideal para verificações de segurança antes de commits ou pushes.
  2. PostToolUse (Após o uso da ferramenta): dispara imediatamente após a execução bem-sucedida da ferramenta. É o gatilho mais popular para formatação automática de código (Prettier) ou linting do arquivo modificado (ESLint).
  3. Notification (Notificação): ativa-se quando o assistente precisa enviar uma mensagem importante do sistema ou solicitar autorização adicional.
  4. Stop (Fim da resposta): dispara no momento em que o Claude Code termina completamente a geração da resposta e aguarda a próxima mensagem do usuário. Usado para reproduzir sinais sonoros e notificações desktop.
Pontos de disparo dos Hooks no ciclo de vida ЗбільшитиPontos de disparo dos Hooks no ciclo de vidaPontos de disparo dos Hooks no ciclo de vida

3. Estrutura de configuração no settings.json e sintaxe do Matcher

A configuração dos hooks é armazenada no arquivo .claude/settings.json. Se este arquivo ainda não existir na raiz do seu projeto, crie-o.

Sintaxe básica de configuração

json
{ "hooks": { "PreToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "echo 'Починається редагування файлу...'" } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash-команда завершена успішно'" } ] } ] } }

Como funciona o campo Matcher

O campo matcher define a qual ferramenta específica do agente o hook deve reagir:

  • "Edit" — intercepta a modificação de arquivos já existentes.
  • "Write" — dispara ao criar um novo arquivo ou sobrescrevê-lo totalmente.
  • "Bash" — reage à execução de qualquer comando de console.
  • "Bash(git commit*)" — template preciso que filtra chamadas Bash iniciadas pelo comando git commit.
  • "*" — seletor universal (wildcard), que dispara para qualquer ferramenta do agente.
Dica

Os templates matcher são sensíveis a maiúsculas/minúsculas. Use os nomes padrão das ferramentas do Claude Code: Edit, Write, Bash, Glob, Grep.

4. Linting e formatação automáticos (ESLint + Prettier)

O cenário diário mais prático é delegar a formatação e a verificação primária de estilo às utilitários Prettier e ESLint. Isso garante que o código seja sempre salvo no repositório em estado perfeito.

Configuração do PostToolUse para ESLint e Prettier

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

Análise das flags de segurança no comando

  • "$CLAUDE_FILE_PATH" — variável de ambiente dinâmica onde o Claude insere automaticamente o caminho completo do arquivo recém-modificado pelo agente.
  • 2>/dev/null — suprime a saída excessiva de erros do fluxo stderr para não sobrecarregar o terminal.
  • || true — construção bash crucial. Garante que, mesmo se o linter encontrar erros irreparáveis e retornar código 1, o hook termine com código 0 e não pare o trabalho subsequente do agente.
mermaid
flowchart TD A["Claude викликає Edit"] --> B["Файл збережено на диску"] B --> C["PostToolUse тригер"] C --> D["npx eslint --fix $CLAUDE_FILE_PATH"] D --> E{"Успішно або || true"} E --> F["Агент продовжує вирішувати задачу"]

5. Barreiras de proteção antes do git commit (TypeCheck + Testes)

Se usamos hooks "suaves" com || true para formatação, para fixar mudanças no controle de versão é necessário um controle rigoroso de qualidade (Quality Gate).

Usando PreToolUse, você pode bloquear a criação de um commit se houver erros de compilação TypeScript ou falhas nos testes unitários no projeto.

Configuração do hook Pre-commit bloqueador

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm run lint" } ] } ] } }

O que acontece quando erros são detectados

  1. O Claude formula o comando git commit -m "...".
  2. Antes de sua execução, o sistema ativa o PreToolUse.
  3. Os comandos de validação são executados: npm run typecheck e npm run lint.
  4. Se um erro for encontrado: o processo retorna um código de saída não-zero (exit code 1).
  5. O Claude Code intercepta a saída do erro do compilador diretamente em seu contexto.
  6. Em vez de um commit quebrado, o assistente analisa o texto do erro, corrige automaticamente os tipos no código e faz uma nova tentativa limpa de commit.
Importante

Atenção: nas verificações bloqueadoras de PreToolUse, nunca use || true, caso contrário, a verificação será sempre considerada bem-sucedida e a barreira de proteção deixará de funcionar.

6. Notificações de áudio e desktop ao concluir tarefas (Stop Hook)

Refatorações complexas ou a execução de suítes completas de testes podem levar de 2 a 10 minutos. Em vez de ficar olhando fixamente para o terminal, configure notificações através do evento Stop.

Dica

A notificação dispara apenas quando o agente conclui completamente a geração da resposta final, e não entre chamadas intermediárias de ferramentas.

7. Passagem de contexto através de variáveis de ambiente

Para que os scripts de automação sejam flexíveis e adaptativos, o Claude Code exporta automaticamente metadados da operação atual para variáveis de ambiente do sistema (Environment Variables).

Variáveis de ambiente do Claude Code para hooks ЗбільшитиVariáveis de ambiente do Claude Code para hooksVariáveis de ambiente do Claude Code para hooks

Referência das variáveis de sistema do Claude Code

Variável de ambienteTipo de valorDescrição e exemplo de conteúdo
$CLAUDE_FILE_PATHCaminho absolutoCaminho para o arquivo específico sendo criado ou editado (/Users/dev/project/src/index.ts)
$CLAUDE_TOOL_NAMEIdentificador textualNome da ferramenta que iniciou o evento (Edit, Write, Bash)
$CLAUDE_PROJECT_DIRCaminho absolutoDiretório raiz do projeto onde a sessão atual do Claude Code está rodando

Exemplo de script Bash contextual para um hook

Crie o script .claude/hooks/smart-validator.sh:

bash
#!/usr/bin/env bash set -e # Перевіряємо, чи існує файл і яке у нього розширення if [[ -f "$CLAUDE_FILE_PATH" ]]; then case "$CLAUDE_FILE_PATH" in *.ts|*.tsx) echo "⚡ Валідація TypeScript файлу: $CLAUDE_FILE_PATH" npx eslint --fix "$CLAUDE_FILE_PATH" || true ;; *.json) echo "🔍 Перевірка валідності JSON..." jq empty "$CLAUDE_FILE_PATH" 2>/dev/null || echo "Помилка формату JSON!" ;; *.md) echo "📝 Оновлено документацію: $(basename "$CLAUDE_FILE_PATH")" ;; esac fi

Agora, no .claude/settings.json, basta indicar a chamada deste script:

json
{ "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash .claude/hooks/smart-validator.sh" } ] } ] } }

8. Padrão «CI-in-a-Loop»: feedback contínuo

No desenvolvimento tradicional sem hooks, surge um padrão de ruptura: o agente altera dezenas de arquivos, depois inicia-se uma build do projeto que gera uma avalanche de 40 erros de tipo. É difícil para o agente descobrir qual alteração específica causou a quebra.

CI-in-a-Loop (Curto ciclo de feedback) inverte esse processo:

mermaid
flowchart TD A["Claude вносить правку в код"] --> B["Миттєвий запуск tsc"] B --> C{"Є помилка?"} C -->|Так| D["Claude бачить 1 точкову помилку"] D --> E["Миттєвий фікс за 5 секунд"] E --> B C -->|Ні| F["Перехід до наступного рядка/файлу"]

Configuração da auditoria cíclica de TypeScript

json
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -n 20 || true" } ] } ] } }

Por que usar obrigatoriamente head -n 20

Se a saída do compilador retornar centenas de linhas de log, elas entram no contexto do modelo e podem estourar o limite de tokens. Limitar via head -n 20 mostra os primeiros erros mais críticos, dando ao modelo um guia preciso para correção imediata sem sobrecarregar a sessão.

9. Automação Headless: modo -p, Cron e Git Hooks

Os hooks podem ser combinados com o modo autônomo (headless) do Claude Code — a flag -p (print/prompt). Isso permite automatizar a execução de tarefas totalmente sem intervenção humana.

mermaid
flowchart LR A["Розклад Cron (02:00)"] --> B["Скрипт nightly-audit.sh"] B --> C["claude -p 'Run test suite, fix bugs, commit'"] C --> D["Хуки PostToolUse контролюють код"] D --> E["Автоматичний Push результату"]

Script autônomo de auditoria noturna (nightly-audit.sh)

bash
#!/usr/bin/env bash cd /var/www/my-project # Запуск Claude Code в автономному режимі з фіксованим завданням claude -p "Run full test suite. If any tests fail, inspect the stack trace and fix them. Ensure typecheck passes. Finally, commit all fixes with a conventional commit." >> /var/log/claude-audit.log 2>&1

Configuração do agendamento via Cron

Abra o planejador de tarefas (crontab -e) e configure a execução toda noite às 03:00:

text
0 3 * * * /usr/local/bin/nightly-audit.sh

Execução da verificação em um Git Hook nativo (.git/hooks/post-merge)

Para que, após cada atualização via git pull, seja iniciado automaticamente uma análise de compatibilidade:

bash
#!/usr/bin/env bash # .git/hooks/post-merge echo "🚀 Запуск автоматичної перевірки залежностей через Claude..." claude -p "Check if package.json was updated. If so, run npm install, verify build, and report summary."

Não esqueça de dar permissão de execução ao script: chmod +x .git/hooks/post-merge.

10. Melhores práticas de engenharia e regras de segurança para Hooks

Hooks mal configurados podem causar loops infinitos ou travar o terminal. Siga estas quatro regras fundamentais de higiene de engenharia.

Quatro regras para design seguro de hooks

  1. Desempenho extremo: Hooks com evento PostToolUse rodam após cada modificação de arquivo. Se o hook demorar mais de 1-2 segundos, o trabalho interativo com o Claude ficará lento e desconfortável. Execute testes E2E pesados apenas em PreToolUse antes do commit, mas não após cada Edit.

  2. Logging obrigatório da saída: Sempre redirecione a saída de scripts de diagnóstico para um arquivo de log temporário:

    bash
    "command": "bash .claude/hooks/check.sh >> /tmp/claude-hooks.log 2>&1 || true"

    Se o hook parar de disparar, você poderá abrir imediatamente /tmp/claude-hooks.log e encontrar a causa.

  3. Teste isolado em terminal limpo: Antes de adicionar qualquer comando ao settings.json, execute-o manualmente em um shell comum. Se o comando gerar erro no console, ele garantidamente quebrará a sessão do Claude Code.

  4. Prevenção de recursão infinita: Nunca configure um comando em PostToolUse que modifique os arquivos do projeto por si só sem flags de ignorância (por exemplo, um script externo que chama outro Edit), caso contrário, o agente entrará em um loop infinito de chamadas.

Aviso

Não execute comandos via hooks que esperem entrada interativa do usuário (como confirmações read -p ou sudo pedindo senha). Isso resultará no travamento do processo do terminal.

11. Workshop prático, cheat sheet e checklist final

Para começar rapidamente em seu próprio projeto, use esta referência consolidada pronta e uma configuração production testada.

Cheat sheet para escolher o tipo de Hook para automação ЗбільшитиCheat sheet para escolher o tipo de Hook para automaçãoCheat sheet para escolher o tipo de Hook para automação

Arquivo de configuração pronto .claude/settings.json

Copie esta configuração de referência para a pasta .claude do seu projeto:

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm test" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Роботу завершено!\" with title \"Claude Code\"' 2>/dev/null || true" } ] } ] } }

Autoavaliação rápida

Dica

1. Qual a diferença fundamental entre PreToolUse e PostToolUse?

Resposta: PreToolUse roda antes da execução da ação da ferramenta e pode bloqueá-la com exit code não-zero. PostToolUse roda após a conclusão bem-sucedida da operação e é usado para formatação ou linting.

Dica

2. Por que adicionar || true nos hooks de formatação?

Resposta: Para que erros do linter ou formatador não retornem status crítico e parem o processo de geração da resposta do agente.

Dica

3. Qual variável de ambiente contém o caminho do arquivo recém-editado?

Resposta: A variável $CLAUDE_FILE_PATH.

Checklist final de implementação de Hooks

  • Criado o diretório .claude/ e o arquivo settings.json na raiz do projeto.
  • Configurada a formatação automática de arquivos modificados via PostToolUse + Prettier.
  • Implementada a verificação de tipos/testes em PreToolUse para bloquear commits ruins.
  • Adicionadas notificações de som/desktop no evento Stop.
  • Testados todos os scripts de hook manualmente no terminal antes de integrar.
Este guia é totalmente gratuito. Se ele te poupou uma noite, você pode apoiar o crescimento do projeto.
Apoiar o autor