Pare de entupir o CLAUDE.md: os 7 controles do Claude Code

A frase mais valiosa do post da Anthropic sobre como direcionar o Claude Code não é uma feature — é uma confissão. Um "nunca faça isso" escrito no seu CLAUDE.md não é proteção de verdade: numa sessão longa, ou numa situação ambígua, o modelo pode simplesmente passar por cima de uma regra que só existe no prompt. Se uma instrução não pode ser violada de jeito nenhum, ela precisa ser código que executa, não texto que o modelo lê. Essa ideia sozinha reorganiza o jeito de usar os sete controles.

O modelo mental que eu tirei do post: cada controle se diferencia em dois eixos — quando ele entra na context window e com que rigor ele é obedecido. Escolha o controle por esses dois eixos, não por costume.

Os 7 controles, nesses dois eixos

• CLAUDE.md — entra no início da sessão, linha por linha, toda sessão, relevante ou não. A orientação da Anthropic: mantenha abaixo de 200 linhas. Bom pro que é verdade sempre — stack, comandos de build, convenções. Péssimo lugar pra procedimentos e restrições duras.
• Rules (.claude/rules/*.md) — restrições que podem ter escopo por caminho, com paths: no frontmatter (por exemplo, src/api/**), entrando no contexto só quando o Claude mexe em arquivos que batem com o padrão. Bom pra "nesse canto do código, sempre X" sem pesar em toda sessão.
• Skills (.claude/skills/<nome>/SKILL.md) — só o nome e uma descrição curta carregam de cara; o passo a passo completo entra quando a skill é invocada. Bom pra procedimentos repetíveis: checklist de release, rotina de revisão. Se o seu CLAUDE.md tem lógica em etapas, isso é uma skill morando no arquivo errado.
• Subagents (.claude/agents/*.md) — rodam numa context window isolada e devolvem só a resposta final; dá pra aninhar até cinco níveis. Bom pra investigações paralelas e bagunçadas (fuçar logs, auditar dependências) cujo barulho intermediário você não quer na conversa principal.
• Hooks (settings.json) — comandos de verdade que disparam de forma determinística em eventos do ciclo de vida. Um hook de PreToolUse que termina com código 2 bloqueia a chamada da ferramenta, ponto final. É o único item da lista que é imposição, e não persuasão.
• Output styles (.claude/output-styles/*.md) — injetados direto no system prompt, então são o controle em nível de prompt mais obedecido de todos. A pegadinha: um estilo customizado substitui as instruções padrão de código do Claude Code, a não ser que você defina keep-coding-instructions: true.
• --append-system-prompt — adições que valem só naquela sessão, por cima do papel padrão. Útil pra ajustes pontuais, mas a Anthropic avisa do retorno decrescente: quanto mais você empilha aí, menos cada instrução é seguida.

O ângulo de EM

Num time, isso é uma questão de onboarding e de risco, não um truque de produtividade pessoal. Um repositório onde as restrições duras vivem em hooks, os procedimentos viram skills e o CLAUDE.md fica enxuto é um repositório onde o agente do dev recém-contratado se comporta igual ao do sênior desde o primeiro dia. E em entrevista com empresa internacional, explicar por que uma regra vai num hook em vez de num prompt é exatamente o tipo de critério que soa sênior.

Hoje: abra o seu CLAUDE.md e audite linha por linha. Tudo que estiver escrito como "nunca" ou "sempre" e que doeria de verdade se fosse ignorado → vira um hook de PreToolUse. Todo passo a passo → vira uma skill. O que sobrar tem que caber com folga em 200 linhas.

Fontes

• Anthropic — Steering Claude Code with skills, hooks, rules, subagents and more