Anatomia da pasta .claude: O que faz e por que confunde

Se você pesquisou "anatomia da pasta .claude", provavelmente está tentando entender o que essa pasta realmente faz, por que confunde as pessoas e quais partes merecem atenção.

Um tópico do Reddit de março de 2026 deixou isso claro. Um desenvolvedor que teve problemas com convenções de colocação pouco claras criou uma folha de dicas cobrindo o layout do diretório .claude/, eventos de hooks, settings.json, configuração MCP, estrutura de skills e limites de gerenciamento de contexto.

A confusão central: Global vs. Nível de projeto

A maior fonte de confusão é a diferença entre o diretório global ~/.claude/ e o diretório no nível do projeto .claude/.

O diretório global fica na sua pasta pessoal e define comportamento compartilhado. O diretório no nível do projeto fica dentro de um repositório específico e sobrescreve ou estende a configuração global.

Convenções de colocação

Skills ficam em .claude/skills/. Cada skill tem seu próprio diretório com um arquivo SKILL.md.

Agentes ficam em .claude/agents/, não como arquivos soltos na pasta raiz.

Configurações ficam em .claude/settings.json no nível do projeto ou ~/.claude/settings.json globalmente.

Hooks são operacionais, não passivos

O erro mais comum é um matcher muito restrito. Um hook PostToolUse que só corresponde a "Write" perde edições feitas com "Edit" ou "MultiEdit".

Quatro coisas que realmente importam

1. Escopo — Global vs. nível de projeto é a primeira decisão.

2. Convenções de colocação — Skills precisam de SKILL.md, agentes vão em agents/.

3. Conteúdo vs. orquestração — Skills, agentes, configurações, hooks e MCP não são conceitos equivalentes.

4. Sinais de deriva — A documentação muda rápido. Se sua configuração parou de funcionar, verifique se as convenções subjacentes mudaram.

A pasta .claude combina escopo, estrutura e comportamento. Uma vez internalizado esse modelo de três camadas, a pasta deixa de parecer bagunça escondida e passa a parecer um mapa operacional.