Comandos Personalizados, Hooks e Subagentes: Para Que Serve Cada Um
O Claude Code vem com três maneiras separadas de estender seu comportamento: comandos de barra personalizados, hooks e subagentes.
Eles são agrupados porque todos vivem sob o mesmo guarda-chuva de "personalizar o Claude Code", e porque um projeto real geralmente acaba usando os três ao mesmo tempo.
Mas eles resolvem problemas diferentes, rodam em pontos diferentes do fluxo de trabalho e são configurados de maneiras completamente diferentes.
Confundi-los é a fonte mais comum de confusão para uma equipe configurando o Claude Code pela primeira vez.
Resumo
- Ideia Central: um comando personalizado é um prompt reutilizável, um hook é um gatilho de shell automático e um subagente é uma instância Claude isolada com seu próprio contexto e ferramentas.
- Por Que Importa: escolher o ponto de extensão errado para um trabalho ou falha completamente (um hook não pode "pensar") ou desperdiça esforço (um subagente para algo que um comando de uma linha faria).
- Conceitos-Chave: comando de barra, frontmatter, corpo do prompt, evento de ciclo de vida, PreToolUse, PostToolUse, Stop, contexto isolado, acesso a ferramentas com escopo.
- Quando Usar: comandos para solicitações repetíveis que você digita com frequência, hooks para qualquer coisa que precise acontecer deterministicamente fora do julgamento do Claude, subagentes para trabalhos que precisam de sua própria janela de contexto ou um conjunto de ferramentas mais restrito.
- Limitações / Trade-offs: comandos ainda consomem o contexto da sessão principal, hooks não podem raciocinar (eles apenas executam lógica de shell) e subagentes adicionam latência e perdem o acesso ao contexto em execução do pai.
- Tópicos Relacionados: frontmatter de comando de barra, automação PostToolUse, bloqueio PreToolUse, pesquisa paralela de subagentes.
Fundamentos
Pense nos três pontos de extensão como respostas a três perguntas diferentes.
Comandos de barra personalizados respondem "como paro de digitar a mesma solicitação repetidamente?"
Um comando é um arquivo markdown com um cabeçalho frontmatter e um corpo de prompt, armazenado em um diretório de comandos do projeto ou do usuário.
Digitar /review-pr envia o prompt desse arquivo para a conversa atual exatamente como se você o tivesse digitado.
Hooks respondem "como faço algo acontecer sempre, sem pedir ao Claude para se lembrar de fazer isso?"
Um hook é um comando de shell registrado em um evento de ciclo de vida, como antes de uma ferramenta ser executada ou após a conclusão de uma edição de arquivo.
O harness executa o hook diretamente. Claude não decide se o hook dispara; o evento disparando é o que o aciona.
Subagentes respondem "como dou a uma parte do trabalho sua própria folha em branco?"
Um subagente é uma instância Claude separada, gerada pela sessão principal, com sua própria janela de contexto e sua própria lista de ferramentas permitidas.
Ele faz o trabalho atribuído, então relata um resumo para a sessão que o gerou, sem nunca ter visto todo o resto do histórico dessa sessão.
Uma analogia útil: um comando é uma macro salva, um hook é um alarme de movimento e um subagente é um colega de trabalho a quem você entrega uma pasta selada com instruções.
Mecânicas e Interações
Os três pontos de extensão diferem mais claramente em quem ou o que decide que eles rodam.
Um comando só roda quando um usuário (ou outro prompt) o invoca explicitamente pelo nome. Nada dispara por conta própria.
Um hook roda automaticamente sempre que seu evento registrado ocorre, independentemente de qual comando ou prompt acionou esse evento. Ele não tem consciência de intenção, apenas da carga útil do evento que recebe.
Um subagente roda quando o Claude da sessão pai explicitamente gera um, tipicamente porque uma tarefa é grande, independente ou inundaria o contexto principal com detalhes intermediários.
Esses três também diferem em o que eles podem ver e tocar.
O corpo do prompt de um comando se torna parte da conversa atual, então ele compartilha o contexto completo da sessão principal e seu acesso completo a ferramentas.
Um hook normalmente executa um script de shell simples ou um comando CLI; ele não tem raciocínio de modelo próprio; ele apenas executa e retorna um status de saída.
Um subagente recebe uma janela de contexto isolada, semeada apenas com o que o pai escolhe entregar a ele, e uma lista de ferramentas que pode ser reduzida a partir das próprias permissões do pai.
# Um hook não "entende" a edição; ele apenas reage à carga útil do evento.
# Esta é uma entrada de hook PostToolUse em settings.json, conceitualmente:
{
"PostToolUse": [
{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE_PATH\"" }] }
]
}Esse trecho é uma ligação de ciclo de vida, não um prompt. Nada nele pede ao Claude para decidir se deve formatar o arquivo; a formatação simplesmente acontece toda vez que um evento de edição dispara.
Comandos e subagentes, por outro lado, ambos roteiam pelo modelo, que é por isso que ambos podem raciocinar, fazer perguntas de acompanhamento internamente e produzir chamadas de julgamento que um hook nunca poderia.
Considerações Avançadas e Aplicações
Na prática, os três pontos de extensão raramente são usados isoladamente. Um comando pode instruir o Claude a gerar vários subagentes. Um hook PreToolUse pode bloquear uma das edições desses subagentes tão facilmente quanto bloqueia a sessão principal. Os eventos de ciclo de vida que um hook escuta não se importam com qual camada do sistema gerou a chamada da ferramenta.
Essa composibilidade também é onde as equipes se metem em problemas. Um comando que sempre gera três subagentes para uma tarefa que precisava de apenas um desperdiça latência e tokens. Um hook escrito para "ajudar" commitando automaticamente em cada evento Stop pode silenciosamente commitar trabalho inacabado se disparar no Stop de um subagente, não apenas no da sessão principal. Compreender os limites neste artigo é o que evita esses erros a jusante.
| Ponto de Extensão | Acionado Por | Roda Onde | Melhor Ajuste |
|---|---|---|---|
| Comando de barra personalizado | Invocação explícita /nome | Contexto da sessão principal | Solicitações repetíveis e reutilizáveis |
| Hook | Um evento de ciclo de vida registrado | Shell, fora do modelo | Efeitos colaterais determinísticos: formatar, registrar, bloquear |
| Subagente | Claude gerando-o no meio da tarefa | Seu próprio contexto isolado | Trabalho grande, independente ou paralelo |
Há também uma dimensão de governança. Comandos vivem em controle de versão como markdown simples, então uma equipe pode revisá-los e compartilhá-los como qualquer outro arquivo de origem. Hooks vivem em settings.json e, como executam comandos de shell arbitrários, merecem o mesmo escrutínio que qualquer outro executável verificado em um repositório. Definições de subagentes podem restringir o acesso a ferramentas por função, o que é um limite de segurança real, não apenas uma conveniência organizacional, já que um subagente com escopo para ferramentas somente leitura não pode editar arquivos, mesmo que o prompt tente convencê-lo a fazê-lo.
Concepções Errôneas Comuns
- "Um hook é apenas um comando que se executa sozinho." Um hook não tem prompt nem raciocínio de modelo associado a ele; é um gatilho de shell conectado a um evento, mais próximo de um hook pre-commit do git do que de um comando de barra.
- "Subagentes compartilham o contexto da sessão principal para economizar tokens." O oposto é verdadeiro; o isolamento é o ponto principal, e um subagente só recebe o que o pai inclui explicitamente em seu prompt de tarefa.
- "Comandos podem bloquear ou vetar uma ação." Apenas hooks (especificamente PreToolUse) podem rejeitar uma chamada de ferramenta antes que ela aconteça; um comando só pode moldar o que é solicitado em primeiro lugar.
- "Qualquer um dos três pode substituir os outros." Cada um cobre um mecanismo diferente (invocação, automação, isolamento); um fluxo de trabalho que realmente precisa de bloqueio determinístico não o obterá de um comando, não importa quão cuidadosamente formulado seja o prompt.
FAQs
Qual é a maneira mais simples de lembrar a diferença entre os três?
- Comando: algo que você pede pelo nome.
- Hook: algo que acontece automaticamente em um evento.
- Subagente: outra pessoa que faz um trabalho em seu próprio espaço.
Um comando de barra personalizado pode gerar um subagente?
Sim. O corpo do prompt de um comando pode instruir o Claude a delegar parte da tarefa a um ou mais subagentes, da mesma forma que uma solicitação digitada poderia.
Hooks exigem que o Claude esteja "pensando" quando rodam?
Não. Hooks são comandos de shell executados pelo harness em resposta a um evento; eles rodam independentemente do que o Claude está raciocinando naquele momento.
Por que eu usaria um subagente em vez de apenas pedir na sessão principal?
Para evitar que a janela de contexto da sessão principal se encha com detalhes intermediários de pesquisa ou exploração que só importam para uma subtarefa, não para o resto da conversa.
Um hook pode ver o que o Claude está prestes a fazer antes que aconteça?
Sim, especificamente para hooks PreToolUse. Eles recebem a chamada de ferramenta proposta como entrada e podem aprovar, modificar o resultado ou bloqueá-la antes que a ferramenta seja executada.
Subagentes e a sessão principal do Claude Code estão executando modelos diferentes?
Não necessariamente. Um subagente pode ser configurado para usar o mesmo modelo que a sessão pai ou um diferente; a característica distintiva é o contexto isolado e o escopo de ferramentas, não a escolha do modelo.
Onde os comandos personalizados ficam no disco?
Como arquivos markdown com um cabeçalho frontmatter e um corpo de prompt, em um diretório de comandos com escopo para o projeto ou para o usuário, para que possam ser versionados junto com o restante de um repositório.
Um hook é a ferramenta certa para "sempre executar o linter após cada edição"?
Sim. Esse é um efeito colateral determinístico e incondicional ligado a um evento (uma edição de arquivo), que é exatamente para o que um hook PostToolUse foi projetado.
Um hook é a ferramenta certa para "decidir se este refator é uma boa ideia"?
Não. Isso requer julgamento, que apenas o prompt de um comando ou o raciocínio de um subagente podem fornecer; um hook só pode executar lógica de shell fixa contra o evento que recebe.
O que acontece com o contexto de um subagente depois que ele termina?
Ele relata um resumo para a sessão pai e seu contexto completo é descartado; o pai nunca vê a exploração intermediária bruta do subagente, apenas o que ele escolheu relatar.
Múltiplos hooks podem disparar no mesmo evento?
Sim. Um único evento de ciclo de vida, como PostToolUse, pode ter múltiplos comandos de hook registrados contra ele, e eles rodam na ordem em que são configurados.
Preciso de todos os três pontos de extensão para usar o Claude Code de forma eficaz?
Não. Muitos projetos usam apenas comandos personalizados por muito tempo antes que uma necessidade real de automação determinística (hooks) ou isolamento de contexto (subagentes) apareça.
Relacionados
- Noções Básicas de Comandos Personalizados e Subagentes - um primeiro comando e primeiro subagente práticos.
- Escrevendo Seu Primeiro Comando de Barra Personalizado com Frontmatter Markdown - o formato de arquivo por trás de cada comando.
- Eventos de Hook Comuns e Quando Usar Cada Um - o conjunto completo de eventos de ciclo de vida aos quais os hooks podem se anexar.
- Como Subagentes Obtêm Seu Próprio Contexto e Ferramentas - o mecanismo de isolamento explicado em profundidade.
Versões de Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.