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.

Atualização: um critério prático para ler notícias de IA

A versão em inglês acrescenta mais filtros: comece pela fonte primária, depois veja a reprodutibilidade e só então avalie o impacto em um fluxo de trabalho real. Um número grande, uma captura de tela ou uma frase viral não bastam. Pergunte: a capacidade funciona de forma estável? O que acontece quando falha? Há documentação oficial, artigo técnico, página de produto ou demonstração verificável? Em uma equipe, também precisa ficar claro quem revisa, quem publica e quem assume o custo do erro.

O objetivo não é perseguir todo boato de IA, mas transformar informação em decisão útil: escolher ferramentas, ajustar processos e reduzir riscos.