Estender o Claude Code: CLAUDE.md, hooks, subagents, MCP

Ao longo dos cinco primeiros capítulos você instalou o Claude Code, deu instruções a ele, saiu dos lugares em que ele trava e desenhou as permissões. Este capítulo é sobre remodelar a própria ferramenta. Decorar o nome das extensões não leva a lugar nenhum. O que ajuda é uma tabela de consulta: "qual delas resolve o que está me incomodando agora".

Um mapa para escolher — quatro perguntas decidem

São seis extensões, mas só quatro coisas a pensar. Pedir basta / precisa disparar toda vez / você quer isso em um contexto separado / você precisa alcançar o lado de fora — pergunte-se isso nessa ordem e a resposta costuma sair única.

Pedir basta?

Se uma falha ocasional não for fatal, palavras resolvem. → CLAUDE.md (as premissas permanentes) / Skills (os passos de um trabalho específico)

Precisa disparar toda vez?

Se uma única falha for um problema, bloqueie por meio de um mecanismo. → hooks. Eles são executados quando as configurações habilitadas correspondem ao evento e às condições.

Você quer isso em um contexto separado?

Se você não quer uma enxurrada de saída soterrando a linha principal, rode fora e receba só a conclusão. → subagents

Você precisa alcançar o lado de fora?

Quando você precisa de informação que a IA não tem como saber (os valores atuais de um banco de dados, o que está no seu gerenciador de tarefas). → MCP

A quinta pergunta é "você vai entregar isso para outras pessoas?". Se vai, plugins. As fáceis de confundir são Q1 e Q2: CLAUDE.md, Skills e hooks. Todas se parecem, mas diferem em quando são lidas e quem as executa.

CLAUDE.md — separe carregamento de cumprimento

O CLAUDE.md fornece contexto do projeto a cada sessão quando está em um local que é carregado. Use ~/.claude/CLAUDE.md para instruções compartilhadas entre projetos. Ele contém instruções em texto, não configurações que impõem permissões de operação.

Se o agente diz que leu o arquivo, mas não o segue, examine estas três questões separadamente.

Ele foi carregado? Veja se CLAUDE.md e as regras aparecem em Memory files no /context. O local de inicialização e as configurações de exclusão afetam quais arquivos entram no contexto. AGENTS.md carregado diretamente não aparece nessa lista; sua ausência, sozinha, não prova que ele não foi lido
Ele voltou após a compactação? O CLAUDE.md da raiz do projeto é relido do disco e reinserido após /compact. Arquivos CLAUDE.md de subdiretórios e regras específicas de caminhos são recarregados quando os arquivos correspondentes são lidos. Decisões mantidas somente na conversa recebem tratamento diferente
Ele influenciou a ação? Mesmo que tenha sido carregado, examine separadamente regras vagas e instruções conflitantes. Não suponha que a instrução mais recente sempre vença. Defina o escopo e as condições para exceções

A orientação oficial é menos de 200 linhas por arquivo CLAUDE.md. Isso não é um limite de carregamento nem uma fronteira que garanta o cumprimento. Mantenha as regras necessárias em todas as sessões e separe os detalhes com condições para sua leitura. Importar tudo por @path não reduz o contexto inicial. Use Skills para procedimentos ocasionais e regras específicas de caminhos para instruções limitadas a determinados arquivos.

Isso segue a documentação oficial de memória. Para exemplos de como diferenciar os casos e as diferenças entre ferramentas, veja como investigar agentes de IA que ignoram regras.

“Eu li” não comprova o cumprimento. Verifique a exibição de carregamento separadamente dos diffs e resultados dos testes. Transfira condições verificáveis automaticamente para hooks ou CI, como veremos a seguir, e informe as áreas que continuaram sem verificação.

hooks — execute verificações quando as condições corresponderem

Uma instrução escrita como “não reescreva o .env” não garante uma taxa de cumprimento. Se você precisa verificar uma condição e bloquear uma operação antes de executá-la, considere configurações de permissão e hooks.

Esta seção trata de hooks do tipo command, que executam comandos de shell. Quando as configurações habilitadas correspondem ao evento e às condições, o próprio Claude Code os inicia. Não é necessário que o modelo se lembre de executá-los. Porém, eles não rodam se estiverem desativados nas configurações ou se o caminho de execução não for coberto. Veja O que são os hooks do Claude Code? para uma visão geral. Os nove eventos abaixo são exemplos representativos, não uma lista completa.

SessionStart        no início ou na retomada
UserPromptSubmit    logo após o envio                               [pode bloquear]
PreToolUse          pouco antes de uma ferramenta = porteiro        [pode bloquear]
PostToolUse         depois do êxito da ferramenta = formatação      (não desfaz a ação concluída)
Notification        esperando entrada ou aprovação
Stop                fim de uma resposta                             [pode bloquear]
SubagentStop        subagent terminou                               [pode bloquear]
SessionEnd          fim da sessão
PreCompact          antes da compactação                            [pode bloquear]

O que pode ser bloqueado varia conforme o evento. Bloquear uma ferramenta antes da execução é diferente de impedir que uma resposta termine para que o trabalho continue. Recuse operações perigosas em PreToolUse e formate automaticamente em PostToolUse: são dois pontos de partida comuns. Coloque a configuração sob a chave "hooks" em settings.json. O local do arquivo determina o escopo (~/.claude/ = usuário, .claude/ = compartilhado, settings.local.json = pessoal).

Agora, vamos transformar em mecanismo o “não reescreva o .env” do início. É o exemplo do guia oficial que “bloqueia edições em arquivos protegidos”, restrito ao .env. Você precisa de duas coisas: uma configuração e um script.

① .claude/settings.json — executa o script logo antes de Edit ou Write ser chamado.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh — bloqueia a edição se o nome do arquivo de destino começar com .env (incluindo .env.local e semelhantes). No macOS e no Linux, dê permissão de execução com chmod +x .claude/hooks/protect-env.sh.

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "A edição foi bloqueada porque o jq não foi encontrado" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # converte o \ do Windows em /

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH é um arquivo .env e não será editado" >&2
  exit 2
fi
exit 0

A estrutura é nome do evento → um array de matchers e comandos. O matcher identifica nomes de ferramentas: "Edit|Write" corresponde a Edit ou a Write (omiti-lo corresponde a todas as ferramentas). O hook recebe JSON pela entrada padrão, e, para Edit e Write, tool_input.file_path contém o caminho absoluto do arquivo a ser editado. No Windows, esse caminho usa \ como separador, por isso o script o converte para / antes de comparar. Quando o hook bloqueia com o código de saída 2, o texto da saída de erro padrão chega ao Claude como motivo da recusa, e o Claude o lê e procura outra forma de fazer o trabalho. 1 é tratado como erro não bloqueante, e a operação continua; por isso, use 2 quando quiser bloquear. 0 não apresenta objeção, e as verificações normais de permissão seguem.

O script usa bash e jq (o exemplo do guia oficial também pressupõe o jq). No Windows, os hooks são executados no Git Bash ou, se ele não estiver instalado, no PowerShell; portanto, este exemplo precisa do Git Bash. Para que a falta do jq não deixe as edições passarem, o script bloqueia logo no primeiro passo nesse caso.

Hooks conseguem apertar restrições, nunca afrouxá-las. Devolver uma permissão só pula o aviso; as regras de deny sempre vencem. Um deny de PreToolUse continua valendo no modo que pula todas as aprovações, então ele funciona como piso por baixo de tudo o que você afrouxou no capítulo 5.

O teste é igual ao do guia oficial. Peça ao Claude que “acrescente uma linha de comentário ao .env”: a edição é interrompida antes de acontecer, e a mensagem Blocked: volta para o Claude. Confirme também que os arquivos que não são .env continuam podendo ser editados. Se você errar o caminho do script, aparece só um aviso Failed with non-blocking status code e o portão fica aberto; fique atento também a esse aviso. Observe que este exemplo bloqueia apenas as duas ferramentas Edit e Write; reescritas feitas por comandos do Bash ou do PowerShell seguem outro caminho. Amplie o escopo conforme o que quiser bloquear. Os formatos de saída e as diferenças entre eventos estão no guia oficial de Hooks.

Considere o custo desde o início: hooks do tipo command executam automaticamente comandos de shell com as suas permissões de usuário e podem alterar ou excluir qualquer arquivo que a sua conta alcance. A documentação oficial pede que você leia e teste todos os comandos antes de adicioná-los. Configure apenas comandos confiáveis e valide a entrada. Alterações feitas editando diretamente os arquivos de configuração são normalmente aplicadas de forma automática. Veja o registro em /hooks. Se uma alteração não surtir efeito, examine o JSON e o local do arquivo antes de reiniciar a sessão.

subagents — passar trabalho adiante em um contexto separado

Saídas completas de testes e logs enormes podem preencher o contexto com grandes volumes de texto que você só pretendia examinar por alto, empurrando para fora premissas importantes. Subagentes executam esse trabalho em um contexto separado e devolvem um resumo da conclusão. Normalmente têm contexto, instruções e permissões de ferramentas próprios, então o agente principal precisa passar explicitamente as informações necessárias. Uma execução que cria uma ramificação da conversa e herda o histórico do agente principal é uma exceção; isso é diferente de context: fork em uma skill. Como o relatório é um resumo, peça também as evidências necessárias e as questões não resolvidas.

Vale separar — investigação ampla / conferências que produzem muita saída / tarefas autocontidas em que só a conclusão importa
Não vale separar — trabalho sequencial / vaivém frequente / trabalho paralelo tocando o mesmo arquivo / correções que levam um ou dois passos

É um recurso nativo, então funciona sem configuração. Para acrescentar a sua própria definição, coloque-a em .claude/agents/<nome>.md (~/.claude/agents/ para todos os projetos) com name / description / tools / model no front matter YAML. Gerencie com /agents, chame um com @agent-<nome>. Comece pelos nativos de exploração, de planejamento e de uso geral.

O description é a chave para ser chamado. O agente principal o lê para decidir se delega; uma descrição vaga torna a seleção automática menos provável. Seja específico sobre o que ele faz e quando usá-lo: a mesma armadilha existe nas Skills.

Os Agent Teams, fáceis de confundir com isso, são um mecanismo em que várias sessões independentes se coordenam por uma lista de tarefas compartilhada. É uma adesão experimental, desligada por padrão (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Instâncias separadas ficam rodando, então queima muitos tokens, e não dá para aninhar. A diferença é comparada em Subagents vs Agent Teams no Claude Code. Na dúvida, uma sessão única ou subagents.

Skills — transformar procedimentos em ativos

Para a rotina do tipo "sempre faça assim", o que as Skills fazem melhor é serem abertas só quando necessário. Fisicamente é uma pasta construída em torno de um SKILL.md. Ponha name e description no topo, o procedimento em Markdown abaixo disso, e empacote reference/ ou scripts/ junto. Solte a pasta em .claude/skills/ (por projeto) ou ~/.claude/skills/ (em todo lugar) e ela é reconhecida.

A ideia central é a divulgação progressiva. Normalmente, uma lista de nomes e descrições de skills entra no contexto, enquanto o corpo é carregado por seleção automática ou pela invocação explícita /skill-name. Os materiais de apoio são lidos conforme a necessidade. A lista de descrições também consome contexto; com muitas skills, descrições podem ser encurtadas ou omitidas para caber no orçamento. Escreva um description específico e verifique separadamente se a skill foi invocada e se seu procedimento produziu os resultados esperados. Veja O que são as Claude Skills (Agent Skills)? para saber como criar uma.

Em uma linha: CLAUDE.md = premissas carregadas rotineiramente; Skills = procedimentos abertos por seleção automática ou invocação explícita; hooks do tipo command = processamento acionado pelos eventos e condições configurados.

MCP — alcançar sistemas de fora

MCP (Model Context Protocol) é um padrão para acessar dados e operações externos, como valores atuais de um banco de dados ou tickets em um gerenciador de tarefas. A seguir estão dois métodos comuns de conexão. Diagnostique problemas combinando o método de conexão com os detalhes do erro.

Local (stdio): o servidor inicia como processo filho no seu computador. As pistas são o caminho do executável, as variáveis de ambiente necessárias e a saída de erro do servidor
Remoto (HTTP): você se conecta a um servidor por URL. As pistas são URL, rede, erros do servidor e credenciais

Comece pelo status e pelos detalhes em /mcp. failed pode ocorrer tanto em servidores locais quanto remotos. Se Issue: em claude mcp get <name> incluir um código HTTP ou o corpo do erro, leia-os também. needs authentication aponta para a verificação da autenticação; pending approval, para a revisão da aprovação de um servidor do projeto. Se um cabeçalho fixo Authorization for rejeitado com 401/403 durante a conexão, o status será failed mesmo que o problema seja de autenticação. As soluções estão em Erro de conexão MCP no Claude Code: causas e soluções.

Coloque o arquivo compartilhado .mcp.json na raiz do projeto. Use o env de cada servidor para variáveis passadas a um servidor stdio; para autenticação HTTP, use OAuth ou headers, conforme o serviço. Não escreva chaves reais diretamente em arquivos compartilhados; referencie uma variável como ${API_KEY}. Alguns nomes de variáveis, incluindo as credenciais do próprio Claude Code, resultam em strings vazias nas URLs e nos cabeçalhos remotos; os detalhes estão nas regras oficiais de expansão.

As definições de ferramentas são carregadas sob demanda por padrão. Em uma configuração comum com busca de ferramentas ativada, inicialmente só entram no contexto os nomes das ferramentas e as descrições dos servidores. As definições são carregadas antecipadamente quando a busca está desativada, o ambiente não é compatível ou o servidor usa alwaysLoad, entre outros casos. Os resultados também consomem contexto: confira o uso real com /context e desative os servidores que não usa.

plugins — empacotar um conjunto e distribuir

Plugins permitem agrupar skills, definições de subagentes, hooks e configurações MCP para distribuição. Se incluir um manifesto para um plugin, coloque-o em .claude-plugin/plugin.json. A estrutura padrão coloca skills/, agents/, hooks/hooks.json e .mcp.json na raiz do próprio plugin. Não coloque esses itens dentro de .claude-plugin/. Um plugin que usa apenas a estrutura padrão pode omitir o manifesto.

/plugin marketplace add owner/repo   ← registra um catálogo
/plugin install name@marketplace     ← instala itens individuais a partir dele
/plugin list                         ← listar plugins instalados por marketplaces

Essas são as etapas básicas para instalar por um marketplace. Registrar um catálogo não instala plugins por si só. /plugin list lista os plugins instalados por essa via, não todos os disponíveis por outros meios, como diretórios de skills ou sincronização. Os escopos são user (todos os seus projetos), project (configuração compartilhada) e local (só você neste projeto). Mesmo no escopo project, cada integrante precisa instalar os plugins de fontes externas. O escopo managed é administrado centralmente e restringe alterações de configuração pelos usuários. Para criar os seus, consulte Plugins e Marketplace do Claude Code: usar, criar e publicar.

Plugins podem executar código arbitrário com seus privilégios, alerta a documentação oficial. Os itens da comunidade passam pela validação automatizada e pela revisão de segurança da Anthropic, mas isso não garante que se comportem como esperado. Verifique o publicador, o código incluído e os servidores MCP. O projeto de permissões do capítulo 5 também se aplica aqui ao código de outras pessoas.

O que acrescentar primeiro — uma palavra sobre a ordem

São seis, todas alinhadas, mas você não precisa de todas. Acrescentar coisas antes de ter um problema só compra complexidade de configuração. Comece pelo sintoma.

Explicando a mesma coisa toda vez → CLAUDE.md. Skills no lugar disso, se for só para um trabalho específico
Está escrito, mas é ignorado → examine carregamento, escopo e conflitos. Transfira condições verificáveis automaticamente para hooks
O contexto enche rápido → empurre a investigação pesada para subagents / desative servidores MCP de que você não precisa
A IA não alcança a informação → MCP. Conecte um por vez e siga adiante só depois de ver aquele funcionar
Você quer distribuir a mesma configuração → plugins. Empacote só o que já funciona para você
Nada está incomodando → não acrescente nada. Esse é o melhor estado em que se estar

Essa última linha não é piada. Toda extensão acrescenta mais uma coisa que pode dar errado: "o Claude Code está estranho" muitas vezes acaba sendo uma camada que você mesmo acrescentou. É por isso que o trabalho de isolamento do capítulo 4 vem antes.

Resumo

Os critérios são quatro perguntas: pedir basta (CLAUDE.md, Skills) / precisa disparar toda vez (hooks) / você quer isso em um contexto separado (subagents) / você precisa alcançar o lado de fora (MCP). plugins se for distribuir
O CLAUDE.md mantém instruções persistentes. O arquivo da raiz é reinserido após a compactação. Encurtá-lo não garante o cumprimento; verifique carregamento e comportamento separadamente
Hooks do tipo command são executados pelo Claude Code quando as condições configuradas correspondem. Verifique os caminhos de execução e o comportamento de bloqueio; um hook executado depois não pode desfazer uma operação concluída
Os subagents trabalham em um contexto separado e devolvem só um resumo. Servem mal para trabalho sequencial ou vaivém frequente
As Skills usam divulgação progressiva, abrindo seu corpo quando necessário. Escreva descrições específicas para a seleção automática e confira os resultados do procedimento mesmo após uma invocação explícita
MCP é um padrão de acesso externo. Diagnostique problemas combinando o status de /mcp com o método de conexão e os detalhes do erro
Os plugins são a caixa de distribuição. Código de outra pessoa roda com os seus privilégios, então confira o publicador
A ordem de acrescentar começa pelo sintoma. Um por vez, depois que o problema existe

A conversa de comparar e escolher as ferramentas em si está no capítulo 6 do curso de coding com IA, "Ampliar a capacidade com extensões".

Quanto mais você estende, mais ele consome. Por último vem a prática de manter tudo rodando no longo prazo. Siga para o capítulo 7, Custo e limites.