Melhores Práticas para Comandos, Hooks e Subagentes Personalizados

Estas são as convenções que valem a pena adotar assim que um projeto começa a depender de comandos, hooks e subagentes personalizados além de um experimento pontual.

Cada regra abaixo reflete um modo de falha real, um matcher ambíguo, um prompt de tarefa vago, um hook que roda de forma muito ampla, que aparece rapidamente assim que esses pontos de extensão são usados para trabalho real.

Como Usar Esta Lista

• Trate as regras como padrões para desviar deliberadamente, não como leis, pois a tolerância ao risco de cada projeto difere.
• Revise as seções de hooks e comandos sempre que settings.json ou .claude/commands/ crescer além de um punhado de entradas; as convenções decaem mais rapidamente sob acúmulo silencioso.
• Aplique as regras de subagente por tarefa, pois a quantidade certa de delegação varia com a independência e o tamanho do trabalho real.
• Emparelhe as regras de PreToolUse com uma lista concreta de caminhos protegidos para o seu projeto; uma regra sem um alvo concreto não impõe nada.

A - Nomenclatura e Descoberta

• Dê a cada comando uma description em seu frontmatter. Sem isso, um comando fica invisível no autocompletar, e os colegas de equipe voltam a implementar a mesma solicitação do zero.
• Nomeie comandos pela ação, não pelo solicitante. /pre-review é lido claramente meses depois; /chris-check não sobrevive à saída da pessoa da equipe.
• Mantenha nomes de arquivos e slugs de comandos estáveis após o compartilhamento. Renomear um comando quebra a memória muscular de cada colega de equipe e qualquer documentação que o referencie pelo nome.
• Agrupe comandos relacionados com um prefixo compartilhado quando o conjunto crescer. /pr-review, /pr-summarize e /pr-changelog são lidos como uma família no autocompletar; três nomes não relacionados não o são.

B - Escopo de Matchers de Hook

• Combine hooks com o conjunto de ferramentas mais restrito que realiza o trabalho. Um hook de formatação precisa de Edit|Write, não de um match sem escopo em todas as chamadas de ferramenta.
• Prefira um arquivo de script dedicado em vez de um comando inline longo em settings.json. Um script é testável e comparável por si só; uma linha única extensa em JSON não é.
• Proteja contra dados de evento ausentes ou malformados antes de agir. Um hook que assume que um caminho de arquivo está sempre presente falhará ruidosamente, ou silenciosamente, na primeira vez que não estiver.
• Mantenha hooks rápidos. Um hook PostToolUse é executado em cada edição correspondente; um lento (uma suíte de testes completa, uma compilação grande) adiciona essa latência a cada edição individual, não apenas às que importam.
• Controle de versão de cada script de hook junto com o projeto. Um hook que existe apenas na máquina de um contribuidor é um hook que o resto da equipe realmente não tem.

C - Usando PreToolUse para Limites Reais

• Reserve PreToolUse para regras que devem ser mantidas mesmo contra um prompt enganoso. Qualquer coisa formulada como "isso nunca deve acontecer" pertence aqui, não em uma etapa de limpeza PostToolUse.
• Emita uma decisão explícita de bloqueio, não apenas um código de saída diferente de zero. Uma resposta estruturada {"decision": "block", "reason": "..."} é o sinal confiável; códigos de saída sozinhos podem ser interpretados de forma inconsistente.
• Escreva razões de bloqueio para um humano lendo a transcrição posteriormente. "Bloqueado" não explica nada; "este caminho está protegido, peça a um humano para fazer essa alteração diretamente" explica.
• Ancore padrões de caminhos protegidos à estrutura de diretórios real, não apenas a uma extensão de arquivo. Um padrão como *.json protegendo um único arquivo de lock acabará bloqueando todos os arquivos JSON no projeto.
• Emparelhe uma proteção PreToolUse com proteções normais em nível de repositório. Um hook só é acionado dentro do próprio caminho de chamada de ferramenta do Claude Code; ele não é um substituto para proteção de branch ou permissões de arquivo impostas em outro lugar.

D - Delegando Trabalho para Subagentes

• Escreva prompts de tarefas de subagente como se o subagente não tivesse visto mais nada. Porque não viu; qualquer coisa que a sessão pai saiba e não reafirme simplesmente não está disponível para o subagente.
• Escope as ferramentas de um subagente ao que seu trabalho realmente exige. Um subagente de pesquisa que nunca edita arquivos não deve ter Edit ou Write em sua lista de ferramentas, como uma questão de aplicação, não apenas de organização.
• Peça um resumo, não o conteúdo completo dos arquivos, na instrução de relatório. Um subagente que despeja arquivos inteiros de volta para o pai derrota o propósito de economia de contexto de delegar em primeiro lugar.
• Execute subagentes em paralelo apenas quando as peças forem genuinamente independentes. Uma tarefa onde um subagente precisa das descobertas de outro primeiro deve ser executada sequencialmente, não concorrentemente.
• Combine o número de subagentes paralelos com a quantidade de síntese que a sessão principal pode realmente fazer depois. Gerar mais subagentes do que você pode ler e combinar de forma significativa apenas atrasa a resposta.
• Reserve subagentes para tarefas grandes ou isoladas o suficiente para justificar a sobrecarga. Uma pesquisa de uma linha raramente precisa de sua própria janela de contexto; uma exploração de quarenta etapas geralmente precisa.

E - Impedindo que os Três Pontos de Extensão Colidam

• Não peça a um hook para fazer uma chamada de julgamento. Um hook não tem raciocínio de modelo anexado a ele; se a decisão requer ponderar contexto, ela pertence ao prompt de um comando ou à tarefa de um subagente, não a um script shell.
• Não use um comando onde um hook garantiria o resultado. Se algo deve acontecer todas as vezes, sem exceções, um comando que o usuário precisa se lembrar de digitar é o mecanismo errado; use um hook em vez disso.
• Documente qual dos três pontos de extensão uma nova automação usa e por quê. Um membro da equipe depurando comportamento inesperado precisa saber rapidamente se deve procurar em .claude/commands/, settings.json ou uma definição de subagente.
• Revise os hooks de settings.json e .claude/commands/ juntos durante o onboarding. Ambos são verificados no repositório e ambos moldam o que "digitar uma solicitação" ou "uma edição acontecendo" realmente faz; pular qualquer um deixa um novo membro da equipe com uma imagem incompleta.

FAQs

Relacionado

• Comandos, Hooks e Subagentes Personalizados: Para Que Serve Cada Um - a distinção fundamental em que essas práticas se baseiam.
• Escrevendo Seu Primeiro Comando de Barra Personalizado com Frontmatter Markdown - onde as convenções de nomenclatura e descrição se aplicam diretamente.
• Bloqueando Edições de Arquivo de Risco com um Hook PreToolUse - um exemplo completo e funcional das práticas PreToolUse acima.
• Gerando Subagentes Paralelos para Tarefas de Pesquisa Isoladas - as práticas de fan-out em um walkthrough completo.
• Eventos Comuns de Hook e Quando Usar Cada Um - combinando o evento de um hook com seu trabalho real.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~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 as especificações atuais em platform.claude.com/docs antes de confiar neles.