Automatização com Claude Code: Hooks, Skills e Rules Explicados

Já usa o Claude Code há algum tempo. Ele lê os seus ficheiros, escreve código, executa comandos. Está a correr bem. Mas continua a fazer manualmente coisas que podiam acontecer automaticamente — formatar código depois de cada edição, verificar comandos perigosos antes de executarem, seguir o mesmo processo de deploy em vários passos vezes sem conta.

O Claude Code tem três sistemas que resolvem isto: hooks, skills e rules. Apenas 12% dos setups na nossa análise usam hooks, mas esses obtêm 6.8/10 em média contra 2.1 sem. A diferença não é pequena — e a configuração não é difícil.

Comecemos por algo concreto.

O seu primeiro hook: formatar automaticamente cada ficheiro que o Claude toca

Eis o problema. O Claude edita um ficheiro TypeScript. O código funciona, mas a formatação está errada — indentação incorreta, ponto e vírgula em falta, o que quer que a sua configuração do Prettier imponha. Pede ao Claude para corrigir a formatação. Isso é um turno desperdiçado.

Em vez disso, vamos fazer com que a formatação aconteça automaticamente após cada edição.

Crie este ficheiro em .claude/hooks/format-on-save.sh:

#!/bin/bash
# Executa depois de o Claude editar ou criar um ficheiro

INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')

if [ -z "$FILE" ]; then
  exit 0
fi

# Formatar com base no tipo de ficheiro
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
  *.py)
    ruff format "$FILE" 2>/dev/null
    ;;
  *.go)
    gofmt -w "$FILE" 2>/dev/null
    ;;
esac

Torne-o executável:

chmod +x .claude/hooks/format-on-save.sh

Agora registe-o em .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": ".claude/hooks/format-on-save.sh"
      }
    ]
  }
}

É isso. Da próxima vez que o Claude editar qualquer ficheiro, o Prettier (ou ruff, ou gofmt) executa automaticamente. Sem prompts extra, sem limpeza manual.

Experimente. Peça ao Claude para criar uma função simples num ficheiro TypeScript qualquer. Observe a saída — o ficheiro é formatado automaticamente após a edição. Nunca mais tem de pensar em formatação.

O que são exatamente hooks, skills e rules?

Antes de avançarmos, clarifiquemos o modelo mental. Estas três coisas confundem quase toda a gente no início, por isso aqui vai a versão curta:

• Hooks executam código antes ou depois de cada chamada de ferramenta. São automáticos — não os dispara, simplesmente executam. Pense em "event listeners".
• Skills são comandos slash que escreve. /deploy, /review, /ticket PROJ-123. Empacotam um workflow multi-passo que pode ativar por nome.
• Rules são instruções que se carregam automaticamente com base nos ficheiros em que o Claude está a trabalhar. Quando o Claude toca num ficheiro .tsx, as suas rules de frontend aparecem. Quando toca em SQL, as rules de base de dados aparecem.

Agora vejamos cada um em detalhe.

Hooks: a rede de segurança e o piloto automático

Um hook é um script shell que o Claude Code executa num momento específico. Há quatro tipos:

• PreToolUse — executa antes de uma chamada de ferramenta. Pode bloqueá-la.
• PostToolUse — executa depois de uma chamada de ferramenta. Pode transformar a saída.
• Stop — executa quando o Claude termina o seu turno.
• SessionStart — executa uma vez ao iniciar uma sessão.

Já viu o PostToolUse com o formatador. Vejamos o mais importante: um guard de segurança.

O guard de segurança PreToolUse

Este hook apanha comandos perigosos antes de executarem. Copie isto para .claude/hooks/pre-tool-guard.sh:

#!/bin/bash
# Bloquear comandos shell destrutivos

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool')
COMMAND=$(echo "$INPUT" | jq -r '.input.command // empty')

if [ "$TOOL" = "Bash" ]; then
  if echo "$COMMAND" | grep -qE 'rm -rf /|git push --force|git reset --hard|DROP TABLE'; then
    echo '{"blocked": true, "reason": "Comando destrutivo bloqueado pelo guard de segurança"}'
    exit 0
  fi
fi

echo '{"blocked": false}'

chmod +x .claude/hooks/pre-tool-guard.sh

Registe-o no settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": ".claude/hooks/pre-tool-guard.sh"
      }
    ]
  }
}

Agora se o Claude tentar executar rm -rf / ou git push --force, o hook interceta-o, devolve blocked: true, e o Claude vê a razão. O comando nunca executa.

Pode testá-lo agora mesmo sem o Claude:

echo '{"tool":"Bash","input":{"command":"rm -rf /"}}' | .claude/hooks/pre-tool-guard.sh

Deverá ver {"blocked": true, "reason": "Comando destrutivo bloqueado pelo guard de segurança"}. A sua rede de segurança está a funcionar.

SessionStart: dar contexto ao Claude desde o início

Este hook executa uma vez quando abre o Claude Code. É perfeito para injetar contexto que ajuda o Claude a orientar-se:

#!/bin/bash
# .claude/hooks/session-start.sh

echo "## Estado Git Atual"
echo "Branch: $(git branch --show-current)"
echo "Último commit: $(git log --oneline -1)"
echo "Ficheiros modificados:"
git status --short
echo ""
echo "## TODOs recentes"
grep -r "TODO\|FIXME\|HACK" src/ --include="*.ts" -l 2>/dev/null | head -10

Cada sessão começa com o Claude a saber em que branch está, qual foi o último commit, e que ficheiros têm TODOs abertos. Acabou-se o "em que branch estou?" como primeira pergunta.

Skills: os seus comandos slash pessoais

É aqui que a coisa fica divertida. Escreve um ficheiro markdown que descreve um workflow, e ele torna-se um comando slash que pode escrever a qualquer momento.

O seu primeiro skill: um comando de deploy

Crie .claude/skills/deploy.md:

---
name: deploy
description: Fazer deploy do branch atual para staging ou produção
---

# Workflow de Deploy

1. Executar `npm run build` para verificar que o build passa
2. Executar `npm run test` para confirmar que todos os testes passam
3. Verificar branch atual: `git branch --show-current`
4. Se em `main`:
   - Deploy para produção: `railway up --service production`
   - Verificar health check: `curl -s https://api.example.com/health`
5. Se em outro branch:
   - Deploy para staging: `railway up --service staging`
   - Mostrar URL de staging para revisão

Sempre reportar o estado do deploy e o URL.

Escreva /deploy no Claude Code. O Claude faz build, testa, verifica o branch, faz deploy no ambiente certo, e verifica o health check. Um comando em vez de cinco passos manuais.

Um skill de revisão de código

Este é prático para uso diário. Guarde como .claude/skills/review.md:

---
name: review
description: Rever alterações staged antes de commit
---

# Revisão de Código

1. Executar `git diff --staged` para ver todas as alterações
2. Para cada ficheiro, verificar:
   - Tratamento de erros: operações async estão em try/catch?
   - Segurança: secrets hardcoded, injeção SQL ou XSS?
   - Tipos: algum `any` que deveria ser específico?
   - Testes: funções modificadas têm atualizações de testes?
3. AUTO-CORRIGIR problemas mecânicos (formatação, tipos em falta, bugs óbvios)
4. Reportar issues CRÍTICAS (deve corrigir) e INFORMATIVAS (vale considerar)
5. Se sem issues críticas: sugerir mensagem de commit

Escreva /review antes de commit e o Claude verifica o seu trabalho. Problemas mecânicos são corrigidos automaticamente. Decisões ambíguas são sinalizadas para que decida.

Skills que aceitam argumentos

Skills podem receber entrada. Guarde como .claude/skills/ticket.md:

---
name: ticket
description: Começar trabalho num ticket específico
---

O utilizador fornecerá um ID de ticket (ex. `/ticket PROJ-123`).

1. Obter detalhes do ticket
2. Criar novo branch: `git checkout -b feat/PROJ-123-descricao`
3. Ler ficheiros relevantes mencionados no ticket
4. Propor plano de implementação antes de escrever código
5. Esperar aprovação antes de continuar

Escreva /ticket PROJ-123 e o Claude lê o ticket, cria um branch, encontra os ficheiros relevantes, e propõe um plano — tudo antes de escrever uma única linha de código.

Rules: instruções que carregam na hora certa

Já conhece as rules do guia de setup. Eis porque importam para a automatização: mantêm o contexto do Claude limpo.

Imagine que tem 200 linhas de convenções de frontend, 150 linhas de rules de backend e 100 linhas de standards de base de dados. Se puser as 450 linhas no CLAUDE.md, o Claude carrega tudo em cada interação — mesmo quando só está a editar um ficheiro CSS.

Com rules, o Claude carrega convenções de frontend apenas quando toca ficheiros .tsx, rules de base de dados apenas ao editar migrações, e avisos de segurança apenas perto de ficheiros sensíveis.

Aqui está uma rule de segurança que importa:

<!-- .claude/rules/security.md -->
---
globs: [".env*", "*.pem", "*.key", "*secret*", "*credential*"]
---

- NUNCA fazer commit deste ficheiro no controlo de versões
- NUNCA registar o conteúdo deste ficheiro
- NUNCA incluir estes valores em mensagens de erro ou respostas API
- Se este ficheiro precisar de modificação, explicar as alterações necessárias mas não mostrar valores atuais

Quando o Claude toca qualquer ficheiro que corresponda a esses padrões, estas rules aparecem automaticamente. Quando trabalha em código não relacionado, ficam fora do caminho.

A folha de consulta: quando usar o quê

Esta é a pergunta que toda a gente faz. Assim se decide:

Use um hook quando a ação deve acontecer sempre, sem que ninguém precise pensar nisso. Formatação ao gravar. Bloquear comandos perigosos. Registar cada chamada de ferramenta. Se um humano não deveria ter de se lembrar, é um hook.

Use um skill quando tem um processo multi-passo que repete regularmente. Deploy. Revisão de código. Iniciar ticket novo. Escrever migração. Se escreveria uma checklist para isso, é um skill.

Use uma rule quando as instruções dependem de em que ficheiro o Claude está a trabalhar. Convenções de frontend para ficheiros .tsx. Segurança SQL para migrações. Avisos de segurança para ficheiros .env. Se o conselho é "quando trabalhares em X, segue estas diretrizes", é uma rule.

Combinar os três: um exemplo real

Eis como hooks, skills e rules funcionam juntos num workflow de migração de base de dados:

1. Rule (.claude/rules/database.md) — quando o Claude toca ficheiros de migração, carrega automaticamente as suas convenções: queries parametrizadas, requisitos de rollback, padrões de nomes.

2. Hook (PreToolUse em Bash) — se o Claude tenta executar um comando de migração, o hook verifica se existe ficheiro de rollback. Bloqueia o comando se não houver rollback.

3. Skill (/migrate) — um comando slash que cria o ficheiro de migração a partir de um template, gera o rollback correspondente, executa contra uma base de dados de teste, e reporta o resultado.

A rule fornece o conhecimento. O hook impõe a restrição. O skill empacota o workflow. Cada peça faz um trabalho, bem feito.

Quando as coisas não funcionam

Se os seus hooks, skills ou rules não estão a disparar, eis como depurar:

# Executar Claude em modo verbose para ver a execução de hooks
claude --verbose

# Testar um hook independentemente
echo '{"tool":"Bash","input":{"command":"rm -rf /"}}' | .claude/hooks/pre-tool-guard.sh

Os suspeitos do costume:

• Script de hook sem permissões de execução. Corrija com chmod +x .claude/hooks/seu-hook.sh
• Padrão glob que não corresponde. O padrão **/api/**/*.ts é diferente de api/**/*.ts. Teste o seu contra caminhos de ficheiros reais.
• Skill não encontrado. Certifique-se que está em .claude/skills/ com o name: correto no frontmatter.

O que construiu

Se seguiu os passos, agora tem:

• Um guard de segurança que bloqueia comandos destrutivos antes de executarem
• Um auto-formatador que limpa cada ficheiro que o Claude toca
• Um skill de deploy que empacota todo o seu workflow de deploy num comando
• Um skill de revisão que verifica o seu código antes de fazer commit
• Rules que injetam as convenções certas na hora certa

A maioria dos utilizadores do Claude Code nunca chega aqui. Acabou de construir um ambiente de desenvolvimento personalizado que trabalha para si automaticamente.

Pronto para mais? Aqui está para onde ir:

• Ligar o Claude às suas ferramentas — servidores MCP que permitem ao Claude consultar a sua base de dados, pesquisar no GitHub e obter erros do Sentry
• Padrões de workflow avançados — subagents, execução paralela e as estratégias de depuração dos power users
• Avaliar o seu setup para ver exatamente onde está a sua automatização

Perguntas frequentes

Os hooks tornam as coisas mais lentas?

Um guard de segurança simples baseado em grep adiciona 10-50 milissegundos por chamada de ferramenta — não vai notar. Mas um hook PostToolUse que executa Prettier adiciona 200-500ms por edição. Mantenha os hooks rápidos. Se um hook precisa de fazer trabalho pesado, lance o processo em segundo plano para que o Claude não espere.

Posso partilhar hooks entre todos os meus projetos?

Sim. Coloque hooks partilhados em ~/.claude/hooks/ e referencie-os com caminhos absolutos no seu ~/.claude/settings.json global. Hooks específicos do projeto vão em .claude/hooks/ com caminhos relativos nas definições do projeto.

O que acontece se um hook crashar?

O Claude Code captura erros de hooks e continua como se o hook não existisse — a chamada de ferramenta executa normalmente. O erro aparece no modo verbose. É design safety-first: um hook partido nunca impede o Claude de funcionar. Mas teste os seus hooks a sério — um guard de segurança partido que falha silenciosamente é pior do que não ter guard nenhum.

Um skill pode chamar outro skill?

Não diretamente. Não existe mecanismo de /deploy a chamar /review. Se precisa de um workflow composto, construa um único skill que inclua todos os passos. Em alternativa, use um hook para disparar lógica adicional depois de um skill terminar.

Como as rules interagem com o CLAUDE.md?

Ambos são carregados no contexto, e o Claude segue tudo. Se uma rule contradiz algo no CLAUDE.md, a instrução mais específica geralmente ganha. Mas evite contradições à partida — use o CLAUDE.md para instruções ao nível do projeto e rules para sobreposições específicas de ficheiros.