Escolha de Recursos: CLAUDE.md vs Skill vs Hook vs MCP vs Subagent
📚 Navegação da Série: O artigo anterior 29 Equipes de Agentes (Agent Teams) ensinou a orquestrar colaborações multiagentes em paralelo. Este artigo conclui o quarto bloco de estudos—consolidando os conceitos de
CLAUDE.md, Skills, Hooks, MCP e Subagents de forma integrada. Apresentamos uma tabela e uma árvore de decisão para que você possa mapear suas demandas técnicas diretamente ao recurso correto, sem hesitações.
Pessoal, a essa altura você já acumulou diversos recursos de extensão do assistente.
Entre CLAUDE.md, Skills, Hooks, MCP, Subagents e comandos slash, são muitos termos que parecem claros isoladamente. Contudo, na hora de decidir qual aplicar em um caso de uso real, a indecisão é comum. Perguntas frequentes de quem acabou de estudar esses conceitos incluem: "Uso uma Skill ou um Subagent para isso?", "Posso salvar esta instrução simplesmente no CLAUDE.md?"
Na verdade, isso ocorre pela ausência de um mapeamento claro entre demanda e solução. As documentações explicam o funcionamento técnico de cada extensão, mas costumam focar no "o que é" em vez de "quando usar". Este artigo inverte a abordagem—partiremos das suas necessidades para deduzir a ferramenta ideal.
Em termos simples: os artigos anteriores entregaram as ferramentas em suas mãos; este artigo ensinará qual delas escolher no momento da ação.
Ao terminar este artigo, você obterá:
- Resumos de finalidade dos cinco pontos de extensão (e dos comandos slash), definindo propósitos, vantagens e restrições
- Uma tabela comparativa de tomada de decisões para mapear demandas técnicas aos recursos
- Uma árvore de decisão intuitiva para identificar o recurso ideal por meio de perguntas simples
- Análises detalhadas dos termos que mais geram confusão (Skill vs Subagent,
CLAUDE.mdvs Skill, Hook vs Regras de Permissão) - Orientações de como combinar esses recursos e empacotá-los em Plugins distribuíveis
01 O panorama geral: pontos de extensão no ciclo do agente
Antes de iniciar a escolha, entenda a arquitetura: seus recursos não são opções independentes isoladas, mas sim chaves acionadas em diferentes etapas do fluxo de processamento do Claude.
No Artigo 03, analisamos o "ciclo do agente" do Claude Code—estruturado em "pensar, agir e inspecionar". Nossos seis pontos de extensão (CLAUDE.md, Skills, comandos slash, MCP, Subagents e Hooks) são injetados nesse ciclo: alguns adicionam contexto inicial antes da fase de raciocínio, outros conectam o modelo a APIs externas ou instâncias isoladas durante a execução, e outros operam de forma autônoma em eventos específicos. A documentação oficial aponta:
Extensões são injetadas em diferentes partes do ciclo do agente.
Analogia: A triagem hospitalar. Ao buscar atendimento médico, você não escolhe um especialista aleatoriamente; passa pelo painel de triagem para relatar os sintomas—que direciona dores de cabeça ao neurologista, problemas estomacais ao gastroenterologista e exames ao setor de radiologia. O painel não realiza o tratamento, ele apenas garante o encaminhamento correto. Este artigo funciona como essa triagem: você apresenta a sua demanda de desenvolvimento, e nós indicamos o recurso correspondente.
No dia a dia, suas dúvidas se resumem a poucas intenções: "quero que ele siga esta diretriz em todas as sessões", "desejo que ele carregue esta documentação apenas sob demanda", "preciso que esta ação ocorra autonomamente em um evento específico" ou "quero que ele leia dados de APIs externas". Definida a intenção, o direcionamento técnico torna-se simples. Apresentaremos as ferramentas detalhadamente nas próximas seções, consolidando o conhecimento em tabelas e árvores de decisão.
💡 Resumo em uma frase: As seis extensões não são opções equivalentes, mas sim chaves de controle que atuam nas fases de raciocínio, execução e inspeção do assistente; a escolha depende de onde sua demanda se encaixa no fluxo.
02 Finalidades de cada extensão
Mapearemos o foco de cada extensão para fundamentar as tabelas de decisão a seguir. Cada recurso é associado a seu caso de uso padrão:
CLAUDE.md — Diretrizes persistentes de repositório: convenções de código, comandos de compilação ou regras de governança ("use sempre pnpm", "rode lints antes de commitar") que devem estar ativas em todas as sessões. Esse arquivo é lido no boot inicial do chat.
Skills — Habilidades e documentações sob demanda: referências reutilizáveis (como manuais de design de APIs, checklists de homologação ou roteiros de depuração). Ocupam apenas espaço mínimo na inicialização e são carregadas na totalidade sob demanda; também podem ser invocadas via comandos slash /<nome>.
Comandos slash — Rotinas de acionamento manual: representam o acionamento direto de uma Skill via console (usando /<nome>). A diferença reside no iniciador: nas Skills comuns, o Claude decide dinamicamente quando carregá-las; nos comandos slash, você força a execução digitando /deploy no chat.
MCP — Integrações com APIs externas: conexões com bancos de dados, envios de mensagens no Slack ou interações com o navegador. Use o Model Context Protocol sempre que o Claude precisar de dados ou ferramentas de serviços externos (Artigo 22).
Subagents — Instâncias isoladas para processamento de logs: execução de buscas amplas ou leituras de dezenas de arquivos, onde você precisa apenas do relatório final e deseja evitar a poluição de contexto no chat principal (Artigo 23). O subagente processa os dados em segundo plano e retorna apenas o resumo.
Hooks — Automações de ciclo de vida: rotinas que executam autonomamente baseando-se em eventos do terminal (como "após modificação de arquivos" ou "no início da sessão"). Rodam obrigatoriamente lints locais, bloqueios de comandos inseguros ou envios de alertas. Diferem de diretrizes comuns porque não dependem do raciocínio da IA para funcionarem; sua execução é estrita.
O conceito de Hooks será aprofundado no Artigo 33, onde explicaremos os gatilhos e a sintaxe de desenvolvimento. Por hora, entenda-o como rotinas automatizadas orientadas a eventos.
Abaixo está o quadro comparativo consolidado das propriedades de cada extensão:
| Extensão | Finalidade padrão | Iniciador da chamada | Custo permanente de tokens |
|---|---|---|---|
| CLAUDE.md | Diretrizes e padrões obrigatórios de repositório | Automático (carregado no boot) | Alto (texto completo residente) |
| Skills | Manuais de estilo e instruções sob demanda | Claude (dinâmico) ou Usuário (slash) | Baixo (apenas metadados de descrição) |
| Comandos slash | Execuções manuais estritas de rotinas do console | Usuário (via /<nome>) | Baixo (equivalente a metadados de descrição) |
| MCP | Leitura de dados de servidores externos | Claude (associado a chamadas de ferramentas) | Baixo (esboços de definições de ferramentas) |
| Subagents | Isolamento de histórico ou tarefas paralelas pesadas | Claude ou Usuário (delegação de subchat) | Inexistente no console principal (janela dedicada) |
| Hooks | Automações estruturadas disparadas por eventos locais | Eventos de ciclo de vida do terminal | Nulo (execução via script local) |
As chaves "Iniciador da chamada" e "Custo permanente de tokens" são os principais critérios de escolha, definindo o nível de controle operacional e a eficiência de tokens do projeto.
💡 Resumo em uma frase: Padronize regras no
CLAUDE.md, salve manuais em Skills, crie atalhos manuais com comandos slash, conecte APIs externas via MCP, isole buscas longas em Subagents e amarre rotinas de terminal em Hooks.
03 Tabela comparativa de tomada de decisões
O quadro a seguir mapeia intenções comuns de desenvolvimento às respectivas soluções recomendadas, detalhando os motivos de escolha:
| Intenção técnica (Sua necessidade) | Solução sugerida | Justificativa de uso (evite escolhas incorretas) |
|---|---|---|
| "Quero que ele siga este padrão de nomenclatura em todas as conversas" | CLAUDE.md | Diretriz persistente do repositório que o modelo deve ler no início de cada chat. |
| "Quero disponibilizar este manual de estilos para consulta opcional" | Skills | Referências extensas que devem poupar tokens no boot, sendo lidas apenas sob demanda. |
"Quero digitar /deploy para rodar os scripts de homologação" | Comandos slash (Skill) | Rotina de execução manual complexa com etapas de terminal associadas. |
| "Quero que ele leia dados do PostgreSQL ou notifique no Slack" | MCP | Necessidade de conectar serviços e dados externos que excedem os limites das ferramentas padrão. |
| "Quero que ele inspecione uma pasta inteira de logs e me traga apenas o resumo" | Subagents | Requer isolamento de histórico para evitar consumo excessivo e poluição de tokens no chat ativo. |
| "Quero executar essas duas pesquisas de dependências em paralelo" | Subagents (Paralelos) | Atribuição de tarefas concorrentes que rodam em contextos próprios e retornam apenas conclusões. |
| "Quero executar o linter local sempre que um arquivo for editado" | Hooks (PostToolUse) | Execução automatizada associada a eventos del console, sem depender do raciocínio da IA. |
"Quero bloquear comandos como rm -rf com segurança" | Hooks (PreToolUse) ou Regras de Acesso | Exige imposição física no console, pois instruções textuais em arquivos Markdown não garantem segurança. |
| "Ele continua sugerindo a biblioteca incorreta mesmo após minhas correções" | CLAUDE.md | Problemas recorrentes de aderência devem ser salvos como regras permanentes de boot, não resolvidos em chats avulsos. |
| "Digito a mesma instrução de briefing de tarefas todos os dias" | Skills | Instruções de chat repetitivas devem ser salvas como atalhos para agilizar a inicialização. |
| "Quero distribuir essa suíte de automações para outros repositórios" | Plugins (Empacotamento) | Combina Skills, Hooks, Subagents e MCPs em um único pacote distribuível e versionado. |
Essa divisão segue a lógica de otimização contínua sugerida oficialmente: identificar repetições frequentes (instruções coladas repetidamente, lints rodados manualmente, erros frequentes) é o sinal para modularizar e consolidar o fluxo no recurso correto.
Evite o erro clássico de salvar documentações extensas no CLAUDE.md. Salvar uma lista de APIs de trezentas linhas no CLAUDE.md para "mantê-la acessível" consome espaço útil no boot inicial de todas as conversas, além de confundir o modelo com detalhes excessivos. A abordagem correta é migrar a lista de APIs para uma Skill e adicionar uma breve referência no CLAUDE.md ("convenções de API salvas na Skill api-skill"). Isso otimiza o uso de tokens. A documentação oficial orienta:
Mantenha o CLAUDE.md abaixo de 200 linhas. Se ele começar a crescer, mova o conteúdo de referência para as skills.
💡 Resumo em uma frase: Ao planejar um recurso, traduza sua necessidade para as intenções do quadro e localize a solução recomendada; priorize regras persistentes no
CLAUDE.md, consultas em Skills, integrações no MCP, isolamento em Subagents e automações em Hooks.
04 A árvore de decisão estruturada
Caso prefira um fluxo de exclusão passo a passo para clarear as ideias, siga esta árvore de decisão respondendo a perguntas simples de sim ou não:
O diagrama ilustra o fluxo de triagem lógica: partindo de validações de conexões externas e regras rígidas de segurança, passando pelo escopo de isolamento de histórico, até determinar o nível de recorrência no contexto.
Podemos resumir a lógica da árvore nas seguintes perguntas ordenadas:
1. A tarefa exige conexão com dados ou serviços de APIs externas?
Sim (ler bancos de dados, Slack, integrações web): use MCP. Este é o critério mais direto.
2. O bloqueio ou ação exige execução obrigatória sem depender da aderência da IA?
Sim (bloquear edições no .env, rejeitar exclusões no console, lints automatizados): use Hooks (ou regras de acesso). Chaves textuais no CLAUDE.md atuam como recomendações leves; para garantir a conformidade no terminal, implemente a restrição via Hook.
3. O processamento gerará logs extensos e exige isolamento de histórico?
Sim (leitura massiva de logs, buscas estruturais amplas, tarefas paralelas): use Subagents. O processamento ocorre em subchats em segundo plano, retornando apenas as conclusões.
Se a necessidade for meramente de orientação de comportamento, resta a última pergunta:
4. A instrução deve estar ativa em todas as sessões ou ser consultada apenas sob demanda?
- Regras de repositório constantes (gerenciador de pacotes, compilações): use o CLAUDE.md.
- Manuais de consulta opcional (guias de API, deploys, debugs): crie uma Skill.
- Para atalhos de chamada manual de rotinas complexas da Skill: adicione o prefixo
/<nome>no console para usá-la como Comando slash.
Seguir essa sequência de triagem isola as intenções com facilidade, otimizando a escolha do recurso.
💡 Resumo em uma frase: A triagem lógica segue a ordem: Conexões externas? → Execução obrigatória? → Isolamento de histórico? → Carregamento permanente ou opcional?
05 Esclarecendo conceitos semelhantes
Alguns recursos possuem propriedades parecidas. Detalhamos abaixo as três distinções mais questionadas para evitar sobreposições de uso.
Skills versus Subagents
Ambos suportam a estruturação de fluxos complexos, mas operam em níveis de contexto diferentes.
Analogia: O manual técnico vs O especialista externo. Uma Skill é um guia de instruções carregado diretamente na sua conversa ativa quando necessário. O Subagent é um assistente independente enviado para executar uma tarefa em uma sala separada, retornando apenas as conclusões e preservando sua mesa limpa.
A diferença técnica reside no gerenciamento da janela de contexto:
| Propriedade | Skills | Subagents |
|---|---|---|
| Definição | Guias de consulta e instruções reutilizáveis | Assistentes isolados com janela de tokens própria |
| Destino do texto | Carregado diretamente no chat ativo | Processado no console secundário; envia apenas resumos |
| Impacto no chat principal | Consome tokens e permanece residente na conversa | Isolado; protege a janela de contexto principal |
| Caso de uso ideal | Documentações de APIs e atalhos de rotinas | Leituras de logs massivas, buscas amplas e concorrência |
Use Skills para injetar instruções no seu chat ativo e Subagents para processar tarefas longas em segundo plano, poupando seu contexto. É possível combinar ambos: instanciar um Subagent que carrega uma Skill específica para guiar suas ações.
CLAUDE.md versus Skills
Ambos armazenam diretrizes comportamentais, diferenciando-se pela frequência de leitura:
| Propriedade | CLAUDE.md | Skills |
|---|---|---|
| Carregamento | Automático no boot inicial de todo chat | Dinâmico sob demanda ou invocação manual |
| Controle de versão | Versionado no git do projeto | Versionado no git (local) ou privado (global) |
| Caso de uso ideal | Padrões e regras persistentes de governança | Documentações extensas e roteiros de consulta |
A regra é simples: regras obrigatórias permanentes vão no CLAUDE.md; documentações de consulta opcional vão em Skills. Evite congestionar o boot inicial salvando tabelas de dados ou listas de códigos no CLAUDE.md.
Hooks versus Regras de Permissão
Ambos são classificados como chaves de proteção e segurança (hard constraints), mas operam em níveis de controle distintos:
Tanto Hooks quanto regras de permissão atuam no terminal do Claude Code de forma estrita, diferindo de simples pedidos no CLAUDE.md. A documentação oficial sinaliza:
CLAUDE.md 或 skill 中的「永远不要编辑
.env」之类的说明是请求，而不是保证。阻止编辑的PreToolUsehook 是强制执行。
Recomendações como "nunca edite o .env" no CLAUDE.md ou em skills são apenas pedidos, não garantias. Um hook PreToolUse que bloqueia a edição é uma imposição física.
A diferença reside na complexidade da lógica aplicada:
- Regras de Permissão (Declarativas): gerenciam de forma simples se uma ferramenta ou comando está liberado (ex: declarar
"deny": ["Bash(rm -rf *)"]nosettings.json). Indicado para bloqueios simples de sim ou não. - Hooks (Procedimentais): executam scripts locais completos associados ao evento. Além de bloquear a ação, podem registrar logs locais, enviar mensagens de alerta no Slack ou modificar parâmetros dinamicamente. Indicado para validações complexas ou fluxos que exigem ações secundárias.
Regra prática sugerida: use Regras de Permissão declarativas para bloqueios básicos de segurança; adote Hooks procedimentais apenas se precisar executar ações adicionais ou validações complexas associadas ao bloqueio.
💡 Resumo em uma frase: Skills expõem instruções no chat e Subagents isolam o histórico; CLAUDE.md carrega no boot e Skills lêem sob demanda; Regras de Permissão gerenciam bloqueios básicos e Hooks executam rotinas complexas em eventos—três divisões práticas para seu fluxo de trabalho.
06 A combinação de recursos em produção
Mapear a ferramenta ideal não significa usar apenas um recurso por vez. Em ambientes reais de produção, as extensões trabalham de forma complementar.
Exemplos práticos de combinações recomendadas pela documentação:
| Combinação | Mecânica de integração | Caso de uso real |
|---|---|---|
| Skills + MCP | O MCP conecta a API e a Skill orienta as consultas lógicas | O servidor MCP libera o acesso ao PostgreSQL e a Skill detalha o esquema das tabelas e chaves primárias. |
| Skills + Subagents | A Skill inicia Subagents em paralelo sob demanda | Uma Skill de auditoria /audit inicia instâncias secundárias isoladas para checar performance e segurança. |
| CLAUDE.md + Skills | Regras de governança gerais no boot e guias detalhados sob demanda | O CLAUDE.md define que commits devem seguir o padrão corporativo e a Skill detalha a lista de escopos de commit. |
| Hooks + MCP | Eventos locais disparam chamadas a APIs externas via MCP | O ganho de compilação local dispara um Hook PostToolUse que aciona a API do Slack via MCP para notificar a equipe. |
A combinação de "Skills + MCP" ilustra essa dinâmica: o servidor MCP conecta o Claude Code ao banco de dados, mas não instrui o modelo sobre quais colunas ou regras de indexação utilizar; a Skill de dados detalha a modelagem lógica das tabelas, mas não possui conexões de terminal para ler as linhas. Somar os dois recursos provê acesso físico e orientação lógica simultaneamente, agilizando a escrita de queries assertivas.
Para distribuir uma suíte integrada de automações para outros projetos ou desenvolvedores, utilize o formato de Plugins (Artigo 24)—que atua como o contêiner de empacotamento.
Analogia: A mala de viagem. Em vez de carregar chaves, cabos e utilitários soltos nos bolsos, você organiza tudo em uma mala de ferramentas unificada. O Plugin funciona como essa mala—agrupando Skills, Hooks, Subagents e configurações de servidores MCP em uma pasta que pode ser instalada com um comando, evitando conflitos de nomes graças ao uso de namespaces.
O Plugin agrupa as skills, hooks, subagents e servidores MCP em uma única unidade instalável.
Lembre-se do papel estrutural: os recursos gerenciam as automações de terminal, e o Plugin encapsula as configurações para distribuição e reuso.
💡 Resumo em uma frase: O desenvolvimento de ambiente exige a combinação de recursos (como conectar MCPs a orientações de Skills); use Plugins para empacotar e compartilhar a suíte de automações com facilidade.
07 Exercício prático: Triagem de demandas
Vamos exercitar a tomada de decisões com base em solicitações reais de desenvolvimento. Identifique a melhor solução para cada item a seguir usando a árvore de decisão:
Passo 1: Analisar a lista de demandas:
Lista de Demandas técnicas:
A. Exigir o uso exclusivo do pnpm no projeto, evitando chamadas do npm.
B. Habilitar consultas diretas na base de dados PostgreSQL interna da equipe.
C. Automatizar o fluxo de lançamento de versões (gerar tag, atualizar changelog e push) em um único comando manual.
D. Formatar automaticamente arquivos alterados usando o Prettier após edições do Claude.
E. Mapear a pasta de utilitários e identificar funções legadas inativas sem poluir o chat.
F. Disponibilizar a lista de códigos de erro internos da empresa para consultas eventuais da IA.
G. Bloquear a execução de comandos de modificação em tabelas de produção locais.Passo 2: Resolver os casos usando a árvore de decisão (externalizar conexões, bloquear execuções, avaliar janelas de contexto).
Dedique alguns instantes para definir suas respostas antes de rolar a página.
Passo 3: Conferir as soluções sugeridas:
Compare suas escolhas com o gabarito estruturado abaixo:
| Item | Recurso recomendado | Justificativa estrutural (Árvore de decisão) |
|---|---|---|
| A Padrão pnpm | CLAUDE.md | Regra constante de repositório que deve ser lida no boot inicial (carregamento permanente). |
| B PostgreSQL | MCP | Exige integração física com sistemas e bases de dados externos. |
| C Versões | Comando slash | Rotina complexa de terminal invocada por ação manual do usuário (Skill com /release). |
| D Prettier | Hooks (PostToolUse) | Execução obrigatória automatizada associada a eventos do console. |
| E Funções inativas | Subagents | Exige isolamento de histórico para evitar consumo excessivo de tokens no chat ativo. |
| F Erros corporativos | Skills | Documentação opcional volumosa que deve ser lida apenas sob demanda. |
| G Bloquear banco | Regras de Acesso ou Hooks | Exige imposição física no console (use regras declarativas por padrão). |
Se você diferenciou corretamente os caminhos A e F (boot vs sob demanda) e D e G (automações pós-ferramenta vs restrições declarativas de segurança), sua triagem lúdica está sedimentada. Use esse mesmo raciocínio ao projetar o ambiente de novos repositórios.
Esta triagem de demandas exige prática para se tornar um hábito de desenvolvimento; priorize a economia de tokens na janela de contexto principal para balizar suas escolhas.
08 Resumo
Resumo das diretrizes de triagem:
| Intenção técnica | Extensão recomendada | Ponto-chave operacional |
|---|---|---|
| Padrões persistentes de repositório | CLAUDE.md | Regras lidas no boot; mantenha o arquivo abaixo de 200 linhas. |
| Consultas opcionais ou atalhos de rotinas | Skills / Comandos slash | Metadados compactos em espera e instruções carregadas sob demanda. |
| Acesso a dados e ferramentas de terceiros | MCP | Conexão física com serviços externos. |
| Processamento longo de arquivos | Subagents | Execução paralela em subchats locais com retorno de conclusões. |
| Automações disparadas por eventos locais | Hooks | Imposição de rotinas físicas independentes da IA no terminal. |
| Compartilhar e versionar a suíte | Plugins | Contêiner de empacotamento para distribuição. |
Agora você deve ser capaz de: Avaliar novas demandas técnicas usando o fluxo da árvore de decisão, diferenciar com precisão o escopo de uso de janelas de contexto de Skills e Subagents, proteger o console local por meio de Regras de Acesso e modularizar documentações volumosas de forma a economizar tokens. A triagem correta garante ambientes de desenvolvimento leves e responsivos.
A partir do próximo capítulo, iniciaremos o bloco "Configurações de Sistema". O Artigo 31 "Configurações no settings.json (Settings JSON)" abordará as regras de precedência de arquivos locais e globais do Claude Code. Veremos como os escopos de usuário e projeto interagem e como estruturar suas chaves de configuração com segurança. Como chaves idênticas salvas em caminhos diferentes podem ter comportamentos opostos? Descubra a seguir.