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.

Q1
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)

Q2
Precisa disparar toda vez?

Se uma única falha já é problema, barre por mecanismo. → hooks. Eles rodam sem o modelo decidir nada.

Q3
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

Q4
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 — memória que persiste, até ficar longa demais

O CLAUDE.md, colocado na raiz de um projeto, é um arquivo que é lido automaticamente no início de toda sessão (~/.claude/CLAUDE.md se você quiser em todos os projetos). Por ser um arquivo, ele é imune ao problema do capítulo 1 de "o começo é esquecido quando as coisas ficam longas". É onde moram as coisas que você explica toda santa vez.

"Ele diz que leu o arquivo e depois ignora" não é preguiça, e sim um problema estrutural, com três causas.

  • O meio afunda — instruções no meio de um documento longo são as mais fáceis de perder, e quanto mais longo você o faz, mais as regras do meio deixam de existir na prática
  • A compactação resume tudo embora — assim que a compactação roda, as regras operacionais de detalhe são achatadas. É por isso que as violações se acumulam no fim de uma sessão
  • A instrução mais recente vence — "só commita isso" passa por cima de um procedimento de verificação lido centenas de turnos antes

A correção é cortar. Como regra prática, o que funciona de forma confiável é algo em torno de 100 a 150 linhas. Passando disso, mantenha no topo só as regras inquebráveis e mova o detalhe para arquivos separados (duplicação sai do compasso, então mantenha uma única cópia canônica). Marque como "CRITICAL" apenas as que não dá para largar e escreva-as de modo que alguém de fora consiga julgar o cumprimento: "três linhas ou menos", não "escreva com capricho".

"Eu li" não é prova. A única coisa pela qual julgar é como ele se comporta depois. Uma regra que segue sendo ignorada por mais que você a reescreva não é um problema de redação: é trabalho para a próxima seção.

hooks — não um pedido, uma certeza

"Não reescreva o .env": coloque isso no CLAUDE.md e será respeitado nove em cada dez vezes. Se a uma vez em dez não machuca você, texto basta. Se machuca, use hooks — é essa a bifurcação.

Hooks são comandos de shell que rodam automaticamente em pontos fixos. Quem os roda não é o modelo, e sim o próprio Claude Code, o arcabouço, então eles disparam sem esperar por nenhum julgamento. O quadro completo está em O que são os hooks do Claude Code. São nove pontos de disparo padrão.

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 de uma ferramenta ter êxito = formatação [pode bloquear] 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]

"Pode bloquear" quer dizer que você consegue interromper a ação naquele ponto. Barre comandos perigosos na porta com o PreToolUse, formate automaticamente com o PostToolUse: esses dois são a entrada de costume. A configuração vai sob a chave "hooks" no settings.json, e o lugar em que você põe o arquivo define o escopo (~/.claude/ = você, .claude/ = compartilhado, settings.local.json = só você).

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "..." } ] } ] } }

O formato é nome do evento → um array de matcher mais comando. O matcher é o nome da ferramenta alvo (separado por |, como em "Edit|Write"; omita para casar com tudo). Um hook recebe JSON na entrada padrão e responde com um código de saída: 0 para sucesso, 2 para bloquear (a saída de erro padrão é entregue ao Claude). O caminho do arquivo alvo também está nesse JSON de entrada, então dá para escrever "pare se o caminho for este".

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 preço, de saída. Hooks rodam comandos de shell arbitrários automaticamente, com os seus privilégios. A documentação oficial diz isso com todas as letras: a responsabilidade é inteiramente sua. Configure só o que você confia e valide a entrada. A configuração é fixada quando a sessão começa, então, quando você corrigiu algo e nada muda, abra uma sessão nova.

subagents — passar trabalho adiante em um contexto separado

A saída inteira de uma rodada de testes, um log gigante: quando texto em massa que você só ia passar o olho se acumula, as premissas que realmente importam são empurradas para fora. Os subagents rodam esse trabalho em um contexto separado e devolvem só um resumo da conclusão. Cada um tem a própria janela de contexto, o próprio prompt de sistema e as próprias permissões de ferramenta, e nenhum deles vê o seu histórico de conversa, então os destroços de uma investigação nunca voltam para a linha principal.

  • 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, então um description vago nunca é chamado. Seja específico sobre o que ele faz e quando usá-lo: a mesma armadilha espera você 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.

O coração disso é a divulgação progressiva. Tudo o que é lido no início de uma sessão é o curto description de cada skill; o corpo e os materiais dela carregam só quando um pedido casa. É por isso que você pode instalar dezenas delas e mal encher o seu contexto do dia a dia, a diferença decisiva em relação ao CLAUDE.md, que está sempre ali por inteiro. O outro lado da moeda: se nada casar, ela nunca abre. Com um description vago, o procedimento que você escreveu é como se não existisse. Como escrever um está em O que são as Claude Skills (Agent Skills).

Em uma linha. CLAUDE.md = premissas sempre lidas, Skills = procedimentos que o Claude decide abrir, hooks = processamento que sempre roda.

MCP — alcançar sistemas de fora

As três até aqui eram extensões que mudam o modo de funcionar. Só o MCP (Model Context Protocol) amplia o que ele consegue tocar: é um padrão para alcançar coisas que a IA estruturalmente não tem como saber, como os valores atuais de um banco de dados ou um chamado em um gerenciador de tarefas. Há dois formatos de conexão, e eles travam em lugares diferentes.

  • Local (stdio) — o servidor inicia como subprocesso na sua própria máquina. O que trava é a inicialização em si (caminhos, variáveis de ambiente, resolução do comando)
  • Remoto (HTTP) — você se conecta por URL a um servidor na nuvem. O que trava é quase sempre a autenticação, ou seja, um 401 ou um 403 voltando

Então não jogue tudo no balaio do "não conecta"; comece conferindo o status com /mcp. failed significa inicialização local, needs authentication significa autenticação remota, pending approval significa que ele está esperando por você: o status decide o movimento. As correções estão reunidas em Erros de conexão de servidor MCP no Claude Code: causas e soluções.

Algumas armadilhas próprias. A configuração compartilhada .mcp.json fica na raiz do repositório (não sob .claude/, nem dentro do settings.json), e as chaves de API vão no env de cada servidor. No Windows, o npx é na verdade um arquivo de lote, então passá-lo pelo cmd como /c npx ... faz funcionar.

Todo servidor que você conecta consome contexto. Só as definições de ferramenta já se acumulam e apertam a janela. Desativar os servidores que você não está usando é o hábito seguro.

plugins — empacotar um conjunto e distribuir

Assim que skills, definições de subagent, hooks e configuração de MCP começam a se espalhar, os plugins são o jeito de empacotar tudo em algo que dá para distribuir. As regras de diretório são a parte fácil de errar. O manifesto é o .claude-plugin/plugin.json, e o .claude-plugin/ não guarda mais nada. skills/, agents/, hooks/hooks.json e .mcp.json ficam na raiz.

/plugin marketplace add owner/repo ← registra um catálogo /plugin install name@marketplace ← instala itens individuais a partir dele /plugin list ← confere o que está instalado

A instalação tem dois passos. Registre o catálogo e então instale os plugins dele um a um: acrescentar o catálogo sozinho não instala nada. Os escopos são user (todos os projetos) / project (todo mundo que trabalha nele) / local (só você) / managed (distribuído por um administrador, não editável), e project é o indicado para manter um time em sintonia. Construir o seu próprio está em O que são os plugins e o marketplace do Claude Code.

Um plugin pode rodar código arbitrário com os seus privilégios: a documentação oficial diz isso abertamente. A Anthropic não audita plugins de terceiros nem os servidores MCP que vêm empacotados com eles. Instale apenas o que vem de um publicador em quem você confia. O desenho de permissões do capítulo 5 volta aqui na forma de código escrito por outra pessoa.

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 e é ignorado → corte primeiro. Mova para hooks só o que causa dano real
  • 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 é memória que atravessa sessões. Deixe crescer e o meio afunda, a compactação o dilui e a instrução mais recente o vence. Corte e deixe as prioridades explícitas
  • Os hooks são executados pelo arcabouço, então nenhum julgamento entra na jogada. Eles apertam restrições, mas não as afrouxam
  • Os subagents trabalham em um contexto separado e devolvem só um resumo. Servem mal para trabalho sequencial ou vaivém frequente
  • As Skills abrem só quando o description casa: divulgação progressiva. Acrescentar mais continua barato, mas um description vago nunca é chamado
  • O MCP é o padrão que amplia o que ele consegue tocar. O status do /mcp decide o movimento
  • 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

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.