O problema

O Claude Code tem cinco camadas de contexto distintas: CLAUDE.md, Rules, Skills, Agents e Hooks. Cada uma responde a uma pergunta diferente. Coloque o conhecimento na camada errada e ele inchará cada sessão, será ignorado ou não será acionado quando necessário.

Esta bússola te dá um modelo mental para decidir onde colocar o quê e por que aquela camada é a escolha certa.

Mapa da arquitetura

Acompanhe um prompt real através das cinco camadas. Usaremos a ShopFlow, uma loja de e-commerce fictícia, para mostrar como cada camada funciona na prática.

Consultivo

Obrigatório

CLAUDE.md

"Quem é este projeto?"

ConsultivoSempre

Rules

"De quais orientações estruturais o Claude precisa?"

ConsultivoSempre / por caminho

Skills

"O que o Claude precisa saber sobre X?"

ConsultivoSob demanda

Agents

"Quem deve cuidar deste tipo de trabalho?"

ObrigatórioQuando delegado

Hooks

"O que deve acontecer toda vez, sem exceção?"

ObrigatórioEm evento

Um desenvolvedor pede ao Claude para adicionar uma página de checkout do Stripe...

Passo 1 de 6

Clique em qualquer camada para explorar

Árvore de decisão

Clique para encontrar a camada certa para o seu conhecimento.

Tenho um conhecimento ou orientação que quero que o Claude use. De que tipo é?

As 5 camadas

Cada camada tem um propósito, um teste decisivo e anti-padrões. Expanda uma camada para ver os detalhes.

Quando

Sempre. A primeira coisa que você cria.

O quê

A identidade do projeto em menos de 200 linhas. Stack, comandos de build, estrutura de arquivos, convenções que não dá para inferir do código.

Por quê

Define o contexto base de toda sessão. É o README para o Claude.

Testes decisivos

?"Um novo membro do time precisaria disso no primeiro dia?"

?"O Claude consegue descobrir isso lendo o código?"

Anti-padrões

×Colocar orientações tecnológicas detalhadas aqui (isso é uma skill)

×Passar de 200 linhas (divida em rules)

×Descrever cada arquivo do codebase

Docs de Memory & CLAUDE.md →

Quando

Você precisa codificar padrões de layout, referências de arquitetura, preferências de ferramentas específicas do projeto (ex.: ferramentas de migração, padrões de teste) ou ponteiros para a documentação central, principalmente em projetos grandes e complexos.

O quê

Arquivos .md modulares em .claude/rules/. Podem ter escopo por caminho com o frontmatter paths:. Podem referenciar docs de arquitetura externos, ADRs, páginas de wiki ou convenções de ferramentas escolhidas para este projeto.

Por quê

As rules conectam o Claude à sua base de conhecimento mais ampla. Elas codificam decisões estruturais específicas do projeto: como o código é organizado, quais padrões e ferramentas são preferidos aqui, onde encontrar as referências oficiais. Tudo sem inchar cada sessão.

Testes decisivos

?"É sobre como o código deve ser estruturado ou organizado?"

?"Isso codifica uma escolha de ferramenta ou padrão específica do projeto?"

?"Isso referencia decisões de arquitetura ou documentação central?"

?"Essa orientação deve valer apenas ao tocar arquivos específicos?"

Anti-padrões

×Tratar rules como transbordo do CLAUDE.md (elas têm outro propósito)

×Colocar conhecimento técnico reutilizável aqui (isso é uma skill)

×Rules são orientações estruturais, não expertise geral

Docs de Rules →

Quando

Você tem conhecimento profundo sobre uma tecnologia, workflow ou domínio que o Claude deve consultar quando relevante.

O quê

Arquivos SKILL.md com frontmatter. Invocados automaticamente por correspondência de descrição, ou manualmente via /nome-da-skill.

Por quê

Carregadas sob demanda, não em toda sessão. Mantém o contexto base limpo enquanto disponibiliza expertise profunda.

Testes decisivos

?"Isso seria útil em vários projetos?"

?"É conhecimento técnico ou um processo repetível?"

Anti-padrões

×Colocar convenções específicas do projeto em uma skill portátil

×Skills são agnósticas a projeto; rules cuidam das especificidades

Docs de Skills →

Quando

Uma tarefa recorrente se beneficia de um persona especializado, com ferramentas restritas e skills pré-carregadas.

O quê

Arquivos .md de agent definindo papel, ferramentas permitidas, skills pré-carregadas e instruções de comportamento.

Por quê

Isolamento. Um revisor de código não precisa de acesso de escrita. Um pesquisador não precisa de Edit. Agents limitam contexto e permissões a um papel.

Testes decisivos

?"Esta tarefa precisa de um conjunto de ferramentas ou mentalidade diferente da programação geral?"

?"Estou sempre dando ao Claude as mesmas instruções de papel?"

Anti-padrões

×Criar agents que são só skills, sem diferenças de ferramentas ou permissões

×Se é só conhecimento, é uma skill

Docs de Subagents →

Quando

Você precisa de execução garantida e determinística, não de orientação consultiva.

O quê

Comandos de shell disparados em eventos de ciclo de vida (PreToolUse, PostToolUse, SessionStart etc.).

Por quê

Rules e CLAUDE.md são consultivos. O Claude pode pulá-los. Hooks são código que executa.

Testes decisivos

?"Seria um problema se o Claude às vezes esquecesse de fazer isso?"

?"É um comando de shell, não um julgamento?"

Anti-padrões

×Usar hooks para coisas que exigem raciocínio (isso é uma rule ou skill)

×Hooks são mecânicos, não consultivos

Docs de Hooks →

Matriz de comparação

Comparação lado a lado das cinco camadas.

Camada	Escopo	Carrega quando?	Aplicação	Contém
CLAUDE.md	Projeto	Sempre, em toda sessão	Consultivo	Identidade, convenções
Rules	Projeto / Usuário	Sempre ou por caminho	Consultivo	Estrutura, referências de arquitetura
Skills	Marketplace	Sob demanda / auto-match	Consultivo	Conhecimento técnico, workflows
Agents	Marketplace	Quando recebe delegação	Obrigatório	Papel, restrições de ferramentas
Hooks	Projeto / Usuário	Em evento de ciclo de vida	Obrigatório	Comandos de shell

CLAUDE.mdConsultivo

Escopo

Projeto

Carrega

Sempre, em toda sessão

Contém

Identidade, convenções

RulesConsultivo

Escopo

Projeto / Usuário

Carrega

Sempre ou por caminho

Contém

Estrutura, referências de arquitetura

SkillsConsultivo

Escopo

Marketplace

Carrega

Sob demanda / auto-match

Contém

Conhecimento técnico, workflows

AgentsObrigatório

Escopo

Marketplace

Carrega

Quando recebe delegação

Contém

Papel, restrições de ferramentas

HooksObrigatório

Escopo

Projeto / Usuário

Carrega

Em evento de ciclo de vida

Contém

Comandos de shell

Consultivo vs Obrigatório

Consultivo

Claude deveria

O Claude os lê e os segue, na maioria das vezes. Mas pode optar por divergir se julgar que outra coisa é melhor.

CLAUDE.mdRulesSkills

Obrigatório

Claude deve

Estes executam mecanicamente. Hooks rodam como comandos de shell. As restrições de ferramentas dos agents são limites rígidos. Sem margem de julgamento.

Hooks (comandos de shell)Restrições de ferramentas dos agents

Hierarquia de escopos

Clique em um escopo para ver o que vive nele. Escopos superiores prevalecem sobre os inferiores.

Escopos superiores prevalecem sobre os inferiores ↓

Skill vs Agent

Skill = o QUÊ

Conhecimento de tecnologia. Como o Playwright funciona? Quais são as boas práticas para a configuração do Vite? Como estruturamos pipelines do GitLab CI?

Exemplo

skill playwright: conhece locators, fixtures, Page Object Model, padrões de execução paralela.

Agent = o QUEM

Um especialista que usa esse conhecimento. Tem um persona, ferramentas restritas e uma mentalidade específica. O agent pré-carrega as skills de que precisa.

Exemplo

agent test-writer: pré-carrega a skill playwright + tem acesso de escrita apenas aos arquivos de teste + pensa em casos extremos e isolamento.

Se é só conhecimento, sem diferença de permissões → Skill