Os quatro mecanismos que estendem o Claude Code resolvem problemas genuinamente separados. Uma habilidade ensina o Claude como você quer que algo seja feito. Um hook garante que algo aconteça, independentemente do que o Claude decida. Um subagent protege o contexto da conversa principal delegando trabalho focado a um processo limpo à parte. Um servidor MCP dá ao Claude acesso a um sistema que ele literalmente não consegue alcançar sem ele. Escolha o mecanismo errado e você acaba com uma "regra" que o modelo pode ignorar silenciosamente, ou uma dependência MCP acoplada onde instruções simples teriam funcionado.
Escolha um Mecanismo pelo Trabalho
Comece com uma única pergunta diagnóstica: o que realmente está faltando?
Se a resposta for "o Claude não sabe como eu quero que isso seja feito", é uma habilidade. Formato de commit, templates de descrição de PR, política de lint, checklists de revisão. Tudo isso é conhecimento empacotado, carregado sob demanda quando é relevante, e roda na sua sessão existente sem nenhuma dependência externa.
Se a resposta for "algo deve acontecer em um ponto fixo e não posso confiar que o modelo se lembre", é um hook. Hooks disparam em eventos de ciclo de vida como PreToolUse ou PostToolUse e rodam fora do contexto do Claude inteiramente. O modelo não pode sobrepor-se a eles. CodingNomads descreve bem: hooks rodam deterministicamente sem envolvimento de LLM e sem custo de contexto.
Se a resposta for "essa sub-tarefa levaria 40 leituras de arquivo para minha thread principal", é um subagent. Janela de contexto separada, orçamento de tokens próprio, reporta um resumo. Silencioso e focado.
Se a resposta for "o Claude precisa realmente tocar em um sistema que não consegue alcançar", é um servidor MCP. Leituras de banco de dados, posts no Slack, APIs internas, páginas do Notion. Esses não são problemas de conhecimento, são problemas de conectividade, e apenas MCP resolve isso.
E CLAUDE.md fica acima de todos eles como a camada sempre ativa. Toda sessão a lê automaticamente. Mantenha-a com menos de 200 linhas, de acordo com a própria orientação da Anthropic, senão restrições importantes ficam enterradas e ignoradas.
Instruções, Acesso a Ferramentas, Eventos e Contexto Isolado
O que cada mecanismo realmente controla:
- Habilidades: instruções e contexto, carregados sob demanda na conversa atual. Sem chamadas externas. Sem disparo de evento. O modelo decide quando uma habilidade é relevante com base na descrição no seu frontmatter.
- Servidores MCP: acesso a ferramentas. O Claude chama ferramentas MCP da mesma forma que chama qualquer ferramenta, mas a execução acontece em um processo separado via JSON-RPC. Um servidor MCP conecta o Claude a sistemas externos; uma habilidade diz como usá-los bem uma vez conectado.
- Hooks: eventos de ciclo de vida. SessionStart, PreToolUse, PostToolUse,
PreCompact. Eles rodam deterministicamente. Um hook que bloqueia um comando destrutivo o bloqueará toda vez, quer o Claude tenha achado uma boa ideia ou não. - Subagents: contexto isolado. Você entrega um subagent uma tarefa; ele trabalha independentemente; retorna um resultado. Um subagent que escreve testes não precisa saber sobre seu pipeline de deployment. Um subagent de documentação não precisa de seu schema de banco de dados. Essa separação é o ponto inteiro.
Habilidades e comandos merecem uma breve nota aqui porque são fáceis de confundir. Conforme a documentação oficial de habilidades, comandos customizados são incorporados em habilidades, não um sexto sistema separado. Eles compartilham o mesmo modelo de autoria SKILL.md. Mais sobre isso na próxima seção.
O resumo da Inventive HQ coloca claramente: "Uma habilidade muda o comportamento, um subagent protege o contexto, um servidor MCP adiciona capacidade, e um hook garante que uma ação rode deterministicamente em um evento, independentemente do que o modelo decida fazer."
Onde Slash Commands se Encaixam nas Skills
Custom slash commands não são um mecanismo separado ao lado das skills. Eles são a superfície de invocação das skills. Quando você digita /deploy ou /review, está acionando uma skill pelo nome. Essa skill carrega as instruções, qualquer arquivo de referência vinculado e o contexto para como Claude deve lidar com essa tarefa.
A tarefa de autoria (escrever um SKILL.md com boas descrições no frontmatter), a tarefa de busca de comando (decidir qual nome de comando expor) e a tarefa de comparação de mecanismo (escolher entre skills e hooks) são três preocupações diferentes do leitor. Eles compartilham um formato de arquivo, o que é parte do motivo da confusão persistir.
Se você está decidindo se deve usar uma skill, a pergunta é sempre: isso é conhecimento que eu teria que redigitar, ou é algo que precisa ser acionado por um evento independentemente da entrada? O primeiro é uma skill, possivelmente exposta como um comando. O segundo é um hook.
Para uma análise mais profunda de como CLAUDE.md alimenta o contexto do projeto em cada sessão, o guia CLAUDE.md para agências cobre o escopo e a estrutura de arquivos em detalhes.
Compor Mecanismos para uma Tarefa de Repositório
A maioria das configurações do mundo real não escolhe um mecanismo e pronto. Elas compõem dois ou três. Aqui está um cenário ilustrativo mostrando como isso funciona para um fluxo de PR:
| Tarefa | Mecanismo | Motivo |
|---|---|---|
| Enforçar formato de descrição de PR | Skill | Know-how empacotado; carrega quando Claude escreve um PR |
| Buscar contexto de ticket do Linear | Servidor MCP | Sistema externo que Claude não consegue alcançar nativamente |
| Escanear >20 arquivos para análise de impacto | Subagente | Mantém a thread principal limpa; retorna um resumo focado |
| Bloquear commits se testes falharem | Hook | Garantia determinística; não pode ser questionada pelo modelo |
| Regra de nomenclatura de branch sempre ativa | CLAUDE.md | Nunca condicional; necessário em cada sessão |
| Executar linter automaticamente antes de gravar arquivo | Hook no PreToolUse | Precisa disparar em um evento, não no julgamento do Claude |
O exemplo do linter vale a pena pausar. O resumo do Moeed captura bem: "A parte 'executar o linter' é uma habilidade, Claude consegue fazer, você só quer consistência. A parte 'fazer commit apenas se passar' é um hook, isso é uma garantia, não uma diretriz. Elas se complementam."
Esse é o modelo mental prático. Habilidades e hooks geralmente funcionam na mesma tarefa de ângulos diferentes.
Escolhas Erradas Comuns e Como Corrigi-las
Alguns padrões aparecem repetidamente:
- Servidor MCP para algo que era apenas conhecimento. Se você se vê iniciando um servidor MCP para que Claude "acesse" seu guia de estilo, pare. Isso é uma habilidade. MCP é para conectividade em sistemas ativos, não para carregar documentação em markdown.
- Regra CLAUDE.md que é na verdade um hook. Colocar "nunca execute rm -rf" em CLAUDE.md é uma sugestão que o modelo tecnicamente pode contornar. Um hook
PreToolUseque bloqueia a ferramenta Bash nesse padrão é um parador inegociável. Se uma regra precisa ser garantida, pertence a um hook, não ao contexto. - Habilidade para uma tarefa que precisa de seu próprio orçamento de contexto. Se o trabalho envolve ler dezenas de arquivos, o vazamento de tokens na sua sessão principal se acumula rápido. Inicie um subagende. Ele recebe um prompt focado, faz o trabalho e retorna um resumo. Seu contexto principal permanece coerente.
- Subagende para algo que simplesmente precisava de uma instrução. Subagendes têm overhead. Se Claude só precisa conhecer sua convenção de migração, escreva uma habilidade. Não inicie um trabalhador isolado para um problema de conhecimento.
- CLAUDE.md sobrecarregado. Passando de 200 linhas, a orientação da própria Anthropic diz que restrições críticas se perdem. Mova conteúdo de referência para habilidades ou divida em arquivos
.claude/rules/que carregam condicionalmente com base em correspondência de caminho.
Se você está construindo um fluxo de trabalho Claude Code do zero e quer um ponto de partida estruturado, o guia de fluxo de trabalho Claude Code explica como sequenciar essas camadas para uma configuração de repositório real.
Siga o Guia de Implementação Relevante
Uma vez que você identificou o mecanismo correto, os caminhos de implementação se dividem claramente. Este post é uma camada de navegação e comparação, não um tutorial de configuração. Aqui é onde ir a seguir, por mecanismo:
- Configuração de hooks: o guia de hooks Claude Code cobre eventos de ciclo de vida, tipos de manipuladores e como escrever manipuladores shell e HTTP que rodam de forma determinística.
- Subagendes: o guia de subagendes Claude Code explica como instruir um subagende, escopo suas permissões de ferramentas e manipular o resultado na sessão pai.
- Servidores MCP: se você está construindo ou integrando servidores MCP para uma pilha de produção, o guia de produção de servidores MCP cobre tipos de servidor, transporte e padrões de confiabilidade.
- Habilidades: comece com a documentação oficial de habilidades, que cobre estrutura SKILL.md, descrições no frontmatter e como comandos customizados mapeiam para arquivos de habilidade.
Não tente ler os quatro de uma vez antes de decidir qual mecanismo se aplica. É assim que você acaba três horas dentro da configuração de hook quando precisava de uma habilidade de duas linhas.
FAQ
O CLAUDE.md é um mecanismo que devo incluir nesta decisão?
Sim, mas é um tipo diferente de decisão. CLAUDE.md não é selecionado no momento da tarefa. Ele carrega automaticamente a cada sessão. A pergunta para CLAUDE.md é: "Claude precisa dessa informação todas as vezes, incondicionalmente?" Se sim, coloque lá. Se a instrução só importa para certas tarefas, ela pertence a uma skill com uma descrição de frontmatter específica.
Uma skill pode disparar uma chamada de servidor MCP?
Sim. Uma skill pode instruir Claude a usar ferramentas MCP disponíveis como parte de um fluxo de trabalho. A skill fornece o como (o que pedir, em qual sequência, com quais expectativas de formatação) e o servidor MCP fornece o acesso. São complementares, não concorrentes.
Qual é a diferença entre um subagente e um agent team?
Um subagente é um worker que você despacha da sessão principal para lidar com uma sub-tarefa focada. Um agent team é um conjunto de sessões pares que podem se comunicar diretamente, adequado para trabalho colaborativo genuinamente paralelo. Para a maioria das tarefas de repositório, um subagente é a escolha certa. Agent teams fazem sentido quando múltiplos workstreams independentes precisam se coordenar em vez de uma sessão delegar para baixo.
Hooks têm acesso ao contexto do Claude?
Não. Esse é o ponto. Hooks rodam fora do contexto do Claude e o modelo não pode sobrescrevê-los. Isso os torna a ferramenta certa para garantias duras: verificações de segurança, passes de linting obrigatórios, padrões de arquivo bloqueados. O tradeoff é que um hook não pode tomar decisões nuançadas com base no que Claude entende sobre a tarefa. Ele dispara no evento e executa seu handler.
Quando faz sentido usar todos os quatro mecanismos juntos?
Quando você tem um fluxo de trabalho com múltiplos modos de falha distintos: uma lacuna de conhecimento (skill), um requisito de conectividade (MCP), um risco de context-bleed (subagente), e pelo menos uma ação que deve ser garantida independentemente do julgamento do modelo (hook). A maioria das tarefas simples precisa de um ou dois mecanismos. Recorrer aos quatro em cada tarefa adiciona overhead sem benefício.
A distinção mais nítida nesta comparação toda: uma skill é uma sugestão que Claude lê e segue; um hook é uma regra que o harness força estejam ou não de acordo. Errar nessa faz sua "regra de segurança" ser apenas um pedido educado.