#Os 7 Jeitos de Guiar o Claude Code (e Quando Usar Cada Um)

O Claude Code tem sete formas de receber instrução. Saber qual usar para cada coisa é o que separa um setup que ajuda de um que atrapalha.

---

#Contexto

Todo CLAUDE.md começa pequeno. Três linhas com o comando de build, uma convenção de nomes, o jeito de rodar os testes.

Seis meses depois ele tem 400 linhas. Tem procedimento de deploy, checklist de segurança, "sempre rode o prettier", "nunca use git push --force", preferências de estilo, e um bloco que ninguém lembra por que está lá. Cada uma dessas linhas é lida no início de toda sessão e consome tokens, relevante ou não.

O problema não é o conteúdo. É o lugar. O Claude Code oferece sete mecanismos para guiar o comportamento dele, e cada um foi pensado para um tipo diferente de instrução. Jogar tudo no CLAUDE.md é usar uma chave de fenda para todo parafuso, prego e porca da casa.

Este guia mostra os sete mecanismos, o que cada um custa, e um critério simples para escolher o certo.

#As três perguntas que decidem tudo

Antes dos mecanismos, vale entender as variáveis. Cada forma de instruir o Claude controla as mesmas três coisas de um jeito diferente:

1. Quando a instrução entra no contexto? No início da sessão, sob demanda, ou só quando um evento dispara.
2. O que acontece com ela na compactação (compaction)? Sessões longas são compactadas para caber na janela. Algumas instruções sobrevivem, outras somem até serem tocadas de novo.
3. Quanto custa em tokens? Tudo que está sempre carregado ocupa espaço o tempo todo, mesmo quando irrelevante para a tarefa do momento.

Some a isso uma quarta dimensão: autoridade. Uma instrução em texto é um pedido que o modelo pode interpretar ou esquecer. Um hook é código que roda de verdade. A diferença entre "peça para o Claude rodar o formatador" e "o formatador roda sozinho" é a diferença entre os dois.

#1. CLAUDE.md: os fatos que valem sempre

O CLAUDE.md da raiz carrega no início da sessão e fica lá o tempo todo. Versões em subpastas carregam sob demanda, quando o Claude toca um arquivo daquela pasta. Depois de uma compactação, o da raiz é relido; os de subpasta somem até serem acessados de novo.

Custo de contexto: alto. Cada linha é paga em toda sessão.

Melhor para: fatos que o Claude precisa ter sempre à mão. Comando de build, estrutura de diretórios, convenções de código, normas do time.

A recomendação prática é manter abaixo de 200 linhas, com um dono responsável. Em monorepos, dê a cada time um CLAUDE.md na própria subpasta, para que ninguém carregue convenção de código que nunca vai tocar.

O teste para saber se algo pertence ao CLAUDE.md: é um fato verdadeiro o tempo todo? Se for um procedimento ("como deployar") ou uma automação ("sempre formate"), o lugar é outro.

#2. Rules: restrições com escopo

Rules vivem em .claude/rules/ como arquivos markdown separados. Podem ser sempre carregadas ou limitadas a certos caminhos via frontmatter paths:. São reinjetadas na compactação.

---
paths:
  - "src/api/**"
---
Todo handler de API valida a entrada com Zod antes de processar.

Custo de contexto: médio. Baixo quando a regra tem escopo de path, porque só entra no contexto quando o Claude trabalha em arquivos que casam com o padrão.

Melhor para: restrições e convenções específicas, principalmente as que valem só para uma parte do código. Uma regra que só se aplica a src/api/** não precisa poluir o contexto enquanto você mexe no frontend.

Uma rule sem escopo é mecanicamente igual a colocar o conteúdo no CLAUDE.md: sempre carregada, sempre custando tokens. O ganho aparece quando você usa o escopo de path.

#3. Skills: procedimentos sob demanda

Skills ficam em .claude/skills/ como pastas com um SKILL.md. No início da sessão, só o nome e a descrição carregam. O corpo completo entra quando a skill é invocada, por comando ou por correspondência automática com a tarefa.

Custo de contexto: baixo. O corpo (que pode ter centenas de linhas) só ocupa espaço quando é usado de fato.

Melhor para: procedimentos. Checklist de deploy, processo de release, fluxo de revisão de segurança. Aquele bloco de 30 linhas de "como fazer X" que está inchando o CLAUDE.md é uma skill esperando para nascer.

A diferença em relação ao CLAUDE.md é o timing. O CLAUDE.md é para o que o Claude precisa saber sempre. A skill é para o que ele precisa saber só quando a tarefa aparece. Tirar procedimentos do CLAUDE.md e transformá-los em skills mantém o contexto base enxuto sem perder o conhecimento.

#4. Subagents: trabalho isolado

Subagents ficam em .claude/agents/ com frontmatter YAML (nome, descrição, e campos opcionais de modelo e acesso a ferramentas). O nome e a descrição carregam no início; o corpo só entra quando o subagent é chamado.

A característica que define o subagent: ele roda na própria janela de contexto, separada. Faz o trabalho lá, e só o resumo final volta para a conversa principal.

Custo de contexto: baixo. Zero na conversa principal até ser chamado, e mesmo depois só o resultado retorna.

Melhor para: tarefas paralelas que sujariam a conversa com resultados intermediários que você não vai reler. Busca profunda no código, análise de um log gigante, auditoria de dependências.

Pense na diferença entre skill e subagent assim: a skill executa o procedimento dentro da thread principal, onde você vê e dirige cada passo. O subagent leva o trabalho para outra sala e volta só com a conclusão. Quando o processo gera muito ruído que você não precisa acompanhar, o subagent protege seu contexto.

#5. Hooks: automação determinística (e garantias)

Hooks são registrados no settings.json (ou no frontmatter de uma skill ou agent) e disparam em eventos do ciclo de vida: edição de arquivo, chamada de ferramenta, início de sessão, e dezenas de outros. O código roda no harness, fora do contexto do modelo.

Existem cinco tipos: command (roda um shell command), http (faz um POST), mcp_tool (chama uma ferramenta de um servidor MCP), prompt e agent (usam o julgamento de um modelo para decidir). Os três primeiros são determinísticos: rodam sempre igual, sem depender da interpretação do Claude.

Custo de contexto: baixo. É código no harness, não instrução carregada.

Melhor para: automação que precisa ser confiável. Rodar o linter depois de cada edição, bloquear comandos perigosos, mandar uma notificação no Slack quando algo termina.

Aqui está a virada de chave do artigo original da Anthropic. Frases como "sempre faça X" e "nunca faça Y" no CLAUDE.md são o uso errado da ferramenta. O modelo escolher rodar um formatador é diferente do formatador rodando sozinho. Quando algo precisa acontecer, instrução em texto é frágil; hook é garantia.

Um hook de PreToolUse consegue inspecionar qualquer chamada de ferramenta e negá-la com exit code 2 (ou com um JSON de decisão de permissão). É um bloqueio de verdade, impossível de obter com uma regra escrita que o modelo pode contornar sem querer.

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

Para o nível organizacional existem as managed settings, configuradas por um administrador e impossíveis de sobrescrever. É como um time impõe um limite que nenhum desenvolvedor consegue burlar.

#6. Output styles: mudar o papel

Output styles ficam em .claude/output-styles/ e são injetados no system prompt no início da sessão. Nunca são compactados, e ficam em cache depois da primeira requisição.

Custo de contexto: alto. Ocupam o system prompt o tempo todo.

Melhor para: mudanças significativas de papel. Transformar o Claude Code de assistente de programação em outra coisa.

Atenção ao detalhe que pega muita gente: um output style customizado substitui as instruções padrão de escopo, comentários, segurança e testes. Você ganha o novo comportamento e perde as defaults que vinham de graça. Os styles embutidos (Default, Explanatory, Learning) cobrem a maioria dos casos sem essa manutenção. O Explanatory adiciona insights sobre as decisões de implementação; o Learning pede que você escreva pequenos trechos marcados com TODO(human). Trocar entre eles é um /output-style.

#7. Append system prompt: ajuste de uma sessão

O --append-system-prompt é uma flag de linha de comando passada no momento da invocação. O texto é somado ao system prompt original, sem alterar o papel central do Claude, e vale só para aquela execução.

Custo de contexto: moderado. Aumenta os tokens de entrada, mas o prompt caching reduz o custo depois da primeira requisição.

Melhor para: um padrão de código específico, um formato de saída, ou um conhecimento de domínio que você quer só naquela sessão. Útil em scripts e automações pontuais.

A limitação é honesta: quanto mais instrução você empilha por esse caminho, menos rigorosamente o Claude segue cada uma. Funciona bem para ajustes pequenos, não para reescrever o comportamento todo.

#A tabela que resume

Mecanismo	Quando carrega	Na compactação	Custo de contexto	Melhor para
CLAUDE.md	Início, persistente	Relido	Alto	Fatos sempre válidos
Rules	Início ou por path	Reinjetado	Médio (baixo se scoped)	Restrições e convenções
Skills	Nome no início, corpo sob demanda	Reinjetado até o orçamento	Baixo	Procedimentos
Subagents	Nome no início, corpo na chamada	Só o resumo volta	Baixo (zero até chamar)	Tarefas isoladas
Hooks	Eventos do ciclo de vida	Fora do contexto	Baixo	Automação determinística
Output styles	Início (system prompt)	Nunca compactado	Alto	Mudança de papel
Append system prompt	Na invocação	Nunca compactado	Moderado	Ajuste de uma sessão

Vale lembrar a diferença de autoridade. CLAUDE.md, rules e append são instruções: o modelo as interpreta e pode falhar. Hooks e managed settings são determinísticos: acontecem independente do que o modelo decide. Quando o custo de errar é alto, escolha o lado determinístico.

#O modelo mental: "sempre", "nunca", "às vezes"

Esqueça os nomes por um segundo e olhe para a frase que você ia escrever no CLAUDE.md. A forma dela já indica o mecanismo certo:

• "Sempre faça X" (uma ação) vira hook. Se o formatador precisa rodar, faça-o rodar, não peça.
• "Nunca faça Y" vira hook de PreToolUse ou managed settings. Quando algo não pode acontecer, instrução é a ferramenta errada.
• "Para fazer Z, siga estes passos" vira skill. Procedimento mora em skill, não no contexto base.
• "Nesta pasta, vale a regra W" vira rule com escopo de path.
• "Este é um fato sobre o projeto" fica no CLAUDE.md. É o único caso em que ele é a resposta certa.
• "Faça esse trabalho pesado sem me encher de log" vira subagent.

O CLAUDE.md é para fatos que o Claude deve segurar o tempo todo. Um runbook de deploy ou um checklist de revisão de segurança pertencem a .claude/skills/. Essa única distinção já resolve a maior parte do inchaço.

#Repercussão na comunidade

O artigo original da Anthropic virou referência rápida. Na semana seguinte surgiram dezenas de explicações derivadas em blogs, no Medium, no dev.to e em newsletters, sinal de que o framework de decisão preencheu uma lacuna real: as ferramentas existiam havia meses, mas faltava o critério de quando usar cada uma.

O ponto de atrito mais citado é o escopo de path das rules. Várias issues abertas no repositório do Claude Code relatam que o frontmatter paths: nem sempre funciona como documentado. Há relatos de que rules com paths: no nível do usuário (~/.claude/rules/) são ignoradas, de que a regra só é injetada quando o Claude lê um arquivo que casa com o padrão (não quando escreve), e de que o formato globs: se comporta de forma mais previsível que o paths: documentado em algumas configurações.

A lição prática: rules com escopo são poderosas no papel, mas teste o comportamento real no seu setup antes de confiar nelas para uma restrição importante. Para algo que não pode falhar, um hook continua sendo a aposta mais segura, exatamente pelo argumento de determinismo do artigo.

#Na Prática

Como desinchar um CLAUDE.md que virou um monstro:

1. Audite o arquivo atual

Leia cada bloco e classifique em quatro pilhas: fato, procedimento, restrição, automação.

2. Mova os procedimentos para skills

Todo "como fazer X" com mais de uns poucos passos vira uma pasta em .claude/skills/:

mkdir -p .claude/skills/deploy

Coloque o passo a passo no SKILL.md com nome e descrição claros, para o Claude invocar na hora certa.

3. Transforme os "sempre" em hooks

"Sempre rode o linter depois de editar" vira um hook de PostToolUse no .claude/settings.json, com matcher Edit|Write.

4. Transforme os "nunca" em bloqueios

"Nunca rode comando destrutivo" vira um hook de PreToolUse que inspeciona a chamada e sai com exit code 2 para negar.

5. Dê escopo às restrições por pasta

Convenção que só vale para uma área do código vira uma rule em .claude/rules/ com paths:, testada no seu setup.

6. Deixe no CLAUDE.md só o que é fato

O que sobrar (comandos, estrutura, convenções gerais) fica no CLAUDE.md, idealmente abaixo de 200 linhas.

Dica: não tente migrar tudo de uma vez. Comece pelo bloco que mais incomoda (geralmente o procedimento mais longo) e vire ele uma skill. O alívio no contexto é imediato e você pega o jeito.

#O que isso muda no seu dia a dia

O CLAUDE.md inchado não é só uma questão de organização. Cada linha irrelevante carregada é token gasto e atenção diluída do modelo. Distribuir as instruções pelos sete mecanismos não é firula: é o que mantém o contexto enxuto e o comportamento confiável.

O resumo cabe em uma frase. Fatos no CLAUDE.md, procedimentos em skills, restrições com escopo em rules, trabalho pesado em subagents, e tudo que precisa acontecer em hooks. O texto pede; o código garante. Saber a diferença é o que faz o Claude Code trabalhar do seu lado em vez de contra.

Se quiser ir mais fundo em como estruturar um CLAUDE.md que puxa o melhor do agente, o Claude Code Guide cobre o assunto em detalhe.

---

#Referências

• Steering Claude Code: skills, hooks, subagents and more: artigo original da Anthropic que apresenta os sete mecanismos e o framework de decisão.
• Hooks reference: documentação oficial dos eventos, dos cinco tipos de hook e do bloqueio via exit code 2 e decisão de permissão.
• Create custom subagents: documentação oficial sobre como definir subagents, janela de contexto isolada e o que retorna para a sessão principal.
• Output styles: documentação oficial dos styles embutidos (Explanatory, Learning) e dos customizados.
• Path-scoped rules: issues no repositório do Claude Code: relatos da comunidade sobre o comportamento de paths: versus globs: no frontmatter das rules.