Automatizando tarefas repetitivas no Claude Code: comandos personalizados, hooks e modo não interativo

Neste capítulo você vai aprender a transformar tarefas que repete todos os dias em automações do Claude Code. São três mecanismos: comandos personalizados, que você dispara com uma barra como qualquer slash command; hooks, que executam scripts em momentos precisos da sessão; e o modo não interativo, que permite chamar a ferramenta de dentro de scripts e de pipelines de integração contínua. Tudo se apoia no que você já conhece: a pasta .claude do capítulo um, o settings.json com permissões do capítulo seis e a disciplina de instruções claras do capítulo quatro.

Comandos personalizados em arquivos Markdown

Se você já digitou pela terceira vez algo como revise este arquivo conforme nossas convenções, verifique tratamento de erros e procure logs esquecidos, está na hora de salvar esse pedido. Um comando personalizado é apenas um arquivo Markdown dentro da pasta .claude/commands. O nome do arquivo vira o nome do comando, e o conteúdo é o texto que será enviado ao Claude como se você o tivesse digitado. Um arquivo chamado revisar.md cria o comando /revisar.

Existem dois lugares para guardar esses arquivos. A pasta .claude/commands na raiz do projeto é versionada e compartilhada com o time. A pasta .claude/commands dentro da sua pasta de usuário vale para todos os projetos da sua máquina. A regra é simples: se o comando depende de convenções do projeto, fica no projeto; se é um hábito seu, fica no usuário.

Exemplo um: revisão por checklist com argumentos

O texto do comando pode receber o que você digitar depois do nome usando a variável $ARGUMENTS. Veja o arquivo revisar.md do projeto de tarefas que acompanhamos desde o capítulo dois.

--- description: Revisa um arquivo conforme o checklist do time --- Revise o arquivo $ARGUMENTS seguindo este checklist. Para cada item, responda cumprido ou não cumprido e cite a linha. 1. Toda função exportada trata erros e nunca engole exceções. 2. Não há console.log esquecido. 3. Entradas externas passam por validação com Zod. 4. Nomes seguem as convenções do CLAUDE.md. Não edite nada. Termine com uma lista de correções sugeridas, ordenada por gravidade.

Ao digitar /revisar src/rotas/tarefas.js, o caminho substitui $ARGUMENTS e o Claude executa exatamente a revisão que você definiu. O bloco entre os três traços no início é o cabeçalho opcional: a descrição aparece na lista do /help, e você também pode declarar ali uma chave allowed-tools para restringir quais ferramentas o comando pode usar, por exemplo apenas leitura.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Exemplo dois: gerar changelog com saída de comandos

Um comando pode incluir a saída de um comando de shell no próprio texto. Basta escrever um ponto de exclamação seguido do comando entre acentos graves. Para isso funcionar, o cabeçalho do comando precisa declarar a chave allowed-tools incluindo a ferramenta Bash, por exemplo allowed-tools: Bash(git log:*); sem essa declaração, o comando de shell não é executado e o texto é enviado literalmente. O Claude Code executa o comando antes de enviar o pedido e insere o resultado no lugar.

Gere uma entrada de changelog em Markdown para a versão $ARGUMENTS a partir destes commits: !`git log $(git describe --tags --abbrev=0)..HEAD --oneline` Agrupe em Adicionado, Corrigido e Alterado, usando os prefixos de Conventional Commits para classificar. Escreva em português, voltado a usuários finais. Insira no topo do CHANGELOG.md sem apagar entradas anteriores.

Com /changelog 2.4.0, você recebe a entrada pronta a partir dos commits desde a última tag, algo que antes exigia copiar o histórico à mão.

Exemplo três: componente padrão e namespaces

Quando o número de comandos cresce, organize-os em subpastas. Um arquivo em .claude/commands/frontend/componente.md continua sendo invocado pelo nome do arquivo, mas aparece na listagem agrupado pela subpasta frontend, o que ajuda o time a encontrar o que precisa. O conteúdo desse comando pede para criar um componente novo com nome $ARGUMENTS usando um componente existente como modelo de estrutura, criando junto o arquivo de teste e o arquivo de estilos, e sem alterar nenhum componente já existente. É a mesma técnica de aderência aos padrões do projeto do capítulo sete, agora reutilizável com uma linha.

Hooks: garantias que não dependem de pedir

Uma instrução no CLAUDE.md é um pedido que o Claude normalmente respeita. Um hook é uma garantia: um comando de shell que o Claude Code executa automaticamente quando um evento ocorre, sem que o modelo decida nada. Os eventos mais usados são quatro. PreToolUse dispara antes de uma ferramenta ser usada, como Bash ou Edit. PostToolUse dispara logo depois. Notification dispara quando o Claude precisa da sua atenção, por exemplo ao pedir aprovação. Stop dispara quando o Claude termina de responder.

Os hooks são configurados na seção hooks do settings.json, nos mesmos três níveis de usuário, projeto e local que você conheceu no capítulo seis. Cada entrada tem um matcher, que filtra o nome da ferramenta, e uma lista de comandos. O comando recebe na entrada padrão um JSON com os detalhes do evento, incluindo os parâmetros da ferramenta. Se ele terminar com código zero, tudo segue. Se terminar com código dois, a mensagem escrita na saída de erro é devolvida ao Claude como explicação; em PreToolUse isso bloqueia a ação antes de ela acontecer, enquanto em PostToolUse a ferramenta já rodou e o aviso serve apenas para que o Claude corrija o que fez.

Rodar o formatador após cada edição

{   "hooks": {     "PostToolUse": [       {         "matcher": "Edit|Write",         "hooks": [           {             "type": "command",             "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown"           }         ]       }     ]   } }

Aqui a ferramenta jq extrai o caminho do arquivo editado do JSON recebido e o passa ao Prettier. Depois disso, nenhum diff chega a você com formatação errada, e você deixa de gastar janela de contexto pedindo formatação.

Bloquear um comando proibido

A lista deny do capítulo seis resolve padrões fixos. Um hook PreToolUse com matcher Bash permite lógica arbitrária. Salve o script abaixo em .claude/hooks/bloquear-push-forcado.sh e aponte o comando do hook para ele.

#!/bin/bash cmd=$(jq -r '.tool_input.command') if echo "$cmd" | grep -qE 'push +(-f|--force)'; then   echo "Push forçado bloqueado pelo hook do projeto" >&2   exit 2 fi exit 0

Você poderia estender o script para permitir o push forçado apenas em branches que começam com o seu nome, algo impossível de expressar em uma regra deny simples. Lembre-se, porém, de que verificações por texto são frágeis: variações como git push origin main -f, apelidos de comando ou vários comandos encadeados na mesma linha podem escapar do padrão. Trate o hook como uma camada extra e proteja as branches importantes também no servidor Git.

Avisar quando a tarefa termina

Um hook no evento Stop com o comando notify-send no Linux, ou osascript exibindo uma notificação no macOS, avisa quando uma tarefa longa acaba. Assim você pode trabalhar em outra janela sem ficar olhando o terminal.

Uma precaução: hooks rodam com as suas permissões na sua máquina. Ao clonar um projeto de terceiros, revise os hooks do settings.json antes de aceitá-los. O Claude Code pede confirmação quando hooks vindos de configuração de projeto mudam, e você deve ler o que está sendo aprovado.

Modo não interativo com claude -p

Até aqui tudo aconteceu dentro de uma sessão interativa. Com a opção -p, de print, o Claude Code recebe um pedido, responde e encerra, o que o torna utilizável em qualquer script. Ele aceita entrada por pipe, então você pode encadear ferramentas do terminal.

cat logs/erro.log | claude -p "Resuma as causas prováveis destes erros em três linhas" git diff main | claude -p "Liste riscos deste diff, um por linha, sem sugerir código"

Para consumir a resposta em outro programa, use --output-format json. A saída traz o texto da resposta, o identificador da sessão, o número de turnos e o custo em dólares daquela execução. Um exemplo prático em integração contínua: um passo do pipeline executa gh pr diff, envia o resultado ao claude -p com uma instrução de revisão em formato de lista, e publica o texto como comentário no pull request usando gh pr comment. Isso reaproveita o GitHub CLI do capítulo onze e a revisão por checklist deste capítulo.

Dois cuidados são obrigatórios. O primeiro é permissão. No modo não interativo ninguém está lá para aprovar, então toda ação que exigiria confirmação é simplesmente negada, a menos que você a libere com a opção --allowedTools, por exemplo --allowedTools "Read" "Bash(npm test)". Nunca use --dangerously-skip-permissions em um servidor de integração que tenha acesso a segredos ou ao repositório com direito de escrita; a exceção, como no capítulo seis, é um contêiner descartável e isolado. Guarde a ANTHROPIC_API_KEY como segredo do pipeline, nunca no código.

O segundo cuidado é custo. Cada chamada de claude -p é uma sessão nova: se você autentica com uma chave de API, ela é cobrada por uso; se usa uma assinatura Pro ou Max, o consumo entra nos limites do seu plano. Em qualquer um dos casos, um script em loop pode consumir muito em pouco tempo. Limite o número de passos com --max-turns, delimite bem o pedido para evitar buscas amplas no projeto e registre o campo de custo do JSON em cada execução para acompanhar o gasto.

Recapitulando

Comandos personalizados são arquivos Markdown em .claude/commands, no projeto ou no usuário, que aceitam argumentos por $ARGUMENTS, podem incluir saída de comandos de shell e se organizam em subpastas. Hooks são comandos configurados no settings.json que rodam em eventos como PreToolUse, PostToolUse e Stop, e servem para formatar após edições, bloquear ações com código de saída dois e notificar o fim de tarefas, com a vantagem de serem garantias e não pedidos. O modo não interativo com claude -p leva o Claude Code a scripts e pipelines, com entrada e saída por pipe e formato JSON, desde que você controle explicitamente as ferramentas permitidas e acompanhe o custo de cada execução.