CLAUDE CODE MASTER CLASS

TL;DR — MCP (Model Context Protocol) é como Claude conversa com o mundo além do seu filesystem. Um .mcp.json declara servidores; cada servidor expõe ferramentas chamadas mcp__<srv>__<tool>.

▸ Cinco servidores maduros pra conhecer

• playwright — automação de browser. Click, type, screenshot, evaluate JS. Default pra workflow autenticado.
• chrome-devtools — observabilidade de rede, performance, runtime. Só pra debug.
• dbhub — SQL multi-DB (Postgres, MySQL, SQLite). Read-only por padrão.
• nextjs-devtools — build logs, routes, server actions, diagnostics de cache.
• github — issues / PRs / repos / workflows estruturados (mais rico que o CLI gh).

▸ Adicionando um servidor

// .mcp.json na raiz do repo
{ "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"]
    }
} }

▸ Trust gate

Por padrão Claude pergunta antes de habilitar servidores MCP declarados num projeto. Use enableAllProjectMcpServers: true nos settings pra pular o prompt — só em repos que você confia.

▸ Modelo mental

TL;DR — uma skill é uma pasta com um SKILL.md dentro. O corpo dele É o prompt. Invoca como /<nome>. Você para de colar as mesmas instruções toda sessão.

▸ Anatomia

▸ O frontmatter que importa

---
description: Dica de descoberta em uma linha (Claude lê pra saber quando sugerir você)
argument-hint: <new <slug> | list>
allowed-tools: [Read, Grep, Bash]
paths: ["docs/specs/**"]   # path-scoped: só carregável em dirs que casem
context: fork               # turn isolado (não polui a conversa principal)
---
# /nome — corpo abaixo dessa linha é o prompt

▸ Duas features que fazem diferença

1. $ARGUMENTS — o que o usuário digitou depois do slash command. Permite uma skill lidar com várias formas de chamar.
2. !`shell-cmd` — roda no carregamento da skill; stdout é injetado como contexto. Excelente pra estado vivo ("data de hoje", "branch atual", "lista de PRs abertos").

▸ Skills bundled (já na sua máquina)

/simplify · /batch · /debug · /loop · /claude-api — todas vêm com o Claude Code. /help lista o que está na sua instalação.

TL;DR — um agent roda num contexto isolado e retorna uma única mensagem. Delegue quando (a) o trabalho precisa de muitas tool calls, (b) o resultado cabe num resumo, ou (c) você quer manter ruído fora da conversa principal.

▸ Os cinco agents built-in

• general-purpose — pesquisa e execução multi-step. O default.
• Explore — busca read-only rápida. "Onde X está definido? Que arquivos usam Y?"
• Plan — modo arquiteto. Produz um plano de implementação, não escreve código.
• claude-code-guide — Q&A sobre o próprio Claude Code (essa Master Class é um exemplo real).
• statusline-setup — configura sua status line. Nicho mas vem com o produto.

▸ Uma boa delegação tem cinco partes

TASK:        uma frase — o que fazer
CONTEXT:     arquivos/paths que o agent deve ler primeiro
CONSTRAINTS: o que NÃO fazer · budgets · guardrails de estilo
DELIVERABLE: artefato concreto (path de arquivo, PR, formato do resumo)
DONE_WHEN:   condição verificável (testes passam, arquivo existe)

DELIVERABLE ou DONE_WHEN é obrigatório (ou ambos). O agent não herda contexto do pai — entrega tudo que ele precisa de antemão.

▸ Dispatch via tool call

Agent({
  subagent_type: "Explore",
  prompt: "TASK: localizar todos os callers de getUser() em src/.\n..." ,
  model: "sonnet",          // opcional · sobrescreve default
  isolation: "worktree",    // opcional · roda em worktree git temporário
})

▸ Model-fit cheatsheet

Implementação mecânica → sonnet. Lookup rápido de schema/protocolo → haiku. Revisão de arquitetura ou debug exploratório → opus. Pesquisa comparativa multi-fonte → opus se ≥2 sinais, senão sonnet.

TL;DR — hooks são shell scripts que rodam em eventos de ciclo de vida. 29 eventos no total. Cada um recebe JSON via stdin e decide pelo exit code: 0 = permite, 2 em PreToolUse = BLOQUEIA (stderr mostrado ao agent), qualquer outro = só log.

▸ As sete famílias de eventos

1. Session lifecycle — SessionStart · SessionEnd · Setup · Stop · StopFailure
2. Prompts & instructions — UserPromptSubmit · UserPromptExpansion · InstructionsLoaded
3. Tool gates — PreToolUse · PostToolUse · PostToolUseFailure · PostToolBatch
4. Permission — PermissionRequest · PermissionDenied
5. Sub-agents & tasks — SubagentStart · SubagentStop · TaskCreated · TaskCompleted
6. Compaction — PreCompact · PostCompact
7. System — Notification · TeammateIdle · ConfigChange · CwdChanged · FileChanged · WorktreeCreate · WorktreeRemove · Elicitation · ElicitationResult

▸ Hook mínimo viável

// .claude/settings.json
{ "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash .claude/hooks/check-bash.sh"
      }]
    }]
} }

#!/usr/bin/env bash
# .claude/hooks/check-bash.sh — lê JSON de stdin, decide pelo exit
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
if [[ "$cmd" =~ rm\ -rf ]]; then
  echo "bloqueado: rm -rf é negado nesse projeto" >&2
  exit 2
fi
exit 0

▸ Uma pegadinha que vale sinalizar

PostToolUse(Bash) dispara só em sucesso. Pra capturar falhas, pareie com PostToolUseFailure(Bash). Payload de falha usa .error e não tem tool_response.

▸ Três tipos de handler

• type: command — shell script. O default.
• type: prompt — single-turn Claude eval sobre $ARGUMENTS.
• type: agent — dispara um sub-agente com ferramentas pra verificação profunda.