Claude Code hooks, slash commands e MCP: os três recursos que mudam seu fluxo

A diferença entre quem usa Claude Code e quem voa com ele não está no modelo. Está em três recursos que quase ninguém configura: hooks, slash commands e MCP.

A maioria instala o Claude Code, faz uns prompts, gosta, e para por aí. Trata como um autocomplete turbinado. Funciona, mas é desperdiçar a maior parte da ferramenta.

Neste tutorial você vai configurar os três recursos que transformam o Claude Code de assistente reativo em parte do seu fluxo: hooks para automatizar e blindar ações, slash commands para empacotar procedimentos repetidos, e MCP para dar ao agente acesso real às suas ferramentas. Tudo com os arquivos de config exatos.

TL;DR

• O que é: os três pontos de extensão do Claude Code — hooks (automação por evento), slash commands (procedimentos reutilizáveis) e MCP (conexão com ferramentas externas).
• Stack: Claude Code CLI, settings.json, .mcp.json, arquivos Markdown em .claude/.
• Custo/Acesso: tudo embutido no Claude Code, sem dependência paga extra (fora a conta do próprio Claude).
• Pré-requisito: Claude Code instalado. Se ainda não usa, comece por Claude Code: o que é, como funciona e por que os devs migraram pra ele.

Por que esses três recursos importam

O Claude Code não é só o modelo. É um harness: o modelo no centro, cercado de ferramentas, contexto e regras que decidem o que ele pode fazer e como. Hooks, slash commands e MCP são exatamente os três pontos onde você mexe nesse harness.

Pensa assim:

• Hook é o "sempre que acontecer X, faça Y" — automação determinística, sem depender do modelo lembrar.
• Slash command é o "quando eu pedir, execute esse procedimento" — um prompt empacotado e versionado.
• MCP é o "o agente agora enxerga essa ferramenta" — banco, issue tracker, monitoramento, o que for.

Antes, você cercava o agente na unha: copiava log do Sentry pro chat, repetia o mesmo prompt de revisão dez vezes, torcia pra ele não rodar um rm errado. Com os três configurados, isso vira parte da máquina. O agente lê o Sentry direto, você dispara a revisão com /review, e o rm -rf é bloqueado por um hook antes de chegar no shell.

Isso não é hype. É engenharia de fluxo. Vamos aos três.

Claude Code hooks: automação que não depende do modelo lembrar

Hook é um comando que o Claude Code dispara automaticamente em pontos da sessão. O modelo não decide se roda — o harness roda. É essa garantia que muda o jogo.

Os eventos cobrem o ciclo de vida inteiro. Os que você mais vai usar (referência oficial):

• SessionStart — quando a sessão começa.
• UserPromptSubmit — quando você manda um prompt, antes do modelo ver.
• PreToolUse — antes de uma tool rodar (pode bloquear).
• PostToolUse — depois que a tool roda com sucesso.
• Stop — quando o Claude termina de responder.

Hooks ficam no settings.json — em ~/.claude/settings.json (vale pra todos os projetos), .claude/settings.json (do projeto, commitável) ou .claude/settings.local.json (do projeto, fora do git). A estrutura tem três níveis: evento → matcher (filtro por tool) → handler.

O caso clássico: barrar comando destrutivo antes dele rodar. No .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

E o script que decide. Ele recebe o input da tool como JSON no stdin e responde com uma decisão de permissão:

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Comando destrutivo bloqueado por hook"
    }
  }'
else
  exit 0  # sem decisão: segue o fluxo normal de permissão
fi

permissionDecision aceita deny, allow, ask ou defer. Saída com exit code 2 também bloqueia e manda o stderr de volta pro Claude como feedback — útil pra dizer pra ele o que fazer diferente, não só barrar.

A aplicação prática vai muito além de bloquear rm. Um PostToolUse com matcher Edit|Write que roda php artisan test (ou seu linter) toda vez que um arquivo muda. Um Stop que avisa no terminal quando a tarefa termina. Um SessionStart que injeta o estado atual do projeto no contexto. O impacto no fluxo: regras de qualidade e segurança deixam de depender do modelo "lembrar" e viram trilho fixo.

Slash commands: pare de repetir o mesmo prompt

Se você cola o mesmo bloco de instruções no chat toda semana, isso devia ser um slash command. É um arquivo Markdown que vira um comando /nome.

Detalhe importante de 2026: slash commands e skills foram unificados. Um arquivo em .claude/commands/deploy.md e um skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam igual (docs). Os arquivos em .claude/commands/ continuam valendo; skills só adicionam recursos extras (pasta de apoio, invocação automática pelo modelo).

Um comando de revisão de PR, em .claude/commands/review-pr.md:

---
description: Revisa o PR atual buscando bugs e problemas de segurança
argument-hint: [numero-do-pr]
allowed-tools: Bash(gh pr diff *) Bash(gh pr view *)
---

Revise o PR #$1 com foco em correção e segurança.

Contexto já carregado:

- Diff do PR: !`gh pr diff $1`
- Arquivos alterados: !`gh pr diff $1 --name-only`

Aponte bugs, riscos de segurança e quebras de contrato. Seja específico no arquivo e na linha.

Três coisas acontecem aqui, e cada uma muda o resultado:

• $1, $2, $ARGUMENTS — argumentos. /review-pr 4521 injeta 4521 no lugar de $1. $ARGUMENTS pega tudo de uma vez.
• !`comando` — injeção de contexto dinâmico. O Claude Code roda o comando antes do modelo ver o prompt e substitui a linha pela saída. O modelo recebe o diff já inline, não a instrução de buscá-lo.
• allowed-tools — concede as tools listadas sem pedir confirmação enquanto o comando roda.

O ganho não é digitar menos. É padronizar. O /review-pr da sua equipe roda sempre com o mesmo prompt, as mesmas tools e o contexto certo já carregado — versionado no repositório, igual pra todo mundo. Procedimento vira artefato, não memória de quem está na frente do teclado.

MCP: dar ao agente acesso real às suas ferramentas

Toda vez que você copia dado de outra ferramenta pro chat — log de monitoramento, issue do Jira, linha de um banco — é sinal de que falta um servidor MCP. O Model Context Protocol é um padrão aberto pra conectar o agente a ferramentas, bancos e APIs externos. Conectado, o Claude lê e age direto no sistema.

Adicionar um servidor é um comando. Os três transportes (referência):

# HTTP — servidores remotos (a maioria dos SaaS hoje)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# SSE — streaming via server-sent events
claude mcp add --transport sse asana https://mcp.asana.com/sse

# stdio — processo local, pra ferramentas com acesso ao sistema
claude mcp add --transport stdio meu-server -- npx -y meu-mcp-server

O que mais confunde quem começa é o escopo, que decide onde a config mora e se a equipe compartilha:

• local (padrão) — só você, só neste projeto. Fica em ~/.claude.json.
• project — compartilhado via .mcp.json na raiz, commitável.
• user — você, em todos os seus projetos.

Para a equipe inteira ganhar a mesma ferramenta, use --scope project. O .mcp.json resultante é simples e vai pro git:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

Por segurança, o Claude Code pede aprovação antes de usar servidores de .mcp.json que vieram do repositório — você revisa antes de confiar. Para resetar as escolhas, claude mcp reset-project-choices.

O impacto em produto é o maior dos três. "Implemente a feature da issue ENG-4521 e abra o PR", "veja no Sentry quanto essa feature é usada", "puxe os 10 últimos pedidos do Postgres" — tudo isso vira pedido direto, sem ponte manual. O agente para de trabalhar a partir do que você cola e passa a trabalhar a partir do que o sistema realmente diz.

Limitações e pontos de atenção

Poder vem com responsabilidade. Onde o pessoal se queima:

• Hook é código que roda com suas permissões. Um PreToolUse mal escrito pode travar a sessão ou rodar coisa que você não quer. Trate hooks como parte do código do projeto: revise, versione, teste.
• MCP de .mcp.json é superfície de ataque. Um servidor malicioso herdado de um repositório vê o que o agente vê. Por isso a aprovação existe — não clique em "confiar" no automático. Revise o .mcp.json antes.
• Servidor MCP custa contexto. Cada servidor conectado injeta as descrições das tools no contexto. Conectar dez servidores "por garantia" come token budget e degrada a escolha de tool. Conecte o que a tarefa pede.
• allowed-tools em slash command não é blindagem. Ele concede tools sem prompt enquanto o comando roda; não substitui suas regras de permissão. Não use pra liberar Bash(*) geral.

FAQ rápido

Hook bloqueou algo que eu queria. Como destravo? Edite o if/matcher ou o script. Hook é determinístico: se a regra bate, ele dispara. Use /hooks dentro do Claude Code pra listar tudo que está configurado e achar o culpado.

Slash command e skill são a mesma coisa agora? Praticamente. Os dois geram /nome. Skill adiciona pasta de apoio e invocação automática pelo modelo. Arquivo em .claude/commands/ continua funcionando — migre só se precisar dos extras.

Posso usar servidor MCP de terceiros com segurança? Pode, com critério. Prefira conectores revisados (o Anthropic Directory usa a mesma infra), e lembre que servidor MCP enxerga o que o agente enxerga. Não conecte servidor desconhecido num projeto com dado sensível.

Onde coloco a config: global ou do projeto? Regra de bolso: o que é seu hábito pessoal vai em ~/.claude/; o que a equipe precisa compartilhar vai em .claude/ (ou .mcp.json) e entra no git.

Conclusão

Hooks, slash commands e MCP são os três pontos onde você para de usar o Claude Code e começa a moldar ele em volta do seu fluxo. Hook trava e automatiza. Slash command padroniza procedimento. MCP conecta o agente ao mundo real. Configura os três e o agente deixa de ser autocomplete e vira infraestrutura.

E esse é exatamente o salto que separa brincar com IA de construir produto com IA: parar de pedir código e começar a desenhar o harness em volta do modelo. Se você quer ver isso aplicado de ponta a ponta — do prompt até o agente rodando em produção — é o que a gente destrincha no workshop Do Prompt ao Harness: construindo um agente de vendas.

O próximo passo é abrir seu settings.json e escrever o primeiro hook. Começa pelo PreToolUse que barra o rm -rf. É o menor commit possível com o maior alívio de produção.